Protocol Specification

RadioKit uses a compact binary protocol which is transport-agnostic (works for BLE, Serial, WiFi, and Cloud). The protocol is designed for low-latency, reliable control with minimal overhead.

RadioKit runs five parallel protocols on the same physical transport, demuxed by start byte:

Start Byte	Protocol	Purpose
0x55	Widget Protocol	UI config, variable sync, reliability
0xAA	Filesystem Protocol	Bulk file operations (LittleFS)
0xBB	OTA Protocol	Over-the-air firmware updates
0xDD	Settings Protocol	Device config, auth, telemetry, features
0xEE	Print Protocol	Transport-agnostic console output

---

Widget Protocol (0x55)

Packet Structure

[START][LENGTH_LO][LENGTH_HI][CMD][PAYLOAD...][CRC_LO][CRC_HI]
  0x55    total      total

Field	Size	Description
START	1	Always 0x55
LENGTH	2	Total packet length including all fields
CMD	1	Command byte
PAYLOAD	0-N	Command-specific payload
CRC	2	CRC-16/CCITT-FALSE over CMD + PAYLOAD

Minimum packet size: 6 bytes (no payload).

Command Bytes

Value	Name	Direction	Description
0x01	GET_CONF	App -> Arduino	Request configuration descriptor
0x02	CONF_DATA	Arduino -> App	Configuration descriptor response
0x05	ACK	Both	Acknowledge reliable packet
0x06	GET_VARS	App -> Arduino	Request current variable state
0x07	VAR_DATA	Arduino -> App	Variable state response
0x08	VAR_UPDATE	Both	Reliable push of a single widget state
0x09	GET_META	App -> Arduino	Request widget metadata
0x0A	META_DATA	Arduino -> App	Metadata response
0x0B	META_UPDATE	Both	Reliable push of widget metadata
0x0C	SET_INPUT	Arduino -> App	Set state of an input widget from Arduino
0x1D	GET_WIFI_INFO	App -> Arduino	Request WiFi status
0x1E	WIFI_INFO_DATA	Arduino -> App	WiFi status payload

CONF_DATA (Configuration)

Sent in response to GET_CONF. Contains widget configuration for the UI.

Global Header

[ORIENT][WIDGET_COUNT][THEME_LEN][THEME...]

Field	Type	Description
ORIENT	uint8_t	0x00 = Landscape, 0x01 = Portrait
WIDGET_COUNT	uint8_t	Number of widget descriptors that follow
THEME_LEN	uint8_t	Length of theme identifier string
THEME	char[N]	Theme name (e.g., "default", "dark", "retro")

Note: Device name, description, and firmware version are no longer in CONF_DATA. They are retrieved via the Settings protocol’s GET_DEVICE_INFO command (0x08).

Widget Descriptor

Each widget is described by a fixed header followed by optional string data.

[TYPE][ID][X][Y][WIDTH][HEIGHT][ROT_LO][ROT_HI][STYLE][VARIANT][STR_MASK][STR_DATA...]

Field	Type	Description
TYPE	uint8_t	Widget type ID (see table below)
ID	uint8_t	Widget index (0-based, sequential)
X	uint8_t	Center X on virtual canvas (0-200)
Y	uint8_t	Center Y on virtual canvas (0-200)
WIDTH	uint8_t	Physical width in virtual units (0 = auto-aspect)
HEIGHT	uint8_t	Physical height in virtual units (0-200)
ROTATION	int16_t	Rotation in degrees (clockwise)
STYLE	uint8_t	Widget style (0=primary, 1=dim, 2=success, 3=warning, 4=danger)
VARIANT	uint8_t	Behavioral variation (e.g., spring mode, detent count)
STR_MASK	uint8_t	String bitmask (determines following string segments)

Widget Type IDs

ID	Widget	Description
1	PushButton	Momentary button
2	ToggleButton	Latching button
3	Slider	Linear slider (-100 to +100)
4	Joystick	2-axis joystick
5	LED	Status indicator
6	Text	Read-only text display
7	Multiple	Button group / select group
8	SlideSwitch	iOS-style toggle switch
9	Knob	Rotary knob (-100 to +100)
10	Telemetry	Display-only metrics

String Bitmask (STR_MASK)

Bits indicate which optional strings are included. Each active bit adds a [LEN][STR] pair to the STR_DATA block.

