hawkBit Update & Device Management Manual (L-1034e.A0)

Table of Contents

hawkBit Update & Device Management Manual (L-1034e.A0)
Document TitlehawkBit Update & Device Management Manual (L-1034e.A0)
Article NumberL-1034e.A0
Release Date23.05.2022

Introduction

This manual describes how to set up a simple hawkBit server for updating phyBOARDs with RAUC. After reading this manual, you will be able to:

  • run a simple hawkBit server using a pre-built Docker image,
  • set up an intermediate client managing communication between RAUC and hawkBit,
  • upload and deploy update bundles with hawkBit to a target device.

Prerequisites

To try out hawkBit with this guide, install Docker in order to run the hawkBit container:

host$ sudo apt-get install docker.io

Connect the phyBOARD with a LAN cable to the host computer. The setup is the same as described in the respective BSP manual, where the target board has the static IP address 192.168.3.11 and the host 192.168.3.10. It is also possible to use DHCP and have the addresses assigned automatically, which should be the default. To find out the IP address of your host computer, execute the following:

host$ ip a

This will print the configured addresses of all interfaces. Be sure to look at the right interface being connected to the phyBOARD and note down the address, e.g. 192.168.3.10.

The target board must be flashed with a RAUC image. For detailed instructions, see our RAUC manual.

For instructions on how to set up IP addresses of your device manually, see the respective BSP Software Manual for your hardware.

Setting Up a Local hawkBit Server

First, we set up the hawkBit server on the local computer. For this, run the hawkBit Docker container:

host$ sudo docker run -d -p 8080:8080 hawkbit/hawkbit-update-server:latest

Tip

For other ways of setting up a hawkBit server, see the official Eclipse hawkBit documentation: https://www.eclipse.org/hawkbit/gettingstarted/

Check the status of the running container:

host$ sudo docker ps -a

Open the hawkBit UI in a web browser by visiting http://localhost:8080 and login with the default username "admin" and password "admin".

Enable authentication via a security token for now. This can be changed with System ConfigAllow targets to authenticate directly with their target security token:

Save the changes by clicking on the save icon at the bottom of the screen.

Note

Using tokens for authentication makes prototyping easy, but it is highly recommended to use certificates and a reverse proxy in a production environment instead, as the security token can be easily stolen.

For more help on this topic, refer to our Security Manual or the security services we provide.

Tip

To reduce the time between checking for new updates, you may change the polling time in the System Config to a minimum of 30 seconds. This is helpful when testing the update system, as otherwise, you may have to wait for up to 5 minutes (default polling time) before the updated bundle is downloaded.

Next, create a new target device in hawkBit. On the Deployment page click the plus sign next to Targets:

Enter a target controller ID to your liking. This should be human-readable, e.g. in this case, "nano-1" was entered. Retrieve the security token by looking into the target's Details tab:

Setting Up an Intermediate Client

For the hawkBit server and the target devices to be able to communicate with each other, an intermediate client is needed which translates the DDI API ("Direct Device Integration", essentially a REST API) calls to RAUC's D-Bus API. This is where the rauc-hawkbit-updater comes in handy. It serves as a translator between these two.

Power up your phyBOARD and connect a serial terminal to it, e.g. using SSH:

host$ ssh root@192.168.3.11

Edit the rauc-hawkbit-updaterconfiguration on the target:

target$ vi /etc/rauc-hawkbit-updater/config.conf

Change the hawkbit_server and target_name, as well as the target's individual security token, that we retrieved earlier. Edit the text by first typing in i:

/etc/rauc-hawkbit-updater/config.conf
hawkbit_server = 192.168.3.10:8080
target_name = nano-1
auth_token = acbe0c787e927ad37cd05719616da4fe

Other settings may be left at the default. Save the changes and close the editor by pressing ESC and typing in :wq.

Restart the systemd service of rauc-hawkbit-updater:

target$ systemctl restart rauc-hawkbit-updater

Observe the output of the service:

target$ journalctl --no-pager -fu rauc-hawkbit-updater

If everything went well you should see the device checking for new software:

Feb 09 09:56:30 phyboard-polis-imx8mn-1 systemd[1]: Started HawkBit client for Rauc.
Feb 09 09:56:32 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Checking for new software...
Feb 09 09:56:32 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: No new software.

The hawkBit UI should now show the time the target was last seen in its Details tab:


Uploading RAUC Bundles to the hawkBit Server

In hawkBit, an update is split into subcategories to accommodate for various combinations of operating system and application updates. For this example, we will focus on OS updates only, as this is what RAUC bundles usually update.

First, create a new software module by clicking on the plus sign in the Upload category under Software Module:

