🏠 Home → Software → RTLV → RTLV — Protocol
🤖 Auto-generated from firmware (SSOT). Do not hand-edit — change the descriptor and regenerate. RTLV v3 ·
source_hash eb6b51128c1b
RTLV is ROSSMA's device telemetry & command protocol. The payload is a stream of [tag][len][value] triplets (Type-Length-Value).
| Property | Why it matters for RTLV |
|---|---|
| Extensibility | new tags never break old decoders |
| Sparse | only present fields are sent — saves airtime |
| Per-tag forward-compat | an unknown tag is skipped via len, parsing continues |
| Direction | Shape | Decoded by |
|---|---|---|
| uplink | [prefix][seq][TLV…] (offset 2) |
service / app |
| downlink cmd | [cmd_id][len][params] |
firmware |
| response | 0xF0 envelope + echo-TLVs |
service / app |
The same tag number means different things on different FPorts. Global tags 0x00–0x0F and 0xF0–0xFF live in the * namespace.
Big-endian by default; a decoder reads each tag's endian field. LE exceptions: 0x07, 0xCB(@100). See Frame Structure.
| Transport | Medium | Frame offset | Notes |
|---|---|---|---|
| LoRaWAN | air | 2 | FPort selects the namespace |
| nRF52 | BLE over I2C | 0 | no FPort byte; frame starts at the prefix |
| ESP32 | UART | 2 | same framing as LoRaWAN |
Firmware is the single source of truth. The descriptor is generated from it, and the decoders, docs and these pages are generated from the descriptor. Drift is caught by source_hash + a CI gate.
RTLV v3, min firmware 3.0.0. source_hash = eb6b51128c1b… pins the exact protocol version (the service pins it).
Magic confirmations (u16 BE):
| Cmd | Name | Magic | Effect |
|---|---|---|---|
1.0xE1 |
factory_reset | 0xFACE/0xDEAD |
soft / full |
199.0xF1 |
factory_reset_lorawan | 0xCA11 |
reset LoRaWAN |
199.0xF2 |
factory_reset_keys | 0xDEAD |
reset keys |
100.0x8F |
reset_all_stats | 0xDEAD |
wipe all stats |
Uplink tags by port: global, LORAWAN_CFG (FPort 199), DEVICE_MGMT (FPort 1), APP_CONTROL (FPort 3), DIAGNOSTICS (FPort 100), UART_SYSTEM (FPort 250), SYSTEM_TELEMETRY (FPort 2), GPIO (FPort 4), ANALOG (FPort 5), HART (FPort 6), ONEWIRE (FPort 7)
Commands by port: DEVICE_MGMT (FPort 1), APP_CONTROL (FPort 3), GPIO (FPort 4), HART (FPort 6), FPort 10, DIAGNOSTICS (FPort 100), LORAWAN_CFG (FPort 199)
Raw ports (chat/paging): PAGING_USER (FPort 220)