From babbb7c80a58803a6e236b27edfacbf5f3ba4501 Mon Sep 17 00:00:00 2001 From: Jonas Remmert Date: Sat, 3 Aug 2024 11:08:36 +0200 Subject: [PATCH] doc: document ota updates Signed-off-by: Jonas Remmert --- doc/source/architecture/index.rst | 1 + doc/source/architecture/ota.rst | 106 ++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+) create mode 100644 doc/source/architecture/ota.rst diff --git a/doc/source/architecture/index.rst b/doc/source/architecture/index.rst index c78110e0..310f7183 100644 --- a/doc/source/architecture/index.rst +++ b/doc/source/architecture/index.rst @@ -9,3 +9,4 @@ interact with each other. django leshan communication_interfaces + ota diff --git a/doc/source/architecture/ota.rst b/doc/source/architecture/ota.rst new file mode 100644 index 00000000..7d74bf48 --- /dev/null +++ b/doc/source/architecture/ota.rst @@ -0,0 +1,106 @@ +Over the Air Updates +==================== + +Over the Air (OTA) updates are a way to update the firmware of a device +remotely. This is a mandatory feature for any IoT device. The device must be +able to update its firmware without any physical user intervention. + +flownexus implements OTA updates according to the LwM2M protocol. The LwM2M +protocol specifies how to update the firmware of a device. The OTA process is +implemented by sending a link to a firmware via LwM2M object 5/0/1 - Package +URI. This method is called Pull via HTTP(s) and is faster, compared to a +transfer via CoAP. Updates via CoAP blockwise transfer to download the firmware +are not supported. + +More information about a possible firmware implementation can be found in the +``lwm2m_client`` firmware sample at +``flownexus/simulation/lwm2m_client/src/firmware_update.c``. + +.. note:: + + Firmware Updates are implemented in the LwM2M server and the example + firmware. A set up a PKI with self-signed certificates is required for the + server to communicate with the device via https. This setup will be + described in upcoming releases shortly. + +Update process of a Firmware +---------------------------- + +The update process is described in detail in the `LwM2M core specification +v1.1.1`_ Chapter *E.6 LwM2M Object: Firmware Update*. This chapter summarizes +the update process: + +1. flownexus sends a link to the firmware to the device via LwM2M object 5/0/1 + - Package URI. It is a relative link to the firmware on the server, e.g. + ``/media/firmware/v0.1.0.bin``. The host ``https://flownexus.org`` is + fixed in firmware. +2. The device downloads the firmware from the server via http(s) and sets the + state to ``STATE_DOWNLOADING``. +3. The device sets the state to ``STATE_DOWNLOADED`` after the download is + complete. +4. flownexus executes the command 5/0/2 - Update to the device. +5. The device sets the state to ``STATE_UPDATING`` upon receiving the command. +6. The device updates the firmware and communicates the result to flownexus. + +This process ensures that errors during the update process are handled and +communicated to the backend. + +States of a OTA Update +...................... + +There are 4 device states during an OTA update. flownexus tracks the state of +the device during the update process in the database (FirmwareUpdate table). +Once the update is completed (failed or successful), the state is set always +set to ``STATE_IDLE``. + + +.. table:: Device States during an OTA Update + + +-------------------+-----------------------+ + | State | Description | + +===================+=======================+ + | STATE_IDLE | device is idle | + +-------------------+-----------------------+ + | STATE_DOWNLOADING | device is downloading | + +-------------------+-----------------------+ + | STATE_DOWNLOADED | download is complete | + +-------------------+-----------------------+ + | STATE_UPDATING | device is updating | + +-------------------+-----------------------+ + +Result Codes for an OTA Update +.............................. + +For every OTA update, a result is generated after the update failed or +successful. There can be only one active OTA update at a time for each client. +An active OTA is indicated by the result ``RESULT_DEFAULT``. The result for +each OTA update is stored in the database (FirmwareUpdate table). + +.. table:: Result Codes for an OTA Update + + +-------------------------+------------------------+ + | Result | Description | + +=========================+========================+ + | RESULT_DEFAULT | default state | + +-------------------------+------------------------+ + | RESULT_SUCCESS | update was successful | + +-------------------------+------------------------+ + | RESULT_NO_STORAGE | no storage available | + +-------------------------+------------------------+ + | RESULT_OUT_OF_MEM | out of memory | + +-------------------------+------------------------+ + | RESULT_CONNECTION_LOST | connection was lost | + +-------------------------+------------------------+ + | RESULT_INTEGRITY_FAILED | integrity check failed | + +-------------------------+------------------------+ + | RESULT_UNSUP_FW | unsupported firmware | + +-------------------------+------------------------+ + | RESULT_INVALID_URI | invalid uri provided | + +-------------------------+------------------------+ + | RESULT_UPDATE_FAILED | update failed | + +-------------------------+------------------------+ + | RESULT_UNSUP_PROTO | unsupported protocol | + +-------------------------+------------------------+ + + +.. _LwM2M core specification v1.1.1: https://www.openmobilealliance.org/release/LightweightM2M/V1_1_1-20190617-A/OMA-TS-LightweightM2M_Core-V1_1_1-20190617-A.pdf