Enter a name and version to your liking. This software module will contain a full OS bundle. Click on Upload File and choose a fitting RAUC bundle provided by our official BSP releases or by your own custom build. The bundle always has the .raucb file extension and must be compatible with the machine being used. For example for a phyBOARD-Polis with i.MX8M Mini the phytec-headless-bundle for the machine phyboard-polis-imx8mm-4 can be used: https://download.phytec.de/Software/Linux/BSP-Yocto-i.MX8MM/BSP-Yocto-NXP-i.MX8MM-PD22.1.0/images/ampliphy-vendor-rauc/phyboard-polis-imx8mm-4/phytec-headless-bundle-phyboard-polis-imx8mm-4.raucb Makes sure to select a bundle from the ampliphy-rauc or ampliphy-vendor-rauc distribution.

Now the software module must be assigned to a new distribution. Again, click on the plus sign under Distributions on the distribution management page. Then drag and drop the software module to the newly created distribution:

This distribution now contains a full OS update bundle. Note, that you can assign multiple software modules to one distribution. This may come in handy when you want to split the base operating system from your user application, and only the user application frequently changes.

Deploying RAUC Bundles from hawkBit to the Device

To issue an update drag and drop the previously created distribution onto the target on the Deployment Management page. Select Forced when assigning the distribution to the target.

After the next polling message is sent, the target device will start downloading the distribution containing the RAUC bundle and install it. To see this process in action, view the logs of rauc-hawkbit-updater:

target$ journalctl --no-pager -fu rauc-hawkbit-updater

This will output the download and install process:

Feb 09 10:21:39 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Checking for new software...
Feb 09 10:21:40 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: New software ready for download. (Name: nano-os, Version: 1, Size: 105127416, URL: http://192.168.3.10:8080/DEFAULT/controller/v1/nano-1/softwaremodules/1/artifacts/phytec-headless-bundle-phyboard-polis-imx8mn-1.raucb)
Feb 09 10:21:40 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Start downloading: http://192.168.3.10:8080/DEFAULT/controller/v1/nano-1/softwaremodules/1/artifacts/phytec-headless-bundle-phyboard-polis-imx8mn-1.raucb
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Download complete. 64.72 MB/s
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: File checksum OK.
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb : installing
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :   0% Installing
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :   0% Determining slot states
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  20% Determining slot states done.
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  20% Checking bundle
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  20% Verifying signature
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  40% Verifying signature done.
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  40% Checking bundle done.
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  40% Checking manifest contents
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  60% Checking manifest contents done.
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  60% Determining target install group
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  80% Determining target install group done.
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  80% Updating slots
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  80% Checking slot rootfs.1
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  83% Checking slot rootfs.1 done.
Feb 09 10:21:41 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  83% Copying image to rootfs.1
Feb 09 10:22:12 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  86% Copying image to rootfs.1 done.
Feb 09 10:22:12 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  86% Checking slot boot.1
Feb 09 10:22:12 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  90% Checking slot boot.1 done.
Feb 09 10:22:12 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  90% Copying image to boot.1
Feb 09 10:22:16 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  93% Copying image to boot.1 done.
Feb 09 10:22:16 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  93% Checking slot bootloader.0
Feb 09 10:22:16 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  96% Checking slot bootloader.0 done.
Feb 09 10:22:16 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb :  96% Copying image to bootloader.0
Feb 09 10:22:20 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb : 100% Copying image to bootloader.0 done.
Feb 09 10:22:20 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb : 100% Updating slots done.
Feb 09 10:22:20 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb : 100% Installing done.
Feb 09 10:22:20 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Installing: /tmp/bundle.raucb : idle
Feb 09 10:22:20 phyboard-polis-imx8mn-1 rauc-hawkbit-updater[353]: Software bundle installed successful. 

After a successful bundle installation, the action should also be visible in the Action history on the Deployment Management page with the current status.

RAUC should show the other slot being marked as active for the next boot with an "x":

target$ rauc status
=== System Info ===
Compatible:  phyboard-polis-imx8mn-1
Variant:
Booted from: rootfs.0 (system0)

=== Bootloader ===
Activated: rootfs.1 (system1)

=== Slot States ===
  [bootloader.0] (/dev/mmcblk2, boot-emmc, inactive)

x [rootfs.1] (/dev/mmcblk2p6, ext4, inactive)
        bootname: system1
        boot status: good
    [boot.1] (/dev/mmcblk2p2, vfat, inactive)

o [rootfs.0] (/dev/mmcblk2p5, ext4, booted)
        bootname: system0
        mounted: /
        boot status: good
    [boot.0] (/dev/mmcblk2p1, vfat, active)

Reboot the target device manually in order to use the new distribution:

target$ reboot

Congratulations! You successfully set up and deployed a software update using hawkBit and RAUC. For subsequent updates, simply upload a new RAUC bundle to the hawkBit server, as described in Uploading RAUC Bundles to the hawkBit Server, deploy it to the device and issue a reboot.