Rules and Mechanism for Mapping PX2/EMX-IDL to JSON-RPC


PX2/EMX devices provide a remote interface. The interface is a REST architecture and utilizes JSON-RPC version 2.0 for formatting messages sent to and received from the device. This document defines how formal PX2/EMX-IDL is mapped to JSON-RPC.

Mapping Rules

Type Mapping

IDL types are mapped to JSON value types as follows:

IDL Type JSON Representation
boolean true or false
int number
long number
float number
double number
string string
time number containing number of seconds since the start of the Unix epoch (midnight UTC of January 1, 1970)
enumeration number representing the index of the enumeration value (0-based)
structure object containing one element per structure member
vector array
map array of objects, each containing two elements: 'key' for the entry's key, 'value' for the entry's value.
interface object containing two elements: 'rid' contains the object identifier, 'type' contains the most derived interface type

Interface version Mapping

Interface versions as specified in IDL-File (e.g. NumericSensor_1_0_1) are not mapped to the protocol as such as interface identifiers are not directly part of any protocol message. However, the interface version is part of the type information which is sent along with object references. Clients may use type information and hence version information to select a compatible proxy for a received object reference.

Interface changes between firmware releases are documented in the file Changelog.txt.

Method Mapping

IDL method calls are mapped to JSON-RPC as follows:

In JSON-RPC Request:

Example (net.Net.setNetworkConfigLan):

"jsonrpc": "2.0",
"method": "setNetworkConfigLan",
"params": {
"speed": 2,
"duplex": 0,
"id": 123

In JSON-RPC Response:

Example (result from devsettings.Snmp.getConfiguration):

"jsonrpc": "2.0",
"result": {
"v2enable": true,
"v3enable": false,
"readComm": "public",
"writeComm": "",
"sysContact": "",
"sysName": "",
"sysLocation": ""
"id": 456

Call Execution

PX2/EMX-JSON-RPC uses HTTP-POST or HTTPS-POST requests. The JSON-RPC request is put into POST data, the JSON-RPC response is delivered in the HTTP/HTTPS response.

The HTTP URL includes an object reference which uniquely identifies a resource that implements a particular IDL interface. There are well-known references that must be used in initial requests. All well-known object references are defined in the file Well-Known-URIs.txt.

JSON-RPC responses may contain references to other objects. References returned by the device are "opaque", they do not use the well-known name. The 'rid' element of those opaque references must be used as URI in requests directed to the referenced resource.


All RPC calls must be authenticated with valid user credentials. PX2/EMX supports two methods for passing those credentials:

Basic Authentication

For HTTP basic authentication the user name and password must be included in the Authorization header of every HTTP request. The contents of the header line must be the keyword Basic followed by a base64-encoded string containing the user name and password, separated by a colon. For instance, to authenticate a request with the default login admin/raritan the following header must be sent:

Authorization: Basic YWRtaW46cmFyaXRhbg==

Session Authentication

For Session-based authentication the client contacts the session manager at /session to open a new session. The initial newSession request must be sent with basic authentication. The server generates a 128-bit session token and sends it to the client. Subsequent requests can be authenticated by including a X-SessionToken HTTP header with the secret session token:

X-SessionToken: 9e520dc84533342cd034b49550969e7f

The session token remains valid until the session expires or is closed. A session expires 30 seconds after the last request.

Bulk RPC

For complex client programs which perform a great number of requests it is not feasible to send a separate HTTP request for every JSON-RPC method call. There is a significant performance overhead, particularly when using HTTPS. To reduce that overhead it is possible to combine multiple JSON-RPC requests into a single HTTP request using the BulkRequest interface at /bulk.

A bulk request is performed by calling the performBulk method with a vector of resource IDs and JSON-RPC request objectss. The method returns a list of HTTP status codes and JSON-RPC response objects.

Example (sent to https://my-device/bulk):

"jsonrpc": "2.0",
"method": "performBulk",
"params": {
"requests": [
// First request: Firmware::getVersion()
{ "rid": "/firmware",
"json": { "jsonrpc": "2.0", "method": "getVersion", "params": {}, "id": 1 } },
// Second request: EventLog::clear()
{ "rid": "/eventlog",
"json": { "jsonrpc": "2.0", "method": "clear", "params": {}, "id": 2 } }
"id": 123


"jsonrpc": "2.0",
"result": {
"responses": [
// First response: HTTP 200 (OK), firmware version
{ "statcode": 200,
"json": { "jsonrpc": "2.0", "result": { "_ret_": "" }, "id": 1 } },
// Second response: HTTP 200 (OK), no return value
{ "statcode": 200,
"json": { "jsonrpc": "2.0", "result": null, "id": 2 } }
"id": 123

The Java language binding uses bulk RPC by default when using the asynchronous API. The Perl und Python bindings do not support bulk RPC yet.