Basic concepts

Identity: the MAC

Every Sentinel is identified by its Ethernet MAC: lowercase without separators, for example a2cb8ff8768d. This value appears in all topics, in the data (id in SenFlat, bn in SenML), on the LCD (the Device menu), and becomes the device Serial in Celestian. Because the identity is derived from the chip’s base MAC, the same unit always has the same ID.

Slots

Sensors take the form of slots with fixed IDs:

Slot	Contents	Count
`t1` … `t4`	DS18B20 temperature, bound to a sensor by ROM ID	4
`d1` … `d4`	digital inputs (door, UPS, water, smoke, generic)	4
`o1` … `o4`	digital outputs	4

Slot IDs never change. What you can change is the metric name (tN_name, dN_name, oN_name, e.g. rack_top), which becomes the data name in Celestian, and the label (text for humans and the LCD). Names follow function, not pin: moving front_door to another slot by swapping names does not break its data series, whereas renaming starts a new series.

Metrics

Every value sent is a metric with a name, for example rack_top, voltage, front_door, alarm_level. A sensor that cannot be read is not sent (never null or a sentinel value). The list of built-in metrics is in Metrics. Modbus devices add metrics named prefix_suffix (e.g. rak1_voltage).

Two connection modes

	Gateway mode (default)	Direct mode
Credentials on the node	none	`mqtt_user` and `mqtt_pass` (ID and device key)
Topics on the node	`sentinel/<mac>/…`	`m/<workspace>/c/<channel>/<mac>/…`
Broker, NTP, OTA IP	gateway IP from DHCP	Celestian broker host
Data when the WAN is down	held by the gateway on disk	held by the node in PSRAM (`hist_kb`), lost on reboot

A node automatically uses gateway mode with no setup. Direct mode is active when workspace and channel are filled in.

Five kinds of settings

Settings are sent to the node over different topics, each with its own version number and report-back:

Topic	Version	Contents	Page
`config`	`cfg_ver`	flat keys: connection, sensors, alarms, display, firmware target	Configuration
`rules`	`rules_ver`	on-device rules: condition, then output, event, or LCD text	Rules
`sources`	`sources_ver`	Modbus metric sources and RS-485 bus settings	Modbus sources
`profiles`	`profiles_ver`	Modbus device profiles (register maps)	Modbus profiles
`tgroups`	`tgroups_ver`	telemetry groups: how often each group of metrics is sent	Telemetry groups

The same rules apply to all of them:

Messages are sent retained (QoS 1) so a node that has just powered up or reconnected receives the latest one.
config applies the valid keys and rejects the rest with reasons; rules, sources, profiles, and tgroups replace the whole set.
The node replies on the …/reported topic (retained) with what applies, the version, and rejected. A configuration counts as applied when the version in the report equals the one sent and rejected is empty.
Everything is stored in the node’s flash and survives reboot.
A set can be sent with confirmation (confirm_s): it runs temporarily and reverts to the old set unless confirmed. This protects against settings that would make the node unusable.

Alarms, rules, and telemetry groups

Built-in alarms (temp_warn_c, volt_max_v, …) handle temperature, power, and digital inputs given dN_alarm. The level is reported as alarm_level: 0 normal, 1 warning, 2 alarm.
Rules for extra logic: turn on a fan when the temperature is high, raise an alarm when a Modbus meter exceeds a limit, or follow working-hours schedules.
Telemetry groups control when metrics are sent, so rarely-changing values do not consume message size.