deploy: ec3e5b2

previews/77/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 5eb4d4947109d54c18fdcb675748692d
+tags: 645f666f9bcd5a90fca523b33c5a78b7

previews/77/_sources/api_doc/api.rst

@@ -0,0 +1,7 @@
+Internal Django
+===============
+
+.. The following text is only a placeholder in case the api can not be
+   generated (e.g. for the pdf version)
+
+The API Documentation is available at https://jonas-rem.github.io/flownexus.

previews/77/_sources/application_guide/endpoint_interactions.rst

@@ -0,0 +1,34 @@
+Endpoint Interactions
+=====================
+
+flownexus can interact with any endpoint via the LwM2M methods ``Read``,
+``Write``, ``Execute`` and ``Observe``.
+
+
+Read
+----
+
+.. note::
+   Currently not supported
+
+Write
+-----
+
+See Chapter :ref:`data-flow-backend-to-endpoint-label` for more details.
+
+
+Execute
+-------
+
+.. note::
+   Currently not supported
+
+Observe
+-------
+
+See chapter :ref:`events-via-composite-observe-label` to see events are
+generated from composite Observe.
+
+.. note::
+   Currently Observe interactions are handled in Leshan, check
+   :ref:`lwm2m-observe-label`.

previews/77/_sources/application_guide/events.rst

@@ -0,0 +1,30 @@
+Events
+======
+
+IoT devices often trigger events. An event is a significant change in the state
+of a device or its environment. As an example, there could be a machine that is
+monitored by an IoT device using multiple sensors. An event is triggered by an
+unusual combination of sensor readings. It is important to aggregate several
+states into a single event, so an application in the cloud can analyze the
+event in detail to know the environmental conditions at that moment.
+
+The database model defines the :term:`Events <Event>` table that represents
+events generated by :term:`endpoints <endpoint>`.
+
+
+.. _events-via-composite-observe-label:
+
+Events via Composite Observe
+----------------------------
+
+In order to group multiple resources together in an unambiguous way, LwM2M
+composite resources are used. Once a composite resource is updated in the IoT
+device (endpoint), Leshan generates a composite event with all values of the
+composite resource. Django deserializes the event, stores its individual
+resources in the database and creates a new event. The individual resources
+within the event may haveindividual timestamps, the event itself has a separate
+timestamp in addition.
+
+.. note::
+   Currently Observe interactions are handled in Leshan at
+   :ref:`lwm2m-observe-label`.

previews/77/_sources/application_guide/fw_setup.rst

@@ -0,0 +1,38 @@
+.. _firmware_setup:
+
+Firmware Setup
+==============
+
+LwM2M Version
+-------------
+
+The used Leshan version uses LwM2M version 1.1. Make sure to enable this
+version in the Zephyr LwM2M client accordingly.
+
+.. code-block:: kconfig
+  :caption: Enable LwM2M version 1.1 in Zephyr
+
+   CONFIG_LWM2M_VERSION_1_1=y
+
+
+LwM2M Transport Format
+----------------------
+
+.. code-block:: kconfig
+  :caption: Enable CBOR Format
+
+   CONFIG_ZCBOR=y
+   CONFIG_ZCBOR_CANONICAL=y
+
+
+LwM2M SenML Format
+------------------
+
+.. note::
+   Currently not supported in flownexus.
+
+.. code-block:: kconfig
+  :caption: Enable LwM2M version 1.1 in Zephyr
+
+   # SenML CBOR - default
+   CONFIG_LWM2M_RW_SENML_CBOR_SUPPORT=y

previews/77/_sources/application_guide/index.rst

@@ -0,0 +1,12 @@
+Application Guide
+=================
+
+This section explains according to best practises how to develop IoT
+applications with flownexus and Zephyr.
+
+.. toctree::
+
+   endpoint_interactions
+   events
+   queue_mode
+   fw_setup

previews/77/_sources/application_guide/queue_mode.rst

