schedule
========

.. py:module:: schedule

.. autoapi-nested-parse::

   When to fetch data, when to stay awake and how long to sleep.



Attributes
----------

.. autoapisummary::

   schedule.FETCH_SLACK_S
   schedule.MINUTES_PER_DAY


Functions
---------

.. autoapisummary::

   schedule.awake_window_s
   schedule.fetch_due
   schedule.ms_to_next_minute
   schedule.is_night
   schedule.update_mode
   schedule.minutes_until
   schedule.sleep_ms
   schedule.full_refresh_due
   schedule.next_fetch_s


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

.. py:data:: FETCH_SLACK_S
   :value: 30


.. py:function:: awake_window_s(woke_from_deep_sleep, window_s)

   Seconds to keep the web API up before sleeping.

   Only after a reset (power on, reset button, deploy): that is when a
   person may want to reach the board. Timer wakes go straight back
   to sleep to save battery.


.. py:function:: fetch_due(woke_from_deep_sleep, state, now_s, interval_s)

   Decide whether this wake fetches new data.

   A fetch means connecting to the WLAN and redrawing the whole screen;
   otherwise only the header is updated.


.. py:function:: ms_to_next_minute(ms_into_minute, margin_ms=500, min_ms=1000)

   Return the sleep time to wake just after the next full minute.

   That way a displayed time changes right when the minute does.


.. py:data:: MINUTES_PER_DAY
   :value: 1440


.. py:function:: is_night(minute, start, end)

   Check whether local `minute` (since midnight) lies in [start, end).

   The range may span midnight, as from 23:00 to 06:00 does.


.. py:function:: update_mode(minute, battery_percent, battery_modes, night, night_interval_s)

   (fetch interval in s, minute clock on?) for the current conditions.

   `battery_modes` are (from percent, fetch interval s, minute clock) rows,
   highest threshold first; the first row the battery reaches applies.
   During `night` ((start, end) in local minutes; None disables it) the
   clock is off and fetches are at most every `night_interval_s`. With an
   unset clock (`minute` None) there is no night.


.. py:function:: minutes_until(minute, target)

   Minutes from local `minute` to the next `target` (1..1440).


.. py:function:: sleep_ms(ms_into_minute, clock, since_fetch_s, interval_s, until_change_s=None)

   Deep sleep time until the next wake, always just after a full minute.

   With the minute clock on, that is the next minute. Otherwise it is the
   next fetch (`interval_s` after the last one, `since_fetch_s` ago), or
   `until_change_s` if the mode changes earlier (e.g. the night ends).


.. py:function:: full_refresh_due(had_full_since_reset, full_at, now_s, interval_s)

   Decide whether a data update needs a full (flashing) refresh.

   It does first after any reset other than a deep-sleep wake (the saved
   image may not match the panel, after an interrupted update for
   instance), otherwise every `interval_s` against ghosting.


.. py:function:: next_fetch_s(fetched_s, interval_s)

   Return when the next fetch will happen.

   That is the first full minute from which `fetch_due` accepts it; see
   `sleep_ms`, which wakes the board then.