MQTT

voltkeeper supports publishing device state to an MQTT broker and subscribing to watch battery SOC for shutdown control.

mqtt-publish

Continuously polls the device over BLE and publishes state to an MQTT broker. Supports Home Assistant MQTT auto-discovery (on by default).

voltkeeper mqtt-publish AA:BB:CC:DD:EE:FF --broker 192.168.1.100

Options

Option	Description
--serial TEXT	Device serial number (overrides BLE lookup for MQTT topic)
--broker TEXT	MQTT broker hostname (required)
--port INTEGER	MQTT broker port (default: 1883)
--username TEXT	MQTT broker username
--password TEXT	MQTT broker password
--interval INTEGER	Seconds between polling cycles (default: 0 = as fast as possible)
--ha-config MODE	Home Assistant discovery mode: normal, none, advanced (default: normal)
--restart-on-source-change	Exit cleanly when source code changes, so systemd restarts the process

mqtt-listen

Subscribes to the device’s MQTT topic and watches battery SOC. When SOC drops below the threshold, initiates a system shutdown after a grace period.

The shutdown is latched — once triggered, it cannot be cancelled by SOC recovery (use systemctl stop to abort before the grace period expires).

voltkeeper mqtt-listen --serial 2409000123456 --broker 192.168.1.100

ADDRESS may be omitted if --serial is provided (useful when running on a different machine without BLE).

Options

Option	Description
--serial TEXT	Device serial number (or provide ADDRESS for BLE lookup)
--broker TEXT	MQTT broker hostname (required)
--port INTEGER	MQTT broker port (default: 1883)
--username TEXT	MQTT broker username
--password TEXT	MQTT broker password
--shutdown-at INTEGER	SOC % threshold for shutdown (default: 10)
--grace-period INTEGER	Seconds below threshold before shutdown (default: 60)
--restart-on-source-change	Exit cleanly when source code changes