battery_forecast
================

.. py:module:: battery_forecast

.. autoapi-nested-parse::

   Discharge rate and runtime forecast from Home Assistant's history.

       uv run tools/battery_forecast.py [--since 2026-09-27T08:12] [--hours 72]

   Takes the battery level recorded since the board last stopped charging
   (sensor.epaper_ladezustand), or since --since (local time), fits a line
   through it and projects when the levels that change the update pace are
   reached.



Attributes
----------

.. autoapisummary::

   battery_forecast.CHARGE_STATE


Functions
---------

.. autoapisummary::

   battery_forecast.parse_time
   battery_forecast.discharge_start
   battery_forecast.fit
   battery_forecast.forecast
   battery_forecast.history
   battery_forecast.main


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

.. py:data:: CHARGE_STATE
   :value: 'sensor.epaper_ladezustand'


.. py:function:: parse_time(text)

   Parse an ISO time from Home Assistant, including a "Z" suffix.


.. py:function:: discharge_start(states)

   Find when the board last stopped charging.

   From `[(time, state)]` this is the first report after the last
   "charging", or the first report at all if none was charging; None if
   it is charging now. (On battery the board mostly reports "stable": the
   discharge in the deep-sleep cycle is below the gauge's resolution.)


.. py:function:: fit(points)

   Least-squares line through [(hours, percent)]: (slope %/h, intercept).


.. py:function:: forecast(levels, start, now)

   Rate and projections from [(time, percent)] since `start`.


.. py:function:: history(entity_ids, since, until)

   Load the state history of `entity_ids` from Home Assistant.


.. py:function:: main()

   Run the command line tool.