raina
Protocol Specification

Raina Link Protocol (RLP v1)

Binary socket transport specification between microcontrollers and the Raina Gateway.

Design Goals

RLP was designed specifically to eliminate the overhead of MQTT and HTTP on low-power IoT controllers (ESP8266, ESP32, STM32, RP2040):

  • Zero Broker Overhead: Connects directly via persistent TCP/TLS stream.
  • Numeric Channel Mapping: Variable names are mapped to 16-bit numeric channels in the initial HELLO handshake. Subsequent telemetry transmissions use only 2 bytes per variable.
  • Zero Dynamic JSON Allocations: Packets are encoded in raw binary format, eliminating heap fragmentation.

1. Network Ports

PortTransportTarget Environment
9000Raw TCP (Plaintext)Local development, LAN, or VPN-secured microcontrollers
8883TLS 1.2 / 1.3Production internet deployments with CA verification

2. Frame Header Format (4 Bytes)

Every packet begins with a standard 4-byte header:

+-------------+-------------+---------------------------+
| Type (1B) | Flags (1B) | Length (2B, Big-Endian) | Header (4 Bytes)
+-------------+-------------+---------------------------+
| Payload (0 to 65535 Bytes) |
+-------------------------------------------------------+

3. Packet Types

OpcodeNameSenderDescription
0x01HELLODeviceInitial authentication with deviceId, token, and channel map.
0x02WELCOMEServerAuthentication accepted; acknowledges device session.
0x03DATADeviceSingle metric telemetry update.
0x04BATCHDeviceMulti-metric batch update sent in a single atomic transmission.
0x05COMMANDServerDownlink actuator command to device with unique 32-bit Command ID.
0x06ACKDeviceConfirmation acknowledging COMMAND execution.
0x07PINGBothHeartbeat liveness check with nonce.
0x08PONGBothHeartbeat reply mirroring PING nonce.