• Bit 0 (0x01): Label (primary display text)
• Bit 1 (0x02): Icon (standard name string)
• Bit 2 (0x04): OnText (for buttons)
• Bit 3 (0x08): OffText (for buttons)
• Bit 4 (0x10): Content (for Text widget initial value)
• Bit 5 (0x20): Extra (widget-specific binary configuration)
• Bit 6 (0x40): Label hidden (label is present but should be hidden)

Each string is encoded as: [LENGTH (1 byte)][UTF-8 DATA]

---

Runtime Communication

VAR_DATA (Full State Sync)

Sent in response to GET_VARS. Contains the current state of all widgets in ID order.

[DATA_W0][DATA_W1][DATA_W2]...

Each widget’s data is encoded according to its type:

Type	Widget	Data Bytes	Description
1	PushButton	1 byte	Current state (0/1)
2	ToggleButton	1 byte	Current state (0/1)
3	Slider	1 byte	Value (Signed int8, -100 to +100)
4	Joystick	2 bytes	X, Y values (Signed int8, -100 to +100)
5	LED	5 bytes	State (1), R, G, B, Opacity
6	Text	32 bytes	UTF-8 string (null-padded)
7	Multiple	1 byte	Selected item(s) (Bitmask)
8	SlideSwitch	1 byte	Current state (0/1)
9	Knob	1 byte	Value (Signed int8, -100 to +100)
10	Telemetry	32 bytes	UTF-8 string (null-padded)

SET_INPUT (Arduino -> App)

Sent by the Arduino to programmatically set the state of an input widget in the app (e.g., resetting a slider or toggle).

[ID][VALUE...]

Field	Type	Description
ID	uint8_t	Widget index
VALUE	variable	Type-specific value (see VAR_DATA table)

The app updates the widget UI immediately. Unlike VAR_UPDATE, this is not acknowledged.

VAR_UPDATE (Reliable Push)

Pushes a change for a single widget. Can be sent by either side:

• App -> Arduino: When user changes an input.
• Arduino -> App: When firmware programmatically changes a widget state

[ID][SEQ][DATA...]

Field	Type	Description
ID	uint8_t	Widget index
SEQ	uint8_t	Rolling sequence number (0-255)
DATA	variable	Type-specific value (see VAR_DATA table)

Reliability Logic

• The sender maintains a pending bitmask (32-bit) for unacknowledged updates
• Retransmission timeout: 500 ms
• Maximum retries: 5 attempts
• After 5 failures, the packet is dropped (fail-soft)
• The receiver sends ACK immediately upon receipt

ACK (Acknowledgment)

Confirms receipt of a reliable packet (VAR_UPDATE or META_UPDATE).

[SEQ]

Field	Type	Description
SEQ	uint8_t	Sequence number being acknowledged

META_DATA & META_UPDATE

Same format as VAR_DATA/VAR_UPDATE but for widget metadata (label, icon, etc.). Used when firmware changes widget appearance at runtime.

WIFI_INFO_DATA (Arduino -> App)

WiFi status response sent in response to GET_WIFI_INFO.

[IP0][IP1][IP2][IP3][MODE][SSID_LEN][SSID...][RSSI]

Field	Type	Description
IP	4 bytes	IP address (4 octets)
MODE	uint8_t	0x00 = STA, 0x01 = AP
SSID_LEN	uint8_t	Length of STA SSID
SSID	char[N]	Connected STA SSID
RSSI	int8_t	WiFi signal strength (dBm)

---

Settings Protocol (0xDD)

A dedicated protocol for device settings, authentication, telemetry, and configuration management. Uses a separate start byte (0xDD) and parallel state machine.

Frame Structure

[START][SUB_CMD][LEN_LO][LEN_HI][PAYLOAD...]
  0xDD   uint8     uint8   uint8   0..1024 bytes

No CRC — transport reliability is assumed.

Sub-Commands (App -> MCU)

