Introduction to JSON-RPC Protocol

Introduction

JSON-RPC (JavaScript Object Notation Remote Procedure Call) is a remote procedure call protocol. It uses JSON as the data format and can communicate between clients and servers through transport protocols such as TCP Socket, HTTP, and WebSocket.

JSON-RPC has the following characteristics:

• Simplicity: Use JSON as the data exchange format, which is concise, easy to understand, and easy to parse.
• Lightweight: Use a text-based JSON format for data exchange, with simple data and protocol structures, bringing small data transmission size, fast speed, and high performance.
• Cross-language and cross-platform: The JSON-RPC protocol supports communication between multiple programming languages (such as C++ and Python) and different platforms.
• Multiple transport protocols supported: The JSON-RPC protocol can use various transport protocols for data transmission, such as HTTP, TCP Socket and WebSocket, making it suitable for various network environments.
• Error handling: The JSON-RPC protocol defines the specifications for error objects and error codes, allowing the client to perform debugging and handle issues based on the error information returned from the server.

The JSON-RPC protocol implements remote procedure calls between the client and the server by the request-response method. The client sends a JSON formatted request to the server, for example {"jsonrpc":"2.0","method":"getRobotNames","params":[],"id":1}. After receiving the request, the server parses the JSON object and extracts the values of fields such as "method", "params", and "id". The server executes the method corresponding to "method" and uses the provided parameters. Based on the execution result, the server generates a response object, serializes the response object into JSON format, for example {"id":1,"jsonrpc":"2.0","result":["rob1"]}, and then sends the JSON formatted response to the client. Finally, the client receives the response transmitted from the server.

Supported Transport Protocols and Port Numbers

The RPC function module in the AUBO SDK supports TCP Socket, HTTP, and WebSocket transport protocols, with the corresponding port numbers as follows:

Protocol	Port number
TCP Socket	30004
HTTP	9012
WebSocket	9012

JSON-RPC 2.0 Specifications

Request Object

The RPC request object contains the following members:

• jsonrpc: The version number of the JSON-RPC protocol, being a fixed value of 2.0

• method: The name of the method being called, being a string

• params: The parameter value, being a structured value

• id: Identifier

Response Object

Success and failure of RPC calls are described below:

1. When the RPC call is successful, the RPC response object contains the following members:

   • jsonrpc: The version number of the JSON-RPC protocol, being a fixed value of 2.0
   • result: The return value of the executed function
   • id: Identifier, which must be the same as the identifier of the request object

2. When an error occurs during the RPC call, the RPC response object contains the following members:

   • jsonrpc: The version number of the JSON-RPC protocol, being a fixed value of 2.0
   • error: The error object, which contains the following members
     • code means the error code
     • message means a brief error description
     • data means additional information about the error, which may be ignored.
   • id: Identifier, which must be the same as the identifier of the request object

The error codes of the error object are shown in the table below:

Error code	Message	Description
-32700	Parse error.	The server receives invalid JSON. An error occurs while the server was parsing the JSON text.
-32600	Invalid Request.	The sent JSON is not a valid request object.
-32601	Method not found.	The method does not exist/unavailable.
-32602	Invalid params.	Invalid method parameters.
-32603	Internal error.	JSON-RPC internal error.
-32099..-32000	Server error.	It is reserved for implementation-defined server errors.

Example

An example of websocket protocol transmission written in Python is as follows:

localhost is the IP address of the robot

import json
import websocket

# WebSocket Server Address
server_address = "ws://localhost:9012"

# Create the WebSocket Connection
ws = websocket.create_connection(server_address)

# Construct the JSON-RPC Request
request = {
    "jsonrpc": "2.0",
    "method": "getRobotNames",
    "params": [],
    "id": 1
}

# Convert the Request into a JSON String
request_json = json.dumps(request)

# Send the Request
ws.send(request_json)

# Receive the Response
response_json = ws.recv()

# Parse the Response
response = json.loads(response_json)

print("Received Response:", response)

# Close the WebSocket Connection
ws.close()

Program running result:

Received Response: {'id': 1, 'jsonrpc': '2.0', 'result': ['rob1']}