firmware
========

.. py:module:: firmware

.. autoapi-nested-parse::

   Which files go onto the board, compiled with mpy-cross where possible.

   Modules are precompiled to .mpy: importing them then skips compiling on
   the board, which for the large fonts alone saves over a second per wake.
   Entry points and the installation's config.py stay source files.

   The build adds version.mpy with VERSION, the firmware version from git
   (see `version`), which the board shows in its boot sequence, in Home
   Assistant and in the web interface.



Attributes
----------

.. autoapisummary::

   firmware.ROOT
   firmware.SRC
   firmware.OUT
   firmware.SOURCE_FILES
   firmware.EXCLUDED
   firmware.RETIRED


Functions
---------

.. autoapisummary::

   firmware.modules
   firmware.version
   firmware.build
   firmware.stale_names


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

.. py:data:: ROOT

.. py:data:: SRC

.. py:data:: OUT

.. py:data:: SOURCE_FILES
   :value: ('boot.py', 'main.py', 'config.py')


.. py:data:: EXCLUDED
   :value: ('config_example.py', 'credentials.py')


.. py:function:: modules()

   Source modules that are compiled to .mpy.


.. py:function:: version(run=subprocess.run)

   Return the firmware version from git.

   It is the last tag without its "v" ("0.2.0"), with the commits since
   and the current one if there are any ("0.2.0-3-g6ec6236"), and
   "-dirty" for uncommitted changes. Without git or tags it is the commit
   hash, or "unknown".


.. py:function:: build()

   Compile the modules into build/mpy/ where they changed.

   :returns: The local paths of all files for the board.


.. py:data:: RETIRED
   :value: ('credentials.py', 'bootscreen.mpy')


.. py:function:: stale_names()

   List the files to remove from the board.

   These are the sources the compiled modules replace, and retired files.