@@ -0,0 +1,43 @@
+Queue Mode
+==========
+
+When configuring a energy saving endpoint that uses LTE-M or NB-IoT, queue mode
+must be enabled in Zephyr so the device will sleep between data transmissions.
+The `Zephyr documentation
+<https://docs.zephyrproject.org/latest/connectivity/networking/api/lwm2m.html>`_
+explains the LwM2M Client in Zephyr in detail.
+
+.. code-block:: kconfig
+  :caption: Enable Queue Mode in Zephyr with a registration update interval of
+   10 minutes
+
+   CONFIG_LWM2M_QUEUE_MODE_ENABLED=y
+   CONFIG_LWM2M_QUEUE_MODE_UPTIME=20
+   CONFIG_LWM2M_RD_CLIENT_STOP_POLLING_AT_IDLE=y
+
+   # Default lifetime is 10 minutes
+   CONFIG_LWM2M_ENGINE_DEFAULT_LIFETIME=600
+
+See chapter :ref:`data-flow-backend-to-endpoint-label` to know know more about
+how queue mode is implemented in flownexus.
+
+eDRX Settings
+-------------
+
+eDRX (Extended Discontinuous Reception) is a feature that allows the device to
+sleep for longer periods of time. The device will wake up periodically to check
+downlink paging messages. If new messages are available, the device will stay
+awake to receive them. Otherwise, the device will go back to sleep. - `Nordic
+Devzone Article
+<https://devzone.nordicsemi.com/nordic/nordic-blog/b/blog/posts/maximizing-battery-lifetime-in-cellular-iot-an-analysis-of-edrx-psm-and-as-rai>`_
+
+Setting the eDRX interval to a value significantly smaller than the timeout
+value of the LwM2M server would theoretically allow flownexus to reach
+endpoints at any time.
+
+.. warning::
+
+   This approach has not yet been tested! The typical way is to configure
+   endpoints to connect to the server within specific intervals. Inbetween
+   those intervalls, the endpoint will sleep and can't be reached from the
+   server.

previews/77/_sources/architecture/communication_interfaces.rst

