Bridge to Celestian

The gateway forwards Sentinel messages to Celestian over two routes: the Mosquitto bridge for status and settings messages, and the history component for telemetry and events (History storage).

Topic mapping

Sentinel ── sentinel/<mac>/telemetry|event (anonymous, rack LAN) ──▶ Mosquitto ──▶ history (queue on disk)
                                                                        ──▶ m/<ws>/c/<ch>/<gateway-ID>/telemetry|event (SenFlat v2)
         ── status, config/reported, cmd/result, rules/reported, … ──▶ Mosquitto ──▶ bridge ──▶ m/<ws>/c/<ch>/<mac>/…

Local (rack LAN)	Celestian	Direction	Carried by
sentinel/<mac>/telemetry, event	m/<ws>/c/<ch>/<gateway-ID>/telemetry, event (many nodes in one SenFlat v2 message)	up	history
sentinel/<mac>/status	m/<ws>/c/<ch>/<mac>/status	up	bridge
config/reported, cmd/result, rules/reported, rules/current, sources/reported, sources/current, profiles/reported, profiles/current, tgroups/reported, tgroups/current	m/<ws>/c/<ch>/<mac>/…	up	bridge
config, cmd, rules, sources, profiles, tgroups	m/<ws>/c/<ch>/<mac>/…	down	bridge

<gateway-ID> is the UUID of the gateway device in Celestian. Telemetry and events that are not SenFlat v2 (SenFlat v1, SenML; old firmware or payload_format other than flat2) are forwarded by history as-is to m/<ws>/c/<ch>/<mac>/…, one by one, without history.

Caution

bridge.conf must not contain the +/telemetry and +/event lines, otherwise data is sent twice. Also make sure the sources, profiles, and tgroups lines (with */reported and */current) are present; copy them from bridge.conf.example then docker compose restart mosquitto. Without them the node keeps working, but Celestian cannot send or see its sources, profiles, and telemetry groups.

Registering in Celestian

1. Create a device with Gateway mode for this gateway and save its device key.
2. Connect it to the channel with the publish type, and subscribe if you want to send config/cmd to nodes.
3. Nodes appear in the gateway’s Roster tab (recognized by MAC). Register them as devices with Serial = MAC (lowercase, no separators).
4. Create a storage rule for that channel; without a rule, messages are not stored.

The bridge clientid must start with the gateway device ID (the broker’s prefix policy), e.g. <gateway-ID>-bridge.

Choosing the connection method to Celestian

Celestian has three broker ports: MQTT 3.1.1, MQTT 5, and MQTTS (one port for 3.1.1 and 5). The gateway uses one of four methods, and the two components that talk to Celestian (history through .env, the bridge through bridge.conf) must use the same one.

Method	Default port	.env	bridge.conf
mqtt3	11883	CELESTIAN_MODE=mqtt3	bridge_protocol_version mqttv311, address <host>:11883
mqtt5 (default)	11884	CELESTIAN_MODE=mqtt5	bridge_protocol_version mqttv50, address <host>:11884
mqtts3	18883	CELESTIAN_MODE=mqtts3	like mqtt3, address <host>:18883, plus bridge_cafile
mqtts5	18883	CELESTIAN_MODE=mqtts5	like mqtt5, address <host>:18883, plus bridge_cafile

The port of each type can be changed in .env: CELESTIAN_PORT_MQTT3, CELESTIAN_PORT_MQTT5, CELESTIAN_PORT_MQTTS. CELESTIAN_PORT (the old way), if set, overrides all of them, so clear it when switching methods.

MQTT 3.1.1 has no message properties (content type), so Celestian must treat a payload without a content type as JSON.

TLS

CELESTIAN_HOST and address must be a domain name that appears in the server certificate (IP addresses fail verification), and certificate checking must not be turned off. Choose one trust source, and keep it the same for history and the bridge:

Server certificate	.env	bridge.conf
Private CA (Celestian’s internal CA)	CELESTIAN_CA_FILE=/mosquitto/config/celestian-ca.crt	bridge_cafile /mosquitto/config/celestian-ca.crt
Public CA (e.g. Let’s Encrypt; the server installs fullchain.pem)	CELESTIAN_CA_FILE= (empty: system CA bundle)	bridge_cafile /etc/ssl/certs/ca-certificates.crt

Store the private CA file at Gateway/mosquitto/celestian-ca.crt; one file is used by both components. Do not set bridge_cafile and bridge_capath together. After changing:

docker compose up -d --build history
docker compose restart mosquitto
docker compose logs history | head     # shows the effective connection method, e.g. mqtts5 (MQTT 5 + TLS)

Bridge session

The bridge uses cleansession false and, for MQTT 5, bridge_session_expiry_interval 3600 (needs Mosquitto 2.1 or newer): the session on the central broker survives 1 hour after the bridge drops, so commands from the server during a brief WAN outage still arrive.