Shared helpers for multi-instance MQTT-based TUI dashboards.
Enables TUI dashboards to monitor all running instances of a service
simultaneously, regardless of how many processes are started on different
ports or hosts. Each service instance publishes a small retained MQTT
heartbeat; the TUI subscribes to a wildcard topic and aggregates heartbeats
from every live instance.
axion/{package}/heartbeat/{service_type}/{hostname}:{port}
{package} — active package name (e.g. homechoice){service_type} — short name for the service: report, webhook, go,conversation, ai{hostname}:{port} — unique instance identifierTUI wildcard subscription: axion/+/heartbeat/{service_type}/+
Heartbeats are published with retain=True so a TUI process sees the last
known state immediately on connect without waiting for the next heartbeat
interval.
from ObjServiceHeartbeat import start_heartbeat
stop_event = start_heartbeat("report", port)
uvicorn.run(...)
start_heartbeat(service_type, port, package="", extras=None) starts a
daemon thread that publishes every TuiConstants.HEARTBEAT_INTERVAL_SECS
(15 s). The thread is daemonic — process exit stops it automatically.
from ObjServiceHeartbeat import (
make_subscription_topic,
read_mqtt_config,
make_paho_client,
)
topic = make_subscription_topic("report") # axion/+/heartbeat/report/+
host, port, user, pwd, pkg = read_mqtt_config()
client = make_paho_client(user, pwd)
make_paho_client creates a client using the paho-mqtt VERSION2 callback API.
When setting on_connect, use the five-argument signature:
def _on_connect(client, userdata, connect_flags, reason_code, properties):
if reason_code == 0:
client.subscribe(topic, qos=1)
reason_code == 0 tests for success; reason_code is a paho ReasonCode
object that supports integer comparison.
{
"service": "report",
"instance_id": "myhost:9400",
"hostname": "myhost",
"port": 9400,
"package": "homechoice",
"uptime_seconds": 3600,
"pid": 12345,
"timestamp": 1700000000.0
}
An instance is considered stale when its last heartbeat timestamp is
older than TuiConstants.HEARTBEAT_STALE_SECS (45 s = 3 missed beats at the
default 15 s interval). TUI dashboards use this threshold to mark instances
offline and grey them out.
| Constant | Default | Description |
|---|---|---|
HEARTBEAT_INTERVAL_SECS |
15 | Seconds between heartbeat publishes |
HEARTBEAT_STALE_SECS |
45 | Seconds before an instance is stale |
CONFIG_POLL_SECS |
60.0 | Slow DB poll for static config data |