From e2d5f3ffd104481284c2d0c8be1056695bf50ea9 Mon Sep 17 00:00:00 2001 From: Tim Anderson Date: Wed, 24 Jan 2024 11:35:07 -0700 Subject: [PATCH] Document the choices of OTA operations Signed-off-by: Tim Anderson --- source/user-guide/custom-sota-client.rst | 39 ++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 3 deletions(-) diff --git a/source/user-guide/custom-sota-client.rst b/source/user-guide/custom-sota-client.rst index ec0eb3e3..a0a99136 100644 --- a/source/user-guide/custom-sota-client.rst +++ b/source/user-guide/custom-sota-client.rst @@ -1,7 +1,40 @@ .. _ug-custom-sota-client: +Customizing Over The Air Updates +================================ + +By default, Secure Over The Air update (SOTA), operates as a daemon process (ref:`ref-aktualizr-lite`) which +periodically checks for updates. If an update is available, it will automatically download, and install +it to a device that is following the update tag. + +This is not always the desired operation. There are a couple ways to control this operation: + +#. Callbacks +#. Custom Update Agent + +Callbacks +--------- + +Aktualizr-lite provides the ability to run an executable at the following OTA operations: + +* Before checking in — check-for-update-pre return: none +* After checking in — check-for-update-post return: OK or FAILED: reason +* Before a download — download-pre return: none +* After a download — download-post return: OK or FAILED: reason +* Before an install — install-pre return: none +* After an install — install-post return: NEEDS_COMPLETION, OK, or FAILED: reason +* After a reboot — install-final-pre return: none + +A simple recipe is in `aktualizr-callback`_ and a sample script is in `callback-handler`_. + +.. _`aktualizr-callback`: + https://github.com/foundriesio/meta-lmp/blob/main/recipes-sota/aktualizr/aktualizr-callback_1.0.bb + +.. _`callback-handler`: + https://github.com/foundriesio/meta-lmp//blob/main/recipes-sota/aktualizr/aktualizr-callback/callback-handler + Custom Update Agents -==================== +-------------------- This section shows how to create a custom update agent—"SOTA client"—for your platform. :ref:`ref-aktualizr-lite` is a general purpose SOTA client that fits many needs. @@ -12,7 +45,7 @@ In these cases, a custom SOTA client can be written in C++ using the aktualizr-l https://github.com/foundriesio/aktualizr-lite/blob/master/include/aktualizr-lite/api.h Using the Custom SOTA Client Example ------------------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The example `SOTA client`_ in aktualizr-lite is a great place to start experimenting. The ``meta-lmp`` layer includes a recipe_ that runs this example as the default SOTA client. @@ -33,7 +66,7 @@ Users can build this custom client into their LmP image with a small addition to echo 'SOTA_CLIENT = "custom-sota-client"' >> conf/machine/include/lmp-factory-custom.inc Forking the custom SOTA Client -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +"""""""""""""""""""""""""""""" Producing a factory-specific SOTA client can be done by: