Interfaces are the physical and logical channels over which communication takes place, such as BLE, WiFi and UART. Protocols define how messages are encoded and sent over those channels.
Summary
| Interface | Lower-layer (LL) protocol(s) | Application (App) protocol |
|---|---|---|
| WiFi | TCPIP, etc. | HTTP/REST ↔ RICREST |
| WiFi | WebSocket/RICSerial | Any App protocol, such as ROSSerial |
| BLE | RICSerial | Any App protocol, such as ROSSerial |
| Raw UART | RICSerial | Any App protocol, such as ROSSerial |
| I2C | I2C | Hardware dependent |
| USB UART | Human-readable 7-bit ASCII serial; ProtocolOverASCII with the 8th bit set | Serial terminal; RICREST GET immediate mode; ESP32 bootloader programming; ProtocolOverASCII |
Interfaces
RIC provides the following interfaces:
- 1 × USB UART: programming, diagnostics, RICREST GET commands in immediate mode, and ProtocolOverASCII.
- 1 × Raw UART: a general-purpose interface using RICSerial (LL), with any App protocol as its payload.
- 2 × I2C: specialised protocols depending on the connected hardware, such as SmartServos and IMUs.
- BLE: a general-purpose interface using RICSerial (LL), with any App protocol as its payload.
- WiFi:
- HTTP: a REST interface supporting the RICREST App protocol.
- WebSockets: a general-purpose interface using RICSerial (LL), with any App protocol as its payload.
Protocol levels and groups
The protocol levels used here are broadly consistent with the ISO-OSI model:
- LL (Lower Layer): protocols below the application layer that move data and provide flow control, integrity checks and similar functions.
- App (Application): protocols that convey top-level messages between applications, such as an iPad app and the firmware.
RIC uses the following protocols:
RICSerial (LL)
RICSerial can be used over any point-to-point, 8-bit serial interface and can carry a variety of payloads, including ROSSerial (App) and RICREST. Its goal is to provide a consistent protocol across interfaces. Because some interfaces are more capable than others, it uses a lowest-common-denominator approach.
RICSerial is based on HDLC and assumes at least an 8-bit serial connection. It uses start and end codes, escaping all other transmitted codes so they cannot be mistaken for the start or end of a message. A CRC allows message validity checks at this level.
RICFrame (LL)
RICFrame is similar to RICSerial, but is used when the lower layer already provides framing. RICSerial is almost always used instead, because many network transports split frames and RICSerial ensures they are reassembled.
RICJSON (LL)
RICJSON is simpler than RICFrame: each message contains only JSON ASCII data, with no overhead. It can only be used when there is no risk of packets being split.
RAWCMDFRAME (LL)
RAWCMDFRAME contains only the raw bytes sent to or from the application.
ROSSerial (App)
ROSSerial is a protocol defined as part of ROS1. It is used to publish data from the robot.
RICREST (App)
RICREST resembles a web REST interface. It makes commands, such as setting WiFi credentials and basic robot motion, available in a human-readable format. In addition to standard GET semantics, it supports POST, file transfer and streaming.
BLE
The BLE interface provides only the RICSerial protocol. It has a single GATT service with two main characteristics:
- Tx: sends RICSerial data.
- Rx: receives RICSerial data.
WiFi
WiFi supports:
- HTTP over TCP: RICREST, similar to a web REST protocol.
- WebSockets over TCP: RICSerial (LL) as standard, with any App payload.
Raw UART
This serial interface is intended for connection to a more powerful control computer, such as a Raspberry Pi. It uses the RICSerial (LL) protocol.
USB UART
The USB interface passes through a CP2102N USB-to-serial converter. It can be used with a terminal emulator for human-readable communication, or with dedicated serial software such as ESP IDF flash programming software.
Typical uses are:
- ESP32 reprogramming, with auto-reset circuitry.
- Diagnostics.
- Immediate mode commands: the subset of RICREST commands that can be sent using HTTP GET. Immediate mode uses only the request URL element. For example, the URL below can be executed in immediate mode by typing filerun/no.raw. Other useful commands include setting WiFi credentials.
- ProtocolOverASCII: uses the same USB UART, with the 8th bit of each byte set. That bit is always clear for plain ASCII. This allows USB UART to support RICSerial directly.
http://<ipaddress>/filerun/no.raw
I2C
I2C is not expected to be used for higher-level communication with RIC. It is used to control and read subsystems such as smart servos, the accelerometer and power level sensors.