RICREST Protocol
The RICREST protocol is one of two main transport protocols supported by RIC (the other being ROSSERIAL). Both RICRESET and ROSSERIAL can be wrapped by the RICSerial and RICFrame protocols.
RICREST is a form of HTTP REST protocol with some limitations (dependent on interface) to make it suitable for the interfaces on which it is carried - see Interface Support below.
The payload RICREST is often plain-text but RICREST can also carry binary payloads such as the body or file-upload information that is carried over HTTP.
Interface Support
The REST API supports the following interfaces:
WiFi + HTTP - the classic REST protocol.
Classic REST GET support with string request and response
REST POST support using media encoding types including binary and JSON
Supports HTTP file transfer in both directions
SerialConsole
Minimal GET support using just the url part of a get request and returning a string response to the console
BLE, TCP socket over RICSerial
GET support with string request & response
POST support with binary and JSON payloads
File transfer
RESTElementCode
The first byte of a RICREST packet is the RESTElementCode. This determines the type of the remainder of the message. For instance if the payload is just a standard REST API command (that might have been typed into a address bar on a browser for instance) then the RESTElementCode will be 0x00 and the remainder of the message is a null-terminated string with the REST command (note that the http://…/api element is stripped off before sending over RICREST).
RESTElementCode (byte 0) | Meaning | Remainder of msg |
|---|---|---|
0x00 | URL | string (null terminated) contains the URL element of a REST API call |
0x01 | CmdRespJSON | string (null terminated) used for responses see table below for contents and examples |
0x02 | Body | uint32_t index uint32_t total uint8[] binary data - length determined from overall message length |
0x03 | CommandFrame | string (null terminated) contains JSON object with properties: cmdName - mandatory fileName fileType fileLen fileCRC reqStr batchAck See table below for examples |
0x04 | FileOrStreamBlock | uint8_t streamID (0 = ANY, 1..255 = numbered stream) uint24_t file position in bytes uint8[] binary data - length determined from overall message length |
Properties in the CmdRespJSON formatted message
Property Name | Values/Description |
|---|---|
rslt | Result of operation: ok OR fail |
req | Original request REST command |
error | If present indicates error string for command |
okto | In file transfer indicates the filePos that has been successfully reached in the received messages |
sokto | For sockets this indicates the streamPos that has been received successfully and accepted into the stream |
Properties in the CommandFrame (JSON format)
Property Name | cmdName validity | Values/Description |
|---|---|---|
cmdName | all | Defines the sub-command ufStart - file upload start ufEnd - file upload end ufCancel - file upload cancel ufStatus - status info |
fileName | ufStart, ufEnd, ufCancel | name of file being uploaded |
fileType | ufStart, ufEnd | type of file: general ricfirmware |
fileLen | ufStart, ufEnd | length of file |
blockCount | ufEnd | number of blocks sent |
reqStr | ufStart, ufEnd, ufCancel | REST API endpoint being used - generally this will be: fileupload OR espfwupdate |
batchAck | ufStart | Used to specify the number of FileBlock messages that can be sent in a batch before an acknowledgement is required. |
reason | ufCancel, ufStatus | userCancel - user (or controller) cancelled notStarted - file upload has not been started OTAStartFailed - robot failed to start OTA process OTAStartedOK - robot started OTA process failRetries - robot failed to acknowledge block after retries failTimeout - robot overall timeout on file upload |