JSON-RPC Protocol Overview

Introduction

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

JSON-RPC has the following characteristics:

• Simplicity: Uses JSON as the data exchange format, which is simple, easy to understand, and easy to parse.
• Lightweight: It uses a text-based JSON format for data exchange, with simple data and protocol structures, resulting in small data sizes, fast network transmission, and high performance.
• Cross-language and Cross-platform: JSON-RPC supports communication between different programming languages (such as C++, Python, etc.) and platforms.
• Support for multiple transport protocols: JSON-RPC can use various transport protocols, including HTTP, TCP Socket, WebSocket, etc., making it suitable for diverse network environments.
• Error handling: JSON-RPC defines error objects and error codes, allowing clients to debug and handle issues based on the error information returned by the server.

JSON-RPC follows a request-response model for remote procedure calls between clients and servers. The client sends a JSON-formatted request to the server, such as { "jsonrpc": "2.0", "method": "getRobotNames", "params": [], "id": 1 }. The server receives the request, parses the JSON object, extracts values for the "method", "params", and "id" fields, and executes the method corresponding to the "method" name with the provided parameters. Based on the execution result, the server generates a response object, serializes it into JSON format, and sends it back to the client. The client receives the server's response.

Supported Transport Protocols and Port Numbers

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

Protocol	Port Number
TCP Socket	30004
HTTP	9012
WebSocket	9012

JSON-RPC 2.0 Specification

Request Object

An RPC request object contains the following members:

• jsonrpc: Indicates the version of the JSON-RPC protocol. It must be "2.0".
• method: The name of the method to be called. It is a string.
• params: The parameters passed to the method. It is a structured value.
• id: A unique identifier.

Response Object

There are two types of RPC response objects: one for successful RPC calls and one for failed RPC calls.

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

   • jsonrpc: Indicates the version of the JSON-RPC protocol. It must be "2.0".
   • result: The return value from the method executed.
   • id: The identifier, which must match the identifier in the request object.

2. When the RPC call fails, the response object contains the following members:

   • jsonrpc: Indicates the version of the JSON-RPC protocol. It must be "2.0".
   • error: An error object containing the following members:
     • code: The error code.
     • message: A brief description of the error.
     • data: Additional information about the error (this may be ignored).
   • id: The identifier, which must match the identifier in the request object.

The error codes are as follows:

Error Code	Message	Description
-32700	Parse error.	Invalid JSON received. An error occurred while 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 or is not available.
-32602	Invalid params.	Invalid method parameters.
-32603	Internal error.	Internal JSON-RPC error.
-32099..-32000	Server error.	Reserved for server errors defined by the implementation.

Example

Here is an example of using WebSocket protocol for transmission in Python:

(Assuming localhost is the robot's IP address)

import json
import websocket

# WebSocket server address
server_address = "ws://localhost:9012"

# Create WebSocket connection
ws = websocket.create_connection(server_address)

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

# Convert the request to 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 Output:

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