The celestian-sim simulator

celestian-sim is a command-line program that pretends to be a device or gateway: it connects to the broker with real device credentials and then sends sensor data periodically. Useful for trying the platform, filling dashboards, testing rules and alarms, and light load.

A single static binary for Linux and macOS (amd64 and arm64), with no dependencies.
It stops cleanly with Ctrl+C, and reconnects automatically if the broker drops.
It runs well inside tmux.

Preparing Celestian

The simulator uses real device accounts:

Create a channel (for example the route warehouse-telemetry).
Create devices (one per simulated device; for a gateway, turn on gateway mode). Note the ID and key (shown only once).
Give them a publish connection to the channel.
Add a storage rule (SenML) on the channel. Without a rule, messages are received but not stored.

The data it sends

The default edge profile imitates an edge node with 12 quantities that are related to each other, not random:

Name	Unit	How it is generated
`temp_inlet`	`Cel`	A sine from 20.5 to 24.5 (the cycle can be changed) with noise.
`temp_outlet`	`Cel`	Inlet + 2.5 + 0.0072 × power: the heavier the load, the hotter.
`temp_ambient`	`Cel`	Inlet + 1.7 + noise (optional).
`humidity`	`%RH`	About 55, dropping slightly when warmer (optional).
`voltage`	`V`	About 230 with drift; occasionally a drop of 8 to 15 V.
`current`	`A`	Computed = power / (voltage × power factor).
`power_draw`	`W`	About 950 ± 180.
`energy`	`kWh`	An accumulation of power over time.
`frequency`	`Hz`	50 ± 0.1.
`power_factor`	`/`	About 0.97.
`uptime`	`s`	Increases with time.
`heap_free`	`By`	About 218000, slowly falling and then recovering.

The payload format is chosen with -format senml (the default), flat (SenFlat v1), or flat2 (SenFlat v2). All the metric names are in the default Metric Catalog. The option -profile rack uses the old profile (T, RH, V, I, S1, S2), and -no-sht41 removes temp_ambient and humidity.

Running

./celestian-sim device \
  -broker celestian.example.com:1883 -workspace cold-storage -channel warehouse-telemetry \
  -id <device-id> -key '<device-key>' -name room-a1 -interval 5s

Data goes to the topic m/cold-storage/c/warehouse-telemetry/room-a1.

./celestian-sim gateway \
  -broker celestian.example.com:1883 -workspace cold-storage -channel warehouse-telemetry \
  -id <gateway-id> -key '<gateway-key>' -name gw-a \
  -children 00:1A:2B:3C:4D:5E,aabbcc001122     # or -children 3 (automatic MACs)

Each child’s data goes to m/<ws>/c/<ch>/gw-a/<child>. Add -gateway-mode batch for one message containing all children.

{
  "broker": "celestian.example.com:1883",
  "workspace": "cold-storage",
  "channel": "warehouse-telemetry",
  "interval": "10s",
  "devices": [
    {"name": "room-a1", "id": "<id-1>", "key": "<key-1>"},
    {"name": "room-a2", "id": "<id-2>", "key": "<key-2>"}
  ],
  "gateways": [
    {"name": "gw-a", "id": "<id-gw>", "key": "<key-gw>", "children": ["001a2b3c4d5e"], "mode": "batch"}
  ]
}

chmod 600 sim.json      # the file contains device keys
./celestian-sim run -config sim.json

Options go after the subcommand: celestian-sim device -format flat2 -once …. Use environment variables so the key is not visible in the process list:

export CELESTIAN_SIM_BROKER=celestian.example.com:1883 CELESTIAN_SIM_WORKSPACE=cold-storage CELESTIAN_SIM_CHANNEL=warehouse-telemetry
read -rs CELESTIAN_SIM_KEY; export CELESTIAN_SIM_KEY
./celestian-sim device -id <device-id> -name room-a1

Important options

Option	Meaning
`-broker`	`host[:port]`, `mqtt://host:1883`, or `mqtts://host:8883` (TLS).
`-workspace`, `-channel`	A route or UUID.
`-id`, `-key`	The ID and device key.
`-name`, `-subtopic`	The label and subtopic.
`-interval`	The send interval (10 seconds by default).
`-qos`	`1` (the default) or `0`.
`-format`	`senml`, `flat`, or `flat2`.
`-speed N`	Speeds up simulated time (the sine and door changes).
`-temp-period`	The temperature sine period (1 hour by default).
`-count N`, `-once`	Stop after N sends.
`-dry-run`	Print the payload without connecting.
`-seed`	A random seed so results can be repeated.
`-children`, `-gateway-mode`, `-jitter`	Gateway only.

Topics, events, and status

The edge profile also imitates the firmware topics. Each node sends to <node>/telemetry (every interval), <node>/event (only when a door changes), and <node>/status (retained on connect; {state: offline} as the LWT and on a clean stop). A node also subscribes to <node>/config and <node>/cmd and replies on config/reported and cmd/result (the actions reboot, identify, ota, publish).

Gateway history

celestian-sim history imitates a gateway that sends held-back data after its connection recovers (SenFlat v2, h=1), to test the receiving side: order, duplicates, past times, wrong clocks, and size limits.

# 2 hours of history, 3 children, shuffled order, 30% resent, one current message first
./celestian-sim history -broker host:1883 -workspace ws -channel ch -id <gateway-id> -key <key> \
  -children 3 -span 2h -step 10s -chunk 60 -order shuffle -dup 0.3 -live

Options: -span, -step, -end, -chunk, -order asc|desc|shuffle, -dup F, -live, -bad-clock ts0|range, -t0 first|last, -q-start, -delay, -oversize. At the end, the simulator prints the expectations (how many points should be stored, how many resends should be dropped, and how many messages should be rejected) to compare with Celestian.

Sentinel nodes

celestian-sim sentinel imitates Sentinel SNT-G1 nodes that connect anonymously to the gateway Mosquitto over MQTT 5, with the metrics di1-di4, do1-do4, temperature, humidity, power quantities, uptime, and moving lat/long. A node accepts config (validated like the firmware), cmd, and rules (evaluated and driving outputs).

./celestian-sim sentinel                                     # one node to 127.0.0.1:11884
./celestian-sim sentinel -nodes a2cb8ff8768d,02aabbccdd02 -interval 5s
./celestian-sim sentinel -dry-run -once                      # see the messages without a broker

Recipes

See a full cycle in minutes: -speed 120 -interval 2s.
A daily temperature cycle: -temp-period 24h.
A limited number of messages: -count 30.
Test an alarm: build a rule with the condition temp_inlet > 23.5 on the same channel (example).
Children in the Roster: run the gateway once, open the Roster tab, then Register as device.

Troubleshooting

Message or symptom	Common cause
`refused by broker: wrong username or password`	A wrong ID or key, or the key was regenerated.
`client ID refused`	The device is disabled, or (production) `-client-id` does not start with the device ID.
`connection dropped by broker` right after connecting	The device has no publish connection to that channel, or the workspace and channel are wrong.
`no PUBACK`	The broker refused the message; check the publish connection and the topic.