hamqtt¶

The board as a device in Home Assistant, via MQTT discovery.

Discovery configs and the state are published retained, so Home Assistant knows the device and its last values even while the board sleeps. The sensors expire (show as unavailable) when no state arrives for EXPIRE_AFTER_S, e.g. because the battery is empty.

The MQTT client is injected (umqtt.simple.MQTTClient on the board), so this module runs on the host in tests.

Attributes¶

`DISCOVERY_PREFIX`
`MAINTENANCE_ON`
`MAINTENANCE_OFF`
`EXPIRE_AFTER_S`
`SENSORS`
`STATS_KEYS`

Classes¶

`Device`	The board as a Home Assistant device: discovery, state and topics.
`Retained`	The latest message on a retained topic, kept up to date.

Functions¶

`slug`(text)	Lowercase ASCII letters, digits and "_", as MQTT/HA IDs want them.
`maintenance_topic`(hostname)	Retained topic of the maintenance switch, e.g. epaper/maintenance.
`read_retained`(client, topic[, attempts, pause_s, sleep])	Return the retained message on `topic` as text, or None (see `Retained`).

Module Contents¶

hamqtt.DISCOVERY_PREFIX = 'homeassistant'¶

hamqtt.MAINTENANCE_ON = 'ON'¶

hamqtt.MAINTENANCE_OFF = 'OFF'¶

hamqtt.EXPIRE_AFTER_S = 1800¶

hamqtt.SENSORS¶

hamqtt.STATS_KEYS = ('awake_share', 'wakes_per_hour', 'awake_per_wake')¶

hamqtt.slug(text)¶: Lowercase ASCII letters, digits and “_”, as MQTT/HA IDs want them.

class hamqtt.Device(hostname, device_id, name, model, config_url, expire_after=EXPIRE_AFTER_S, sw_version=None)¶

The board as a Home Assistant device: discovery, state and topics.

expire_after = 1800¶

node = ''¶

unique = ''¶

state_topic = '/state'¶

stats_topic = '/stats'¶

maintenance_topic = '/maintenance'¶

info¶

discovery()¶: (topic, payload) per sensor for Home Assistant’s MQTT discovery.

maintenance_discovery()¶

Return the discovery config of the “Maintenance mode” switch.

While the switch is on, the board stays awake at its next fetch for the web interface and updates. Command and state share one retained topic, so the board finds the setting whenever it connects.

Returns:: (topic, payload) for the discovery message.

static state(status)¶: State payload for a battery.as_dict() status.

publish(client, status, stats=None)¶

Publish discovery configs, the state and the awake statistics.

All messages are retained.

Parameters:

client – An MQTT client (umqtt.simple.MQTTClient on the board).
status – A battery.as_dict status.
stats – An awake_stats.summary, or None to leave it out.

hamqtt.maintenance_topic(hostname)¶: Retained topic of the maintenance switch, e.g. epaper/maintenance.

class hamqtt.Retained(client, topic, attempts=30, pause_s=0.05, sleep=time.sleep)¶

The latest message on a retained topic, kept up to date.

Subscribing delivers the retained message; later messages on the topic (the switch turned off, say) update value whenever the client’s check_msg runs. The client keeps the subscription and this callback.

value = None¶

hamqtt.read_retained(client, topic, attempts=30, pause_s=0.05, sleep=time.sleep)¶: Return the retained message on topic as text, or None (see Retained).