ota
===

.. py:module:: ota

.. autoapi-nested-parse::

   Firmware updates over the WLAN (`deploy_wlan` is the client).

   Endpoints (raw routes for webapi.handle), all requiring the header
   "Authorization: Bearer <password>"::

       GET    /api/files         {name: sha256 hex} of the files on the board
       PUT    /api/files/<name>  store the request body as <name>
       DELETE /api/files/<name>  remove <name>
       POST   /api/reset         restart once the answer is sent; an optional
                                 body {"version": "0.2.2"} names the new version

   Uploads go to "<name>.part" first and are renamed when complete, so an
   interrupted transfer leaves the old file intact. Names are restricted to
   plain module/data file names in the root directory.



Attributes
----------

.. autoapisummary::

   ota.EXTENSIONS
   ota.NAME_CHARS
   ota.MAX_NAME
   ota.MAX_VERSION
   ota.MAX_RESET_BODY


Classes
-------

.. autoapisummary::

   ota.Updater


Functions
---------

.. autoapisummary::

   ota.valid_name
   ota.sha256_hex


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

.. py:data:: EXTENSIONS
   :value: ('py', 'mpy', 'json', 'txt')


.. py:data:: NAME_CHARS
   :value: 'abcdefghijklmnopqrstuvwxyz0123456789_'


.. py:data:: MAX_NAME
   :value: 40


.. py:data:: MAX_VERSION
   :value: 40


.. py:data:: MAX_RESET_BODY
   :value: 200


.. py:function:: valid_name(name)

   Check for a plain file name like "main.py".

   Allowed are lowercase letters, digits and "_", a dot and one of
   EXTENSIONS.


.. py:function:: sha256_hex(chunks)

   Return the SHA-256 of the concatenated byte `chunks` as hex text.


.. py:class:: Updater(password, on_reset, root='')

   Handlers for the update endpoints listed in the module docstring.

   Every handler takes webapi's raw-route arguments `(rest, headers,
   length, chunks)` and returns a JSON-able dict or a `webapi.reply`.


   .. py:attribute:: updated
      :value: []



   .. py:attribute:: removed
      :value: []



   .. py:attribute:: new_version
      :value: None



   .. py:method:: raw_routes()

      Return the routes to register with `webapi.handle`.



   .. py:method:: list_files(rest, headers, length, chunks)

      GET /api/files: the board's files with their SHA-256.



   .. py:method:: put_file(name, headers, length, chunks)

      PUT /api/files/<name>: store the body, replacing `name` at the end.



   .. py:method:: delete_file(name, headers, length, chunks)

      DELETE /api/files/<name>: remove the file.



   .. py:method:: reset(rest, headers, length, chunks)

      POST /api/reset: ask for a restart after the answer.