UpdateHub embedded Firmware Over-The-Air (FOTA) sample ###################################################### Overview ******** UpdateHub is an enterprise-grade solution which makes it simple to remotely update all your embedded devices. It handles all aspects related to sending Firmware Over-the-Air (FOTA) updates with maximum security and efficiency, while you focus on adding value to your product. It is possible to read more about at `docs.updatehub.io`_. This sample shows how to use UpdateHub in both a polling and manual update mode. Polling mode runs automatically on a predefined period, probing the server for updates and installing them without requiring user intervention. You can access the sample source code for this mode updatehub_polling. Manual mode requires the user to call the server probe and then, if there is an available update, also requires the user to decide if it is appropriate to update now or later. You can access the sample source code for this mode updatehub_manual. Caveats ******* * The Zephyr port of ``UpdateHub`` is configured to run on a :ref:`Freedom-K64F ` MCU by default. The application should build and run for other platforms with offer support internet connection. Some platforms need some modification. Overlay files would be needed to support BLE 6lowpan, 802.15.4 or OpenThread configurations as well as the understanding that most other connectivity options would require an edge gateway of some sort (Border Router, etc). * The MCUboot bootloader is required for ``UpdateHub`` to function properly. More information about the Device Firmware Upgrade subsystem and MCUboot can be found in :ref:`mcuboot`. Building and Running ******************** The below steps describe how to build and run the ``UpdateHub`` sample in Zephyr. Where examples are given, it is assumed the sample is being built for the Freedom-K64F Development Kit (``BOARD=frdm_k64f``). Step 1: Build MCUboot ===================== Build MCUboot by following the instructions in the :ref:`mcuboot` documentation page. Step 2: Flash MCUboot ===================== Flash the resulting image file to the 0x0 address of the flash memory. This can be done in multiple ways, but the most common ones would be using make or ninja: .. code-block:: console make flash # or ninja flash Step 3: Start the updatehub Community Edition ============================================= By default, the updatehub application is set to start on the UpdateHub Cloud. For more details on how to use the UpdateHub Cloud please refer to the documentation on `updatehub.io`_. The UpdateHub Cloud has the option to use CoAPS/DTLS or not. If you want to use the CoAPS/DTLS, simply add the ``overlay-dtls.conf`` before building. You must only use the provided certificate for the test example. Otherwise, you should create a new certificate using these commands: .. code-block:: console openssl genrsa -out privkey.pem 512 openssl req -new -x509 -key privkey.pem -out servercert.pem The cert and private key that will be embedded into ``certificates.h`` in your application, can be generated like this: .. code-block:: console openssl x509 -in servercert.pem -outform DER -out servercert.der openssl pkcs8 -topk8 -inform PEM -outform DER -nocrypt -in privkey.pem \ -out privkey.der If you would like to use your own server, the steps below explain how updatehub works with updatehub-ce running, started by the following Docker command: .. code-block:: console docker run -it -p 8080:8080 -p 5683:5683/udp --rm \ updatehub/updatehub-ce:latest Using this server, create your own ``overlay-prj.conf``, setting the option :option:`CONFIG_UPDATEHUB_SERVER` with your local IP address and the option :option:`CONFIG_UPDATEHUB_CE` with true. If you're using the polling mode on UpdateHub, you'll also need to set the option :option:`CONFIG_UPDATEHUB_POLL_INTERVAL` with the polling period of your preference, remembering that the limit is between 0 and 43200 minutes (30 days). This server does not use DTLS, so you must not add ``overlay-dtls.config``. This sample uses IPv4 by default, but you can use IPv6 by enabling IPv6 and configuring your IP address. Step 4: Build UpdateHub ======================= ``UpdateHub`` can be built for the frdm_k64f as follows: .. zephyr-app-commands:: :zephyr-app: samples/subsys/mgmt/updatehub :board: frdm_k64f :conf: "prj.conf overlay-prj.conf" :goals: build .. _updatehub_sample_sign: Step 5: Sign the first image ============================ From this section onwards you use a binary (``.bin``) image format. Using MCUboot's :file:`imgtool.py` script, sign the :file:`zephyr.bin` file you built in Step 3. In the below example, the MCUboot repo is located at :file:`~/src/mcuboot`. .. code-block:: console ~/src/mcuboot/scripts/imgtool.py sign \ --key ~/src/mcuboot/root-rsa-2048.pem \ --align 8 \ --version 1.0.0 \ --header-size 0x200 \ --slot-size \ --pad \ signed.bin The command above creates an image file called :file:`signed.bin` in the current directory. Step 6: Flash the first image ============================= Upload the :file:`signed.bin` file from Step 4 to image slot-0 of your board. The location of image slot-0 varies by board, as described in :ref:`mcuboot_partitions`. For the frdm_k64f, slot-0 is located at address ``0xc000``. Using :file:`pyocd` you don't need to specify the slot-0 starting address. .. code-block:: console sudo pyocd-flashtool Step 7: Signing the test image ============================== For the update to be correctly validated on the server, you must need sign the (``bin``) image, piping the output to another file. .. code-block:: console ~/src/mcuboot/scripts/imgtool.py sign \ --key ~/src/mcuboot/root-rsa-2048.pem \ --align 8 \ --version 2.0.0 \ --header-size 0x200 \ --slot-size \ --pad \ signed_v2.bin Step 8: Create a package with UpdateHub Utilities (uhu) ======================================================= First, install UpdateHub Utilities (``uhu``) on your system, using: .. code-block:: console pip3 install --user uhu After installing uhu you will need to set the ``product-uid``: .. code-block:: console uhu product use "e4d37cfe6ec48a2d069cc0bbb8b078677e9a0d8df3a027c4d8ea131130c4265f" Then, add the package and its mode (``zephyr``): .. code-block:: console uhu package add signed_v2.bin -m zephyr Then inform what ``version`` this image is: .. code-block:: console uhu package version 2.0.0 And finally you can build the package by running: .. code-block:: console uhu package archive --output .pkg Step 9: Add the package to server ================================== Now, add the package to the updatehub-ce by, opening your browser to the server URL, ``:8080``, and logging into the server using ``admin`` as the login and password by default. After logging in, click on the package menu, then ``UPLOAD PACKAGE``, and select the package built in step 7. Step 10: Register device on server ================================== Register your device at updatehub-ce by using a terminal session on the system where you were debugging the board, and type the following command: .. code-block:: console updatehub run If everything is alright, it will print on the screen ``No update available``. Step 11: Create a rollout ========================= In the browser where the updatehub-ce is open, click on ``menu Rollout`` and then ``CREATE ROLLOUT``. Select the version of the package that you added in step 9. With that, the update is published, and the server is ready to accept update requests. Step 12: Run the update ======================= Back in the terminal session that you used for debugging the board, type the following command: .. code-block:: console updatehub run And then wait. The board will ping the server, check if there are any new updates, and then download the update package you've just created. If everything goes fine the message ``Image flashed successfully, you can reboot now`` will be printed on the terminal. Step 13: Reboot the system ========================== In the terminal you used for debugging the board, type the following command: .. code-block:: console kernel reboot cold Your board will reboot and then start with the new image. After rebooting, the board will automatically ping the server again and the message ``No update available`` will be printed on the terminal. .. _updatehub.io: https://updatehub.io .. _docs.updatehub.io: https://docs.updatehub.io/