# Home Assistant

## Data

The board reads the entities shown on its tiles through Home Assistant's REST API
([`HOME_ASSISTANT_URL`](#defaults.HOME_ASSISTANT_URL), `HOME_ASSISTANT_TOKEN` in `src/config.py`; create a long-lived access
token in your Home Assistant profile). States, warnings and the catalog for the web interface
are each fetched with a single template request (`POST /api/template`), which is much faster on
the board than one request per entity.

The data source is injected into the rest of the firmware (see [`datasource.py`](#datasource)), so other
sources such as SignalK can be added without touching layout or display code.

## Device via MQTT

With every data update the board announces itself via MQTT discovery as the device "ePaper"
with these sensors:

- Akku (battery, %), Akkuspannung (voltage), Ladezustand (charging/discharging/stable)
- Diagnostics: Charge rate (%/h), Awake share (%), Wakes per hour and Awake time per wake (s);
  the last three are statistics since the previous report, useful to judge the power
  consumption

Messages are retained, so Home Assistant knows the last values while the board sleeps. If
nothing arrives for about two fetch intervals, the sensors become unavailable.

This requires an MQTT broker (such as Mosquitto) and the MQTT integration in Home Assistant.
Broker and credentials go into `src/config.py` (`MQTT_BROKER`, `MQTT_USER`, `MQTT_PASSWORD`).
Device name and model ([`DEVICE_NAME`](#defaults.DEVICE_NAME), [`DEVICE_MODEL`](#defaults.DEVICE_MODEL)) have defaults in [`src/defaults.py`](#defaults); like
every default, they can be overridden in `src/config.py`.

## Maintenance switch

The device also has a switch "Maintenance mode". While it is on, the board stays awake after its
next data update, with the web interface and updates over the WLAN available and the WLAN
symbol shown. It switches itself off after [`MAINTENANCE_S`](#defaults.MAINTENANCE_S). `make deploy-wlan` uses the
same switch to wake a sleeping board.

## Warnings

Any binary sensor can serve as a warning source; the attributes of the
[NINA](https://www.home-assistant.io/integrations/nina/) integration (headline, description,
severity, sender, expiry) are shown when present. Choose the sources in the web interface or
with [`DEFAULT_ALERTS`](#defaults.DEFAULT_ALERTS) in `src/config.py`. While Home Assistant is unreachable, cached warnings
stay on screen until they expire.