Table of Contents

RICREST is one of the two main transport protocols supported by RIC; the other is ROSSerial. Both can be wrapped by the RICSerial and RICFrame protocols.

RICREST is a form of HTTP REST protocol. It has some limitations, depending on the interface, to suit the channel carrying it. See Interface support below.

The RICREST payload is often plain text, but it can also carry binary data, such as HTTP body or file-upload information.

Interface support

The REST API supports the following interfaces:

  • WiFi + HTTP: the classic REST protocol.
    • REST GET with a string request and response.
    • REST POST using media encoding types including binary and JSON.
    • HTTP file transfer in both directions.
  • SerialConsole:
    • Minimal GET support using only the URL part of a GET request, with a string response returned to the console.
  • BLE and TCP socket over RICSerial:
    • GET with a string request and response.
    • POST with binary and JSON payloads.
    • File transfer.

RESTElementCode

The first byte of a RICREST packet is the RESTElementCode, which determines the format of the rest of the message.

For a standard REST API command, the RESTElementCode is 0x00. The remaining message is a null-terminated string containing the REST command. The http://…/api prefix is removed before the command is sent over RICREST.

RESTElementCode (byte 0) Meaning Remainder of message
0x00 URL Null-terminated string containing the URL element of a REST API call.
0x01 CmdRespJSON Null-terminated string used for responses. See CmdRespJSON properties below.
0x02 Body uint32_t index
uint32_t total
uint8[] binary data — length determined by the overall message length.
0x03 CommandFrame Null-terminated string containing a JSON object with these properties: cmdName (mandatory), fileName, fileType, fileLen, fileCRC, reqStr, batchAck. See CommandFrame properties below.
0x04 FileOrStreamBlock uint8_t streamID (0 = ANY; 1..255 = numbered stream)
uint24_t file position in bytes
uint8[] binary data — length determined by the overall message length.

CmdRespJSON properties

Property name Values / description
rslt Result of the operation: ok or fail.
req Original REST command from the request.
error If present, the error string for the command.
okto In file transfers, the filePos successfully reached in the received messages.
sokto For sockets, the streamPos successfully received and accepted into the stream.

CommandFrame properties

The CommandFrame uses JSON format.

Property name Valid for cmdName Values / description
cmdName All Defines the sub-command:
ufStart — file upload start
ufEnd — file upload end
ufCancel — file upload cancel
ufStatus — status information
fileName ufStart, ufEnd, ufCancel Name of the file being uploaded.
fileType ufStart, ufEnd Type of file: general or ricfirmware.
fileLen ufStart, ufEnd Length of the file.
blockCount ufEnd Number of blocks sent.
reqStr ufStart, ufEnd, ufCancel REST API endpoint being used, generally fileupload or espfwupdate.
batchAck ufStart 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 started
OTAStartFailed — robot failed to start the OTA process
OTAStartedOK — robot started the OTA process
failRetries — robot failed to acknowledge a block after retries
failTimeout — robot reached the overall file-upload timeout