Value	Name	Payload	Description
0x01	GET_TELEMETRY	(empty)	Request signal/battery status
0x02	BLE_INFO	(empty)	Request BLE connection details
0x03	GET_FEATURES	(empty)	Request feature bitmask
0x04	GET_CHIP_INFO	(empty)	Request chip model, flash, PSRAM
0x05	SET_CONF	[MASK(2 LE)][DATA...]	Update device config fields
0x06	PWD_AUTH	[PWD_LEN(1)][PWD(N)]	Authenticate with password
0x07	FACTORY_RESET	(empty)	Erase NVS and reboot
0x08	GET_DEVICE_INFO	(empty)	Request name, description, UID, icon
0x09	NVS_RAW_READ	[KEY_LEN(1)][KEY(N)]	Read raw NVS key
0x0A	NVS_RAW_WRITE	[KEY_LEN(1)][KEY(N)][VALUE(1)]	Write raw NVS key
0x0B	SET_WIFI	[MASK(2 LE)][DATA...]	Update WiFi credentials
0x0C	GET_CLOUD_INFO	(empty)	Request cloud relay config
0x0D	REBOOT	(empty)	Reboot device (NVS preserved)
0x0E	SET_CLOUD_INFO	[MASK(2 LE)][DATA...]	Update cloud relay config

Sub-Commands (MCU -> App)

Response = subCmd | 0x80.

Value	Name	Payload	Description
0x81	TELEMETRY_DATA	[RSSI][LATENCY][TS_LO][TS_HI]	Telemetry values
0x82	BLE_INFO_DATA	[INTERVAL(2 LE)][MTU(2 LE)][RSSI]	BLE connection details
0x83	FEATURES_DATA	[BITMASK(1)]	Feature capabilities
0x84	CHIP_INFO_DATA	[MODEL...][REV][CORES][FLASH(4)][PSRAM(4)][SDK...][MAC(6)]	Chip info
0x85	SET_CONF_ACK	[STATUS(1)]	Config update result
0x86	PWD_AUTH_ACK	[STATUS(1)]	Auth result (0=OK, 1=user, 2=denied)
0x87	FACTORY_RESET_ACK	[STATUS(1)]	Factory reset confirm
0x88	DEVICE_INFO_DATA	[PROTO_VER][NAME...][DESC...][UID...][ICON...]	Device info
0x89	NVS_RAW_READ_DATA	[STATUS][LEN][VALUE...]	NVS read result
0x8A	NVS_RAW_WRITE_ACK	[STATUS(1)]	NVS write result
0x8B	SET_WIFI_ACK	[STATUS(1)]	WiFi update result
0x8C	CLOUD_INFO_DATA	[URL_LEN][URL...][ACC_LEN][ACC...]	Cloud config
0x8D	REBOOT_ACK	[STATUS(1)]	Reboot confirm
0x8E	SET_CLOUD_INFO_ACK	[STATUS(1)]	Cloud config result

SET_CONF Field Mask

Bit	Field	Description
0	NAME	Device name string
1	DESC	Device description string
2	DEVICE_PWD	Device password (full access)
3	USER_PWD	User password (widgets-only)
4	ICON	Device icon name
7	ERROR	Error flag (set in response on failure)

FEATURES_DATA Bitmask

Bit	Feature	Description
0	OTA	Over-the-air updates supported
1	FILESYSTEM	LittleFS mounted and ready
2	HAS_DEVICE_PWD	Device password is set
3	HAS_USER_PWD	User password is set
4	WiFi	WiFi transport active
5	CLOUD	Cloud relay transport active
6	BLE	BLE transport compiled in
7	PRINT_STREAM	0xEE print stream supported

PWD_AUTH Status Codes

Value	Name	Description
0x00	DEVICE	Authenticated as device (full access)
0x01	USER	Authenticated as user (widgets-only)
0x02	DENIED	Password did not match

Auth Gate Rules

• Unauthenticated: Only GET_CONF, PWD_AUTH, GET_FEATURES, GET_DEVICE_INFO are allowed
• User-authenticated: Widget commands + most Settings commands, but cannot change device config, factory reset, or reboot
• Device-authenticated: Full access to all commands
• Serial bypass: Physical serial access implies full device-level authentication

---

OTA Protocol (0xBB)

Over-the-air firmware updates using ESP32’s Update library.

Frame Structure

[START][SUB_CMD][LEN_LO][LEN_HI][PAYLOAD...]
  0xBB   uint8     uint8   uint8   0..N bytes

Sub-Commands (App -> MCU)

