RI Title
RI logo

RI Remote Interface (RIRI) protocol



1. INTRODUCTION

RI Remote Interface (RIRI) protocol defines a lightweight message based protocol for communication between objects via reliable stream mechanisms such as sockets or pipes.


2. DESCRIPTION

RIRI describes a bidirectional Communications protocol between two peer objects over a reliable byte stream. RIRI does not define how the stream is created. While the protocol is peer to peer it is easier to consider a client server model where one of the RIRI communications objects is the master/server and the second the slave/client.

RIRI defines a message structure, how the message is broken into packets, how the packets are sent between RIRI endpoints.

An RIRI endpoint is the object which manages the stream, assembles packets and notifies user objects on message receipt. It's basic structure in an object table and an replyEvent table. In order to receive messages an object must be in the object table. These objects can be created locally or by the opposite endpoint via the createObject command. The replyEvent table holds events which are triggered by the receipt of a reply sent to an object stored in the opposite endpoints objectTable. Events are stored in pairs, one for a normal reply and one for an error reply.

Messages are structured sets of values sent either to an object or to an event. RIRI allows for some very complex and large message structures.

To convert the underlying stream connection to an message based connection RIRI provides a very light weight packet encapsulation method. It uses a 6 byte header to accomplish this. Headers are shown within (). The size bytes of the header are not always shown but must always be present.

The payload of each packet can be 0 to 65530 bytes. If a larger payload is required it can be transmitted as multiple 'chained' payloads (see example below).

3.0 MESSAGE SYNTAX

RIRI messages are actually one or more sub-messages where each sub-message is an array of binary bytes. For documentation purposes sub-messages are shown enclosed by [].

The actual structure is up to the application, but RI uses some standard structures to minimize duplication.

3.1 RIRI submessage structure

Messages take the general form of:
[^parameter^parameter^...][^parameter^parameter^...][byteStream]...
Where [] denote submessage boundaries. Submessages always start with a 6 header.

The protocol on the socket determines the general structures allowed and the source and target objects determine the message formats.


3.1.1 Binary submessage structure
Within a Binary message field all bytes are assumed to be data and no structure is assumed. A binary submessage is shown as [byteStream].

3.1.2 Raw ASCII submessage structure
A commonly used submessage format is the ASCII format. In an ASCII message all data must be one byte per character and must not use the values reserved for separators. RIRI ASCII submessages use 4 non printing ASCII control characters to indicate separations. Separators are represented by ^ (16r1C)for first level and + (16r1D)for second level ~ (16r1E) third and / (16r1F) fourth. ^ + ~ / are only used to show the separator in documentation, they do not appear in the submessage itself. Leading separators are optional unless the first entity is empty in which case there will be two leading separators (e.g. ^^AS. A trailing separator indicates an additonaly empty entry at the end.

RI has tools for the parsing of such structures and so uses them for most of its protocols.

Some definitions:
Command is the first parameter and consists of a command string
optionally followed by a 16r1D separator and 1 or more keyName=value pairs
separated by 16r1Ds. These are referred to as command attributes.

Key=Value
Keys are stored case sensitive but compared case insensitive. Keys may not include '='
Value use of case is up to the application. Values may not include ';'
Within a value an semicolon is used to separate multiple values into a list

KeyList is keyName+keyName...

KeyValList is keyName=keyValue+keyName=keyValue...

ValList is val11+val12...^val21+val22..
an empty string is allowed for the value.
a empty leading value is shown as ++val1+val2...

3.2 MESSAGE EXAMPLES

3.2.1 MESSAGES SUPPORTED BY objectTable key = 255
The following messages can be sent the communications manager ( cmd = 3, cmdKey = 255 )

-Attribute Query: [^AQ^AttrName+...] ==> [KeyName=KeyValue+ ...]
Queries Socket Attributes

Current Supported Attributes
loopback=aInteger Seconds between connection check
protocol=riri1.0

Error responses
error=100+reason=Attr not Supported

-Attribute Set: [^AS^AttrName+...] ==> [KeyName=KeyValue+ ...]
Sets Socket Attributes

Current Supported Attributes
loopback aInteger Seconds between connection check
protocol the type and version used (riri1.0)

Error responses
error=100+reason=Attr not Supported

4. PACKET HEADER SYNTAX
To separate a reliable stream into messages RI has chosen a 6 byte header for each packet.

Header syntax: (Cmd cmdKey ReplyCmd ReplyKey byteCntHi byteCntLo)

Where each item listed above represents one byte for a total of 6 bytes
Cmd This is the command which the receiving endpoint is to perform.
The choices are listed in the table of commands

cmdKey Some commands require a key to indicate which entity (object or replyEvent)
is to be used as a target for the command. If not used set to binary 0.

ReplyCmd
This becomes the Cmd for the reply.
A special case is in the case of an error in which case the ReplyCmd is converted to a ReplyError
If no reply is desired set to binary 0.

ReplyKey
This becomes the Key for the reply. If not used set to binary 0.

ByteCnt is the number of bytes in the packet not including the header

4.1 Header Commands

-No Op: cmd = 0
No action is requested. Usually used as a replyCmd when no
reply is desired.

-Create Object: cmd = 1
Create an object, return its objectKey

-Destroy Object: cmd = 7
Destroy the object at objectKey = Key

-Send Message to Object: cmd = 3
Send the message to the object at Key.

-Cancel Reply: cmd = 13
Cancel the reply from a send message command. The Key
is the eventKey to be cancelled.

-Trigger Event: cmd = 4
Send the message to the eventKey equal to Key.

-Trigger Error Event: cmd = 8
Sends the message to the error handler at eventKey = Key

-Log message: cmd = 5
Display a message for the operator or place it into to local log file

-Close: cmd = 255
Close the stream connection

-Loopback: cmd = 6
Echo the message back

-Connection Test: cmd = 15
Exchange random data for connection test

-Authenticate: cmd = 14
Used as part of connection verification

-Challenge: cmd = 16
Used as part of the optional connection verification

-Encrypt challenge: cmd = 17
Used as part of optional verification

-Start Submessage: cmd = 2
Low level marker for the start of a new submessage.
Only necessary if a message is more than one submessage.

-Chain: cmd = 10
This header payload is to be chained with the submessage which
preceded it.
Used to allow submessages of size greater than 65000 bytes.


4.2 Header Examples

The syntax used shows the header as {cmd key replyCmd replykey } in decimal with the two trailing size bytes not shown.

4.2.1 Short single submessage
(C,K,RC,RK) first submessage and execute alternate
(10,K,RC,RK) Add to implied first submessage
(C,K,RC,RK) execute

4.2.2 Long single submessage
(2,K,RC,RK) first bytes
(10,K,RC,RK) append to first submessage
(C,K,RC,RK) append to submessage and execute

4.4.3 Multiple submessages
(2,K,RC,RK) start first submessage
(10,K,RC,RK) append to first submessage
(2,K,RC,RK) start second submessage
(C,K,RC,RK) append to second submessage and execute

Published: 03/04/2016 03:45:09 PM Modified: 11/16/2026 11:49:42 AM
Print Email Link
https://roos.com/docs/TDOO-A7QVUR
Roos Instruments CONFIDENTIAL AND PROPRIETARY
©2016-2026 Roos Instruments, Inc. All rights reserved.