main
====

.. py:module:: main

.. autoapi-nested-parse::

   Update the dashboard, then deep-sleep until the next update.

   On battery the mode depends on the charge level and the time of day (see
   config.BATTERY_MODES and config.NIGHT): fetches (WLAN, new data, whole
   screen) come every 10 to 60 minutes, and the header shows the time of the
   last data and of the next fetch. A mode may also run a minute clock,
   which updates the header every minute with a partial refresh and without
   WLAN. A low battery shows a charging notice in the bottom-left tile.

   On external power (USB) the board stays awake instead: fetches every
   config.FETCH_INTERVAL_S, and the web interface on http://<hostname>.local/
   (tile settings, /battery, /log) is always up. On battery it serves the
   web interface only after a reset (not a timer wake), for
   config.AWAKE_AFTER_RESET_S seconds, or while the maintenance switch in
   Home Assistant is on.

   This is the entry point: importing it runs one wake and ends in deep
   sleep.



Functions
---------

.. autoapisummary::

   main.feed
   main.battery_status
   main.charging
   main.usb_power
   main.boot_log
   main.on_external_power
   main.battery_mode
   main.current_header
   main.connect_wlan
   main.sync_clock
   main.make_source
   main.mqtt_device
   main.mqtt_client
   main.report_status
   main.fetch_and_redraw
   main.layout_tiles
   main.mark_full_refresh
   main.low_battery_notice
   main.make_band
   main.update_header
   main.ms_into_minute
   main.update
   main.stay_awake
   main.poll_and_feed
   main.request_reset
   main.make_server
   main.show_update
   main.serve_for
   main.maintenance
   main.redraw
   main.save_tiles
   main.save_alerts
   main.tiles_saved
   main.routes
   main.count_wake
   main.sleep_ms


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

.. py:function:: feed()

   Keep the watchdog from resetting the board.


.. py:function:: battery_status()

   GET /battery: the fuel gauge readings (see battery.as_dict).

   With a USB divider also the measured USB voltage, for checking it.


.. py:function:: charging()

   Whether to show the charging symbol: on USB power, or charging.


.. py:function:: usb_power()

   Whether USB power is present, or None without a divider.


.. py:function:: boot_log()

   GET /log: the last lines of the boot log.


.. py:function:: on_external_power(awake=False)

   Whether the board runs on USB power (see battery.on_external_power).


.. py:function:: battery_mode()

   How often to fetch and whether the clock runs, on battery.


.. py:function:: current_header(online, online_at=None, fetched_at=None)

   Build the header for now.

   Its time shows the last data that arrived and the next planned fetch,
   such as "Stand 14:20 · neu 14:30" (see `header`).


.. py:function:: connect_wlan()

   Join one of the configured WLANs unless already connected.


.. py:function:: sync_clock()

   Set the RTC to UTC via NTP.

   The RTC keeps running in deep sleep, so a failed sync still leaves the
   last known time.


.. py:function:: make_source()

   The data source for the configured tiles (see `datasource`).


.. py:function:: mqtt_device()

   Return (device ID, hamqtt.Device) for this board.


.. py:function:: mqtt_client(device_id, role='status')

   Create an MQTT client for the configured broker.

   Each `role` needs its own client ID, or the broker drops an open
   connection when another one with the same ID arrives.


.. py:function:: report_status(stats=None)

   Publish battery and charge state to Home Assistant via MQTT.

   Called only when the WLAN is up anyway for fetching. `stats` are the
   awake statistics (see awake_stats.summary), if any.

   :returns: Whether the maintenance switch is on.


.. py:function:: fetch_and_redraw(saved)

   Fetch new data, report to MQTT, redraw the screen and save the state.

   `saved` is the state from the previous wake, or None.


.. py:function:: layout_tiles(readings, online, now)

   Tiles for the layout, with trend arrows from the kept history.

   Fresh readings are added to the history; cached ones (offline) are not.


.. py:function:: mark_full_refresh()

   Note that a full refresh has happened since this boot.


.. py:function:: low_battery_notice()

   Lines of the charging notice, or None while the battery is fine.


.. py:function:: make_band()

   Return (framebuffer, buffer) for the header band.


.. py:function:: update_header(saved)

   Redraw only the header, with a partial refresh, if it changed.


.. py:function:: ms_into_minute()

   Milliseconds since the start of the current minute.


.. py:function:: update(woke)

   One dashboard update: full with new data when due, else the header.


.. py:function:: stay_awake()

   Awake mode until the board runs on battery again.


.. py:function:: poll_and_feed(server)

   Wrap `server.poll` for the watchdog and for restarts.

   The returned function feeds the watchdog and restarts the board once
   an update has asked for it, after the answer was sent.


.. py:function:: request_reset()

   Restart the board after the current request (see poll_and_feed).


.. py:function:: make_server()

   Web server with the tile settings, status and update endpoints.


.. py:function:: show_update()

   Show which files the update changed, if status screens are on.


.. py:function:: serve_for(seconds)

   Answer web requests for `seconds`, feeding the watchdog.


.. py:function:: maintenance()

   Stay awake while the maintenance switch is on.

   For at most config.MAINTENANCE_S the web interface and updates over
   the WLAN are available, with the WLAN symbol shown. Then the board goes
   back to sleep.


.. py:function:: redraw()

   Full update now, whether due or not.


.. py:function:: save_tiles(new)

   Store and use a new tile configuration.


.. py:function:: save_alerts(new)

   Store and use new warning sources.


.. py:function:: tiles_saved(saved)

   Schedule a redraw after the web interface saved the tiles.


.. py:function:: routes()

   Status endpoints plus the web interface for the tiles.


.. py:function:: count_wake()

   Add this wake's awake time to the statistics in the RTC state.


.. py:function:: sleep_ms()

   Return how long to deep-sleep.

   With the minute clock on, that is until the next minute; otherwise
   until the next fetch or the end of the night, whichever comes first.