Value	Name	Payload	Description
0x01	OTA_BEGIN	[SIZE(4 LE)]	Begin firmware update
0x02	OTA_CHUNK	[OFFSET(4 LE)][DATA...]	Write firmware chunk
0x03	OTA_END	[CRC32(4 LE)]	Finalize and verify
0x04	OTA_ABORT	(empty)	Abort current update
0x05	OTA_SET_ERASE_FLAG	[MODE(1)]	Set erase flag for next boot

Sub-Commands (MCU -> App)

Value	Name	Payload	Description
0x81	OTA_ACK	[STATUS(1)]	Operation result
0x82	OTA_PROGRESS	[RECEIVED(4 LE)][TOTAL(4 LE)]	Progress notification

OTA Error Codes

Value	Name	Description
0x00	OK	Success
0x01	NO_SPACE	Not enough flash space for firmware
0x02	FLASH	Flash write error
0x03	SEQ	Offset mismatch (chunk out of order)
0x04	INVALID_STATE	OTA not started or already finished
0x05	NOT_SUPPORTED	OTA not available on this platform

OTA Erase Modes

Value	Description
0x00	No erase
0x01	Erase NVS only
0x02	Erase FS only
0x03	Erase both NVS and FS

The erase flag is written to NVS (which survives OTA updates since it’s a separate flash partition). On the next boot, begin() reads the flag and performs the requested erase before continuing.

---

Print Protocol (0xEE)

Transport-agnostic console output. Messages sent via RadioKit.print() / RadioKit.println() are framed as 0xEE packets and delivered to the app’s console view.

Frame Structure

[START][LEN_LO][LEN_HI][DATA...]
  0xEE   uint16   uint16   0..N bytes (UTF-8 text)

• Unidirectional: Device -> App only
• Buffered: Print data is buffered in a 1024-byte circular buffer and flushed on newlines or when the buffer is near-full
• Flush on connect: Boot-time messages are preserved and sent when a client first connects

---

Filesystem Protocol (0xAA)

A separate, higher-bandwidth protocol for filesystem operations (browse, read, write, delete, mkdir, rename, info, ping, format). It uses a different start byte so it can coexist with the widget protocol (0x55) without interfering.

FS Frame Structure

[START][SUB_CMD][LEN_LO][LEN_HI][PAYLOAD...]
  0xAA   uint8     uint8   uint8   0..16380 bytes

Field	Size	Description
START	1	Always 0xAA
SUB_CMD	1	FS sub-command
LEN	2 (LE)	Total frame length (header(4) + payload)
PAYLOAD	0..16380	Sub-command-specific payload
CRC	none	No checksum - rely on transport reliability

Maximum payload size: 16 380 bytes (16 384 - 4-byte header).

Sub-Commands (App -> Arduino)

Value	Name	Payload	Description
0x01	FS_LIST	[u8 path_len][path...]	List entries in a directory
0x02	FS_READ	[u8 path_len][path...][u32 offset][u16 max_bytes]	Read up to 65 535 bytes from offset
0x03	FS_WRITE	[u8 path_len][path...][u32 offset][bytes...]	Write a file chunk
0x04	FS_DELETE	[u8 path_len][path...][u8 recursive]	Delete a file or directory
0x05	FS_INFO	(empty)	Get FS usage / free space
0x06	FS_MKDIR	[u8 path_len][path...]	Create a directory
0x07	FS_RENAME	[u8 old_len][old...][u8 new_len][new...]	Rename / move
0x08	FS_UPLOAD_BEGIN	[u8 path_len][path...][u32 size]	Begin a multi-frame write
0x09	FS_UPLOAD_CHUNK	[u8 path_len][path...][u32 offset][bytes...]	Write a chunk of an upload
0x0A	FS_UPLOAD_END	[u8 path_len][path...][u32 size]	Finalize a multi-frame write
0x0B	FS_PING	(empty)	Capability probe
0x0C	FS_FORMAT	(empty)	Re-format the default FS (destructive)

Sub-Commands (Arduino -> App)

