Skip to content
SentinelSentinel Documentation

Payload formats

The payload format of telemetry, event, and status is chosen with the key payload_format:

Value Format Notes
flat2 SenFlat v2 default since firmware 0.8.2 (new units). One source per message; millisecond time, sequence number q
flat SenFlat v1 compact flat JSON; units are taken by the server from the metric catalog
senml SenML (RFC 8428) carries units (u)

The default only applies to new units: a unit that already stores flat stays flat until configured with {"payload_format":"flat2"}. Changing the format triggers a reboot so the LWT payload changes too. The server must support the chosen format: if not, messages are still received but produce no metrics. All formats carry the same metrics and values.

{"f":"flat","v":2,"q":4821,"h":0,
 "s":[{"id":"001a2b3c4d5e","t0":1790000000000,"ts":1,
       "m":{"rack_top":22.44,"voltage":230.1,"power_draw":948,"front_door":false}}]}
Field Meaning
f, v format marker ("flat") and version (2)
q message sequence number, persistent in flash (written every 256 messages; random seed if empty), keeps rising across reboots and firmware updates. The server drops messages whose q has already been received
h 0 = fresh reading; 1 = history (resent after the connection recovers)
s[] list of sources; from a node always one: id = MAC
t0 epoch milliseconds from the node clock
ts 1 if the clock is NTP-synchronized (succeeded within the last 3 days); 0 if not, and the server uses receive time
m metrics: name → scalar value. In history, values are arrays of [dt, value] pairs

Value rules: a number, boolean, or text (max. 500 characters). A sensor that fails to read or is missing is not included; the node never sends null or a marker value like -1. Metric names are lowercase with digits and _, written in full.

Time

Section titled “Time”

Without a synchronized clock: SenFlat v1 carries no t, SenML carries no bt, and SenFlat v2 marks ts:0. The server uses receive time for all of them. ts:1 does not mean the gateway’s clock has a real NTP upstream; the history component checks that and downgrades to ts:0 if the upstream is lost for long.

Built-in metrics

Section titled “Built-in metrics”
Metric Unit (SenML) Source
tN_name (default t1…t4) Cel DS18B20, one per active temperature slot; name from configuration
temp_ambient, humidity Cel, %RH SHT41 (if sht41 = true)
voltage, current, power_draw V, A, W PZEM-004T
energy, frequency, power_factor kWh, Hz, / PZEM-004T
dN_name (default d1…d4) boolean digital input; true = active per dN_active. Only inputs whose dN_type is not off
oN_name (default o1…o4) boolean enabled digital output; true = ON
alarm_<name>_warn/_high/_active/_inactive, alarm_voltage_low, … boolean status of each alarm whose limit is set
alarm_level number 0 normal, 1 warning, 2 alarm
maintenance boolean only sent while maintenance mode is active
rule_<id>, flag_f1… boolean status of rules with en: true; flags used by the rules set
expander_ok boolean false = PCF8574 not answering
src_<id>_ok boolean source diagnostics (only if diag: true)
uptime, heap_free s, By ESP32
Modbus source metric names from the profile prefix_suffix, e.g. rak1_voltage

A fuller list and the naming rules: Metrics.

The status message

Section titled “The status message”

Retained. Contains state (online / offline), fw (version), ip, and gateway. The offline message is sent by the broker through the LWT; from 0.21.1, status also carries telemetry group send-cause counters.