hamqtt
======

.. py:module:: hamqtt

.. autoapi-nested-parse::

   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
----------

.. autoapisummary::

   hamqtt.DISCOVERY_PREFIX
   hamqtt.MAINTENANCE_ON
   hamqtt.MAINTENANCE_OFF
   hamqtt.EXPIRE_AFTER_S
   hamqtt.SENSORS
   hamqtt.STATS_KEYS


Classes
-------

.. autoapisummary::

   hamqtt.Device
   hamqtt.Retained


Functions
---------

.. autoapisummary::

   hamqtt.slug
   hamqtt.maintenance_topic
   hamqtt.read_retained


Module Contents
---------------

.. py:data:: DISCOVERY_PREFIX
   :value: 'homeassistant'


.. py:data:: MAINTENANCE_ON
   :value: 'ON'


.. py:data:: MAINTENANCE_OFF
   :value: 'OFF'


.. py:data:: EXPIRE_AFTER_S
   :value: 1800


.. py:data:: SENSORS

.. py:data:: STATS_KEYS
   :value: ('awake_share', 'wakes_per_hour', 'awake_per_wake')


.. py:function:: slug(text)

   Lowercase ASCII letters, digits and "_", as MQTT/HA IDs want them.


.. py:class:: 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.


   .. py:attribute:: expire_after
      :value: 1800



   .. py:attribute:: node
      :value: ''



   .. py:attribute:: unique
      :value: ''



   .. py:attribute:: state_topic
      :value: '/state'



   .. py:attribute:: stats_topic
      :value: '/stats'



   .. py:attribute:: maintenance_topic
      :value: '/maintenance'



   .. py:attribute:: info


   .. py:method:: discovery()

      (topic, payload) per sensor for Home Assistant's MQTT discovery.



   .. py:method:: 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.



   .. py:method:: state(status)
      :staticmethod:


      State payload for a battery.as_dict() status.



   .. py:method:: publish(client, status, stats=None)

      Publish discovery configs, the state and the awake statistics.

      All messages are retained.

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



.. py:function:: maintenance_topic(hostname)

   Retained topic of the maintenance switch, e.g. epaper/maintenance.


.. py:class:: 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.


   .. py:attribute:: value
      :value: None



.. py:function:: 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`).