# Operation

## Update cycle and deep sleep

On battery the pace depends on the charge level and the time of day. With the defaults
([`BATTERY_MODES`](#defaults.BATTERY_MODES), [`LOW_BATTERY_PERCENT`](#defaults.LOW_BATTERY_PERCENT),
[`NIGHT`](#defaults.NIGHT); adjustable in `src/config.py`):

| Condition          | Fetch data (WLAN)  | Note                                         |
|--------------------|--------------------|----------------------------------------------|
| Battery from 50 %  | every 10 minutes   |                                              |
| Battery 25–50 %    | every 30 minutes   |                                              |
| Battery below 25 % | hourly             | bottom-left tile: "\<hostname\> aufladen"    |
| Night 01–07        | at most hourly     |                                              |

The header shows the time of the last data and of the next update ("Stand 14:20 · neu 14:30").
The next update is due one interval after the last one started, on a full minute. A clock updated every minute cost too much battery.
In between the board is in deep sleep until the next update, and it wakes on time at the end
of the night. At each update it sets the clock via NTP, fetches the values from Home Assistant
and redraws the screen (without flashing; a full refresh comes at least every
[`FULL_REFRESH_INTERVAL_S`](#defaults.FULL_REFRESH_INTERVAL_S)). The last values are kept in RTC memory, which survives deep sleep; if
Home Assistant cannot be reached, they stay on screen marked "offline".

While the board is in deep sleep it cannot be reached via USB or WLAN: press the reset button
before `make deploy` or `make monitor`, or use `make deploy-wlan`.

## Awake mode and web interface

On USB power (the battery is charging or full) the board stays awake: time and data are updated
as on battery, the web interface is always up, and a WLAN symbol in the header shows that the
board can be reached. With [`SHOW_QR_CODE = True`](#defaults.SHOW_QR_CODE) in `src/config.py` the bottom-left tile also
shows a QR code linking to the web interface; [`tools/qr_sticker.py`](#qr_sticker) prints one as a sticker for
the frame instead. With a voltage divider on [`USB_SENSE_PIN`](#defaults.USB_SENSE_PIN) (see
[Wiring](wiring.md)) plugging in USB wakes the board at once, and the charging symbol shows
while USB is plugged in. Without it, external power is guessed from the fuel gauge, so the
switch takes a few minutes after plugging in or out.

The WLAN symbol also shows during the web window after a reset (see
[`AWAKE_AFTER_RESET_S`](#defaults.AWAKE_AFTER_RESET_S)); the screen is redrawn without it before
the board goes to sleep.

- `http://epaper.local/` – for each of the six tiles choose the data source, label, style
  (number, text, weather icon) and decimals. They are saved in `tiles.json` on the board and the
  display is redrawn. Until then [`DEFAULT_TILES`](#defaults.DEFAULT_TILES) from `src/defaults.py` applies.
  Without waiting at the browser, [`tools/board_tiles.py`](#board_tiles) fetches the settings
  into a local file (`pull`) and sends the edited file back (`push`), waking a sleeping board
  through the maintenance switch.
- Number tiles can show a **trend**: an arrow in the top right corner when the value rose or fell
  by at least a threshold over up to three hours (1 hPa is the usual barometer tendency; the page
  suggests a threshold from the unit). The board keeps the history of all number tiles itself in
  [`trend.json`](#trend), one value per half hour, and compares with the oldest value of the
  last three hours; so an arrow can appear as soon as the trend is switched on, and within half
  an hour after a restart. Steady values show no arrow.
- "Warnungen" on the same page lists the warning sources (default [`DEFAULT_ALERTS`](#defaults.DEFAULT_ALERTS), such as the
  NINA sensors of your area; saved in `alerts.json`). If one of them is active, a warning screen
  replaces the tiles at the next data update: title, text, severity, validity and sender of the
  most severe warning; further ones are counted.
- `http://epaper.local/battery` – battery state as JSON
- `http://epaper.local/log` – boot log

On battery the board is reachable for [`AWAKE_AFTER_RESET_S`](#defaults.AWAKE_AFTER_RESET_S) after a reset (power on, reset button,
`make deploy`), or while the maintenance switch in Home Assistant is on.

With [`STATUS_SCREENS`](#defaults.STATUS_SCREENS) the display shows the boot sequence after every
reset (power on, reset button, restart after an update, watchdog): "Dashboard startet", each
WLAN connection attempt and the result, then the dashboard. An update over the WLAN
(`make deploy-wlan`) also shows how many and which files it changed before the board restarts.

Since USB output during boot is usually lost, [`boot.py`](#boot) also writes to `boot.log` (last 40
lines), available at `http://epaper.local/log`.

The texts on the display and in the web interface are German for now; a configurable language
is on the [backlog](backlog.md).