Skip to main content

Wire Protocol

OpenRoIS carries the RoIS interfaces as JSON-RPC 2.0 messages over WebSocket. RoIS 2.0 leaves transport open, and this mapping is the concrete choice OpenRoIS makes. It is what lets browsers, Unity, and any language with a WebSocket client act as a RoIS service application.

Messages​

KindDirectionShape
RequestApplication to gateway{"jsonrpc": "2.0", "id": 1, "method": "rois.query.query", "params": {...}}
ResponseGateway to application{"jsonrpc": "2.0", "id": 1, "result": {"return_code": "OK", ...}}
NotificationGateway to application{"jsonrpc": "2.0", "method": "rois.event.notify_event", "params": {...}}

Every result carries a RoIS return_code: OK, ERROR, BAD_PARAMETER, UNSUPPORTED, OUT_OF_RESOURCES, or TIMEOUT. A RoIS-level failure is a normal response with a return code other than OK. A JSON-RPC error object signals an internal error of the gateway.

Applications connect to the gateway on any path, for example ws://host:8765/. Adapters connect on /adapter.

Method Catalog​

The status column shows what the current engine implements. Methods marked Planned are part of the specification and on the roadmap.

System Interface​

MethodParamsResultStatus
rois.system.connectnonereturn_codeAvailable
rois.system.disconnectnonereturn_codeAvailable
rois.system.get_profileconditionreturn_code, profileAvailable
rois.system.get_error_detailerror_idreturn_code, resultsAvailable

Command Interface​

MethodParamsResultStatus
rois.command.searchcondition (matched against the refs, case-insensitively, as a substring or a glob)return_code, component_ref_listAvailable
rois.command.bindcomponent_refreturn_codeAvailable
rois.command.bind_anyconditionreturn_code, component_refAvailable
rois.command.releasecomponent_refreturn_codeAvailable
rois.command.set_parametercomponent_ref, parametersreturn_codeAvailable
rois.command.get_parametercomponent_ref, names (optional, all when omitted)return_code, resultsAvailable
rois.command.executecomponent_ref, command_unit_listreturn_code, command_idAvailable
rois.command.get_command_resultcommand_idreturn_code, resultsAvailable

Query Interface​

MethodParamsResultStatus
rois.query.querycomponent_ref, query_type, conditionreturn_code, resultsAvailable

Event Interface​

MethodParamsResultStatus
rois.event.subscribecomponent_ref, event_type, conditionreturn_code, subscribe_idAvailable
rois.event.unsubscribesubscribe_idreturn_codeAvailable
rois.event.get_event_detailevent_idreturn_code, resultsAvailable

Streaming Interface​

Streaming has no JSON-RPC methods of its own. AudioStreaming and VideoStreaming are ordinary components, so an application controls a stream with the methods above: connect_stream, disconnect_stream, suspend_stream, and resume_stream are commands sent with rois.command.execute, get_stream_status is a query, and notify_stream_status is an event to subscribe to. The engine answers any rois.stream.* method with the JSON-RPC error METHOD_NOT_FOUND.

No streaming component ships yet. Media is Planned on the roadmap.

Notifications​

MethodCarriesStatus
rois.event.notify_eventevent_id, event_type, subscribe_id, expire, results (the payload, an OpenRoIS extension that saves one get_event_detail call)Available
rois.system.profile_changednone (OpenRoIS extension: refresh the profile)Available
rois.command.completedcommand_id, statusAvailable
rois.system.notify_errorerror_id, error_typeAvailable

Data Types​

Result and Parameter share one shape. Values are always strings, as in the RoIS IDL, and typed models per component give them structure in the SDKs.

{ "name": "target_positions", "data_type_ref": "string[]", "value": "[\"kitchen\"]" }

Component status values: UNINITIALIZED (0), READY (1), BUSY (2), WARNING (3), ERROR (4). The component_status query returns the numeric form.

Completed status values: OK, ERROR, ABORT, OUT_OF_RESOURCES, TIMEOUT.