Value	Name	Payload	Description
0x81	FS_LIST_DATA	[u16 count] then per entry [u8 is_dir][u32 size][u8 name_len][name...]	Directory listing result
0x82	FS_READ_DATA	[u32 total_size][u32 offset][bytes...]	File chunk
0x83	FS_WRITE_ACK	[u8 err]	Write ack
0x84	FS_DELETE_ACK	[u8 err]	Delete ack
0x85	FS_INFO_DATA	[u32 total][u32 used][u16 block_size][u8 fs_type]	FS usage / metadata
0x86	FS_MKDIR_ACK	[u8 err]	Mkdir ack
0x87	FS_RENAME_ACK	[u8 err]	Rename ack
0x88	FS_UPLOAD_BEGIN_ACK	[u8 err]	Upload begin ack
0x89	FS_UPLOAD_CHUNK_ACK	[u8 err]	Upload chunk ack
0x8A	FS_UPLOAD_END_ACK	[u8 err]	Upload end ack
0x8B	FS_PING_ACK	[u8 status]	Mount status
0x8C	FS_FORMAT_ACK	[u8 err]	Format ack

Error Codes

Value	Name	Meaning
0x00	OK	Success
0x01	NOT_FOUND	File or directory does not exist
0x02	IO	Read/write error
0x03	NO_FS	LittleFS not compiled in or not mounted
0x04	ACCESS_DENIED	Permission denied (requires device-level auth)
0x05	INVALID_PATH	Malformed path or argument
0x06	OUT_OF_SPACE	Filesystem full
0x07	INVALID_STATE	Operation not valid in current state

Notes

• The FS protocol is optional. Sketches that don’t use it can simply not call RadioKit.beginFs().
• The four state machines (0x55 widget, 0xAA FS, 0xBB OTA, 0xDD Settings) are fed from the same byte stream and demuxed by the start byte.
• FS_PING is the recommended way to detect FS support on a freshly-connected device.
• FS operations require device-level authentication (or serial bypass).

---

Transports

BLE (NimBLE)

Role	UUID
Service	0000FFE0-0000-1000-8000-00805F9B34FB
Characteristic	0000FFE1-0000-1000-8000-00805F9B34FB

• Properties: Write (no response), Notify, Indicate
• MTU: 23 bytes (default), negotiated up to 517
• Packet fragmentation: Handled by NimBLE for packets > MTU
• Advertising name: Auto-prefixed with RK_ for app filtering
• Connection interval: Reported via BLE_INFO settings command

USB Serial / UART

• Baud rate: 1000000 (recommended), any speed supported
• Connection timeout: 3000 ms after last valid packet
• Hardware flow control: Optional (RTS/CTS)
• Serial bypass: Physical serial access implies full device-level authentication

WiFi (WebSocket Server)

• Port: 5555
• Modes: AP mode (open network RK_<name>) or STA mode (connects to configured network)
• Credentials: Stored in NVS, configurable via SET_WIFI settings command
• Build flag: -D RADIOKIT_ENABLE_WIFI

Cloud (WebSocket Client)

• Connection: Outbound WSS connection to configured relay server
• Authentication: Ed25519 challenge-response (public key as account identifier)
• Requires: WiFi transport to be active first
• Build flag: -D RADIOKIT_ENABLE_WIFI

---

Timing & Keepalive

• VAR_UPDATE retry: 500 ms interval, 5 max retries
• Connection timeout: 3000 ms (serial), transport-driven (BLE/WiFi)
• BLE connection interval: Reported via BLE_INFO command
• Settings frame timeout: No explicit timeout — transport-driven

---

Error Handling

• CRC mismatch: Packet silently discarded
• Invalid START byte: Stream resynchronized on next valid start byte
• Unknown CMD: Packet ignored (future compatibility)
• Buffer overflow: Packet truncated, connection reset
• Reliable packet timeout: Retransmit up to 5 times, then drop
• Auth rejection: Returns ACK with error code, command ignored

---

Version History

Version	Changes
v1.0	Initial protocol (GET_CONF, CONF_DATA only)
v2.0	Added VAR_DATA, SET_INPUT
v3.0	Added reliability (ACK, VAR_UPDATE), META_DATA, TELEMETRY
v3.1	Added bulk Filesystem protocol (0xAA)
v3.2	Added FS_PING and FS_FORMAT sub-commands
v4.0	NVS-backed config, Settings protocol (0xDD), OTA protocol (0xBB)
v4.2	Removed PING/PONG (transport-driven health), added Print protocol (0xEE)
v5.0	Current version — widget type IDs reordered, CONF_DATA simplified (name/desc moved to Settings), STYLE/VARIANT bytes in widget descriptor

---

See Also

• Widgets Reference — Widget type IDs and properties
• Transports — Transport configuration