Skip to content
CelestianCelestian Documentation

Gateways and the Mosquitto bridge

A common field pattern: sensor nodes have no Celestian credentials. They talk to a local Mosquitto on the gateway, and only the gateway connects to Celestian through a bridge.

Preparing Celestian

Section titled “Preparing Celestian”
  1. Create a channel (for example the route warehouse-telemetry).
  2. Create a device with Gateway mode on, and save the device key (shown once).
  3. Connect the gateway to the channel with the publish type. Add subscribe if the gateway must receive commands, configuration, or rules.
  4. Add a storage rule for that channel (the quick button on the channel page).
  5. Register the nodes as regular devices with Serial = the node’s MAC if you want Telemetry and status per node (Gateways).

The Mosquitto bridge

Section titled “The Mosquitto bridge”

An example mosquitto.conf on the gateway (the ID, key, workspace, and channel are yours):

connection celestian
address celestian.example.com:1883   # MQTT 3.1.1; or :1884 for MQTT 5
clientid <gateway-ID>                # production: must start with the gateway's device ID (<ID>-bridge is fine)
remote_username <gateway-ID>
remote_password <gateway-device-key>
bridge_protocol_version mqttv311
try_private false                    # the Celestian broker is not Mosquitto
cleansession false                   # store & forward while the WAN is down
notifications false                  # bridge notification topics are not channel topics
keepalive_interval 30


# A local "node/" prefix becomes a channel subtopic:
#   node/room-a1/telemetry  →  m/<workspace>/c/<channel>/node/room-a1/telemetry
topic node/# out 1 "" m/<workspace>/c/<channel>/


# Commands and configuration to the nodes (requires a subscribe connection)
topic +/config in 1 m/<workspace>/c/<channel>/ ""
topic +/cmd    in 1 m/<workspace>/c/<channel>/ ""

Notes:

  • <workspace> and <channel> can be a route or a UUID. Use the same form as the control widgets and the Device settings page use.
  • With the client_id policy that requires the device ID prefix, a free-form clientid is refused.
  • notifications true must be off: bridge notification topics are not channel topics and are refused.
  • cleansession false makes Mosquitto and the Celestian broker queue messages while the WAN link is down. The queue on Celestian lasts about one hour.
  • allow_anonymous true on the local listener is safe as long as it is only reachable on the LAN.
  • Configuration and rules sent to nodes use retained messages, so a node that powers on later still receives them. Make sure persistence true is set in Mosquitto.

Payload format on the gateway

Section titled “Payload format on the gateway”

Nodes (or the gateway) send SenML or SenFlat so latest values, aggregation, and dashboards work. bn or id = the node MAC without separators, in lowercase. See Payload formats and SenFlat v2 for history.