A Complete Session​

Discover Components​

Request
{ "jsonrpc": "2.0", "id": 1, "method": "rois.system.get_profile", "params": {} }
Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"return_code": "OK",
"profile": {
"identifier": { "authority": "OpenRoIS", "code": "Engine", "codebook_ref": "", "version": "" },
"sub_engine_ids": ["robot_1"],
"component_ids": ["robot_1/Navigation"],
"component_profiles": [
{
"identifier": { "authority": "OpenRoIS", "code": "Navigation", "codebook_ref": "", "version": "" },
"name": "Navigation",
"function": "actuation",
"command_profiles": [{ "name": "start" }, { "name": "stop" }, { "name": "set_parameter" }],
"query_profiles": [{ "name": "component_status" }],
"event_profiles": [{ "name": "reached_target" }],
"parameter_profiles": [{ "name": "target_positions", "data_type_ref": "string[]" }]
}
]
}
}
}

Subscribe to an Event​

Request
{
"jsonrpc": "2.0", "id": 2, "method": "rois.event.subscribe",
"params": { "component_ref": "robot_1/Navigation", "event_type": "reached_target", "condition": "" }
}
Response
{ "jsonrpc": "2.0", "id": 2, "result": { "return_code": "OK", "subscribe_id": "sub-3f2a91c0" } }

Reserve and Command a Component​

Request
{ "jsonrpc": "2.0", "id": 3, "method": "rois.command.bind", "params": { "component_ref": "robot_1/Navigation" } }
Response
{ "jsonrpc": "2.0", "id": 3, "result": { "return_code": "OK" } }

If another application already holds the reservation, the result is {"return_code": "OUT_OF_RESOURCES"}.

Request
{
"jsonrpc": "2.0", "id": 4, "method": "rois.command.execute",
"params": {
"component_ref": "robot_1/Navigation",
"command_unit_list": [
{
"component_ref": "robot_1/Navigation",
"command_type": "start",
"arguments": [{ "name": "target_positions", "data_type_ref": "string[]", "value": "[\"kitchen\"]" }]
}
]
}
}
Response
{ "jsonrpc": "2.0", "id": 4, "result": { "return_code": "OK", "command_id": "nav-1" } }
Implementation note

RoIS allows a CommandUnitSequence to combine sequential commands with concurrent groups. The engine runs the whole sequence: its items in order, and the branches of a ConcurrentCommands item in parallel. A command that fails aborts the rest of its branch and every later item. The engine assigns every command id itself and returns the sequence with the ids filled in. See Commands, Ids and Status.

Receive an Event​

Notification
{
"jsonrpc": "2.0",
"method": "rois.event.notify_event",
"params": {
"event_id": "8b0c6d1e-5f4a-4b2e-9d3c-1a2b3c4d5e6f",
"subscribe_id": "sub-3f2a91c0",
"event_type": "reached_target",
"expire": "",
"results": [
{ "name": "target", "data_type_ref": "string", "value": "kitchen" },
{ "name": "is_final_target", "data_type_ref": "bool", "value": "true" }
]
}
}

Streaming​

A streaming component (AudioStreaming, VideoStreaming) is driven through the messages its normative profile declares: connect_stream, disconnect_stream, suspend_stream, and resume_stream are its commands, get_stream_status its query, and notify_stream_status its event. connect_stream answers a stream_id and, in its results, whatever the transport needs to attach to the media, for example a media URL or an SDP answer. An application follows the stream by subscribing to notify_stream_status, which arrives as rois.event.notify_event like any other event. The media itself never crosses the gateway: it flows on the data plane between the application and the component's host. See media.

Gateway to Adapter​

The gateway speaks the same JSON-RPC methods to adapters, over the connection that each adapter opens on /adapter. When an adapter connects, the gateway sends rois.system.get_profile to learn its engine identifier and components, then forwards queries, commands, and subscriptions to it. Adapters push rois.event.notify_event notifications, which the gateway delivers to the subscribed applications.