@@ -0,0 +1,183 @@
+Communication, Interfaces
+==========================
+
+The communication between IoT devices and Leshan is specified by the OMA LwM2M
+standard:
+
+- `LwM2M core specification v1.1.1`_
+- `LwM2M transport binding v1.1.1`_
+
+.. _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
+.. _LwM2M transport binding v1.1.1: https://www.openmobilealliance.org/release/LightweightM2M/V1_1_1-20190617-A/OMA-TS-LightweightM2M_Transport-V1_1_1-20190617-A.pdf
+
+The standard describes how the LwM2M server (Leshan) works, however, it does
+not describe how to connect a backend server to Leshan. The backend is
+responsible for storing the data in a database and implementing application
+logic. A frontend can access the data in the database and visualize outward
+facing user interfaces. Leshan acts as a gateway between Endpoints and the
+backend. There should be no application specific logic implemented in Leshan.
+
+In order to communicate and exchange data, both components (Leshan LwM2M Server
+and Django) post data to each other's ReST APIs. Communication is typically
+triggered by IoT devices sending data or the user/application requesting data
+from devices.
+
+Data Flow: Endpoint -> Backend
+------------------------------
+
+All communication from Endpoints to the server flows through Leshan. Leshan
+interprets this data according to the LwM2M protocol and generates a ReST API
+call to the backend server. The backend server then stores the data in the
+database.
+
+Django hosts the ReST API that Leshan posts to. Serializers, a part of Django,
+deserialize the incoming data and store it in the database according to the
+database model.
+
+Leshan Data Format
+..................
+
+There are two types of data that Leshan sends to the backend, single resource
+and composite resource format. The two ReST API endpoints that Leshan posts to
+are available under the following URLs:
+
+- ``/leshan_api/resource/single``: single resource format.
+- ``/leshan_api/resource/composite``: composite resource format.
+
+For more details, please theck the ``Internal Django`` API documentation.
+
+.. code-block:: json
+  :caption: Single Resource Format (3303/0/5700)
+
+  {
+     "ep": "qemu_x86",
+     "obj_id": 3303,
+     "val": {
+         "kind": "singleResource",
+         "id": 5700,
+         "type": "FLOAT",
+         "value": "24.899181214836236"
+     }
+  }
+
+.. code-block:: json
+  :caption: Composite Resource Format (3/0/0..17)
+  :emphasize-lines: 8,26,23
+
+  {
+      "ep" : "qemu_x86",
+      "val" : {
+          "instances" : [ {
+              "kind" : "instance",
+              "resources" : [ {
+                  "kind" : "singleResource",
+                  "id" : 0,
+                  "type" : "STRING",
+                  "value" : "Zephyr"
+              }, {
+                  "kind" : "multiResource",
+                  "values" : {
+                      "0" : "1",
+                      "1" : "5"
+                  },
+              },
+                  "kind" : "singleResource",
+                  "id" : 17,
+                  "type" : "STRING",
+                  "value" : "qemu_x86"
+              } ],
+              "id" : 0
+          } ],
+          "kind" : "obj",
+          "id" : 3
+      }
+  }
+
+The marked lines in the composite resource format show where Object ID,
+Instance ID and Resource ID are located. A composite resource format can
+consist of multiple Object IDs.
+
+.. warning::
+
+  Currently multiResources are not supported and will be ignored. MultiResource
+  dataypes  are e.g. used for Voltage range (min, max).
+
+Registration Updates
+....................
+
+Leshan maintains registrations of endpoints. An endpoint can be registered or
+unregistered. To maintain its registration, an endpoint must send an update to
+Leshan regularly. If an endpoint does not send an update within the specified
+duration, it is considered offline and will be unregistered by Leshan.
+
+Those registration events are encapsulated into an LwM2M Object and sent to the
+backend server. The backend server stores the registration events in the
+database. This allows to use the generic database model for the registration
+events as well. All received registration events are stored in the database and
+can be used for statistics.
+
+All registration events are maintained in the custom LwM2M Object ID ``10240``:
+
+- ``10240/0/0``: Endpoint **registered** to Leshan.
+- ``10240/0/1``: Endpoint **unregistered** from Leshan.
+- ``10240/0/2``: Endpoint **updated** its registration.
+
+.. _data-flow-backend-to-endpoint-label:
+
+Data Flow: Backend -> Endpoint
+------------------------------
+
+:term:`Endpoints <endpoint>` often operate in queue mode, meaning they are not
+always online. The LwM2M Server is aware of the current status of a device
+(Online/Offline) and communicates this status to the backend server. Leshan
+does not queue pending data that should be sent to the device when it comes
+online. The backend server must handle this by itself so it has to have a
+representation of the current status of each device as well as the data to be
+send. The resource table ``EndpointOperation`` is used to store pending
+operations that should be sent to the endpoint while it is online.
+
+Once an endpoint updates it's registration (LwM2M Update Operation) Leshan
+notifies the backend. The backend checks the ``EndpointOperation`` table for
+pending operations and sends them to the device by posting to the Leshan hosted
+ReST API. Leshan keeps the post call open until the device acknowledges the
+operation or a timeout is generated. Endpoints can be slow to respond (several
+Seconds), so the backend has to handle the ReST API call in an asynchronous
+manner. By only sending data to endpoints while they are online, the backend
+can be sure that the ReST API calls are not open for a long time.
+
+Asynchronous Communication
+..........................
+
+Given that endpoints are comparably slow to respond, handling communication
+asynchronously is essential for efficient operation. This can be effectively
+managed using Celery, a distributed task queue. When Leshan notifies the
+backend of an endpoint status update, Celery can be used to handle the
+long-running API calls, ensuring that the backend remains responsive and
+scalable. As the backend communicates with many endpoints simultaneously, an
+efficient queing mechanism is essential to ensure that the system remains
+responsive and scalable.
+
+Before the backend executes the API call, it updates the endpointOperation
+status to ``SENDING``, indicating an ongoing operation.
+
+Once the API call is complete the database will be updated with the result
+(e.g. ``CONFIRMED``, ``FAILED``, ``QUEUED``) depending on the result of the
+request. The ``FAILED`` status is assigned after 3 attempts. Retransmissions are
+triggered when the endpoint updates it's registration the next time.
+
+Example Communication
+.....................
+
+The following example shows how the backend server can send a firmware download
+link resource ``Package URI 5/0/1`` to an endpoint:
+
+#. User creates new ``EndpointOperation``: resource path ``5/0/1``, value
+   ``https://url.com/fw.bin``.
+#. Backend checks endpoint online status.
+#. If endpoint is offline, no further action is taken right away.
+#. Endoint comes online, Leshan sends update to the backend.
+#. Backend checks ``EndpointOperation`` table for pending operations for the
+   endpoint.
+#. Finds pending operation, send resource to endpoint via the Leshan ReST API.
+#. Pending operation is marked ``completed`` if the endpoint acknowledges the
+   operation.