Subscribe to Live Telemetry with MQTT

MQTT is handy when several little programs want the same data. One can draw a dashboard, another can log the flight, and a third can blink something ill-advised.

Connect

The guest shell receives $GATOS_MQTT when MQTT is enabled. On the host, the preferred broker is 127.0.0.1:1883; the status window shows the actual port.

inside the guest

apk add mosquitto-clients
mosquitto_sub -h sim -p 1883 -t 'gatos/#' -v

on the host

mosquitto_sub -h 127.0.0.1 -p 1883 -t 'gatos/events' -v

1. Subscribe to gatos/snapshot and note that a value arrives immediately. It is retained.
2. Subscribe to gatos/events and stage or ignite a vessel. Events are live, not retained.
3. Subscribe to gatos/sim/vessels/active/altitude/radar for the field-level mirror.

Send a command

set half throttle

mosquitto_pub -h sim -p 1883 -t gatos/command -m \
  '{"vessel_id":"Hunter","action":"vessel.throttle","value":0.5}'

Use the exact vessel id and action key. Commands report results on the command-result topic described in the MQTT reference.

Network clients

The embedded broker defaults to loopback. Set mqtt_bind_host to the host-interface IP (or 0.0.0.0 for all IPv4 interfaces) for a Raspberry Pi or ESP32 to connect directly. There is no broker authentication, so every client that can reach the address can also publish commands.

MQTT publishing is subscription-gated, changed-only, and rate-capped. Unsubscribed topics cost very little, which is a nice property for a feature named after shouting messages into space.

MQTT referenceTopic families, retention, field mirrors, commands, cadence, and binding behavior.