RAUC

Introduction

RAUC is a lightweight update client that runs on your embedded device and reliably controls the procedure of updating your device with a new firmware revision.

RAUC is also the tool on your host system that lets you create, inspect and modify update files (”bundles”) for your device.

Please refer to RAUC documentation for a detailed documentation from RAUC.

Yocto Setup

Setup a complete Yocto build environment using the karo-minimal DISTRO for your module.

Until now, we only tested rauc with the QSMP* and TXMP* modules and i.MX8- and i.MX9 modules.

Note

QSMP, TXMP use Mainline Yocto BSP Guide

  1. Setup the Yocto build-directory as described in the Yocto guide for your machine.

  2. Add the following to conf/local.conf:

    DISTRO_FEATURES:append = " rauc"

  3. Compile the image.

    bitbake karo-image-minimal

    Note

    RAUC is only usable for karo-image-minimal or a custom image because the other images are to big to have two rootfs partitions with the same size.

  4. Program your module using uuu and reset it. You can also do your own partitioning of the module. Refer to Custom partitioning and system.conf. By default there are two redundant systems on the board for rauc.

  5. After reset run

    setenv boot_mode mmc_rauc
saveenv

    If the boot_mode is set to mmc, the boot script will not be used and rauc can’t switch between partitions.

  6. Boot your board. Basically, the rauc service is already running when you start Linux. It is essential to ensure that your rootfs is writable. If it is read-only, you can use the implemented rw-alias to make it writable.

    The command

    rauc status --detailed

    displays the detailed status of the update slots (A/B partitions), including boot information, installed versions, slot statuses, and boot attempts.

Host Setup

Prerequisites for host PC

  • build-essential

  • meson

  • libtool

  • libdbus-1-dev

  • libglib2.0-dev

  • libcurl3-dev

  • libssl-dev

sudo apt-get install build-essential meson libtool libdbus-1-dev libglib2.0-dev libcurl3-dev libssl-dev

Building rauc for host PC from sources

git clone https://github.com/rauc/rauc
cd rauc
meson setup build
meson compile -C build # or 'ninja -C build' on meson < 0.54.0

Install rauc on host PC

RAUC can be used directly from the build dir, or optionally be installed.

meson install

Using rauc

Start the rauc service on the module

The rauc service is started automatically at boot. You can check whether the service is running using the command:

ps aux | grep rauc

If the service is not running, you can start it manually:

rauc service &

Create a bundle on host PC

Create a directory with the content that should be installed. For example a new root filesystem.

mkdir content-dir/
cp <path-to-new-rootfs>/rootfs.ext4 content-dir/

Create a manifest describing which image to install where together with some meta info

cat >> content-dir/manifest.raucm << EOF
[update]
compatible=<your-board>    (e.g. txmp-1570)
version=2024-06-14

[bundle]
format=verity

[image.rootfs]
filename=rootfs.ext4
EOF

Let RAUC create a bundle from this

rauc --cert <path-to-cert>/cert.pem --key <path-to-key>/key.pem bundle content-dir/ update-2024-06-14.raucb

In your bsp in the meta-karo-distro layer you can find the key and the cert.

...meta-karo-distro/dynamic-layers/recipes-core/bundles/files/development-1.cert.pem
...meta-karo-distro/dynamic-layers/recipes-core/bundles/files/private/development-1.key.pem

Note

This key and cert is only a development key and cert. For productive usage, please create your own ones.

Install the bundle on the module

The created bundle (in the example update-2024-06-14.raucb) needs to be copied to the module to install it. To install the bundle run the following command on the modules linux commandline

rauc install <path-to-bundle>/update-2024-06-14.raucb

After cyptographically verifying the bundle, RAUC will now determine the active slots by looking at the rauc.slot variable. Then, it can select the target slot for the update image from the inactive slots.

When the update is installed completely, we just need to restart the system. U-Boot will then try to boot the newly installed rootfs. The updated slot will be automatically marked good if the boot process was successful.

Note

If the U-Boot boot script detects a slot change, it reboots the board in order to reload the device trees of the new bootfs partition.

HTTPS streaming of the bundle

Instaed of installing the bundle locally, you can also stream it via an internet connection. The bundles can be installed directly from a HTTP(S) server, without having to download and store the bundle locally. Simply use the bundle URL as the rauc install argument instead of a local file.

rauc install https://<Server - IP>/<Path to Subfolder on Webserver>your_update.raucb

Eclipse hawkBit™

Using Eclipse hawkBit™ as backend solution

Eclipse hawkBit™ is an open-source backend framework designed to manage software and firmware updates for network connected devices, particularly for over-the-air (OTA) rollouts. It allows developers to control update campaigns for large device fleets, supporting phased, secure, and automated deployments.

To utilise RAUC together with the Eclipse hawkBit™ backend framework you need to run a client software running on each device. It aims to provide a ready-to-use bridge between the hawkBit REST DDR API on one side and the RAUC D-Bus API on the other. The rauc-hawkbit-updater is a separate application project developed under the RAUC organization umbrella.

For detailed information visit the rauc-hawkbit-updater client project on GitHub: https://github.com/rauc/rauc-hawkbit-updater

To add the rauc-hawkbit-updater client to your image, add the following line to your conf/local.conf:

IMAGE_INSTALL:append = " rauc-hawkbit-updater"

A config-file must be provided to control the rauc-hawkbit-updater. An example can look like this:

[client]
hawkbit_server                = <Server-IP-Address>:8080
target_name                   = QSBASE93-0E51AA
auth_token                    = 26282ab6f9f279b800734a024194ab9c
#gateway_token                = chietha8eiD8Ujaxerifoxoh6Aed1koof
#ssl_key                      = pkcs11:token=mytoken;object=mykey
#ssl_cert                     = /path/to/certificate.pem
bundle_download_location      = /tmp/bundle.raucb
#tenant_id                    = DEFAULT
ssl                           = false
#ssl_verify                   = true
#ssl_engine                   = pkcs11
#connect_timeout              = 20
#timeout                      = 60
#retry_wait                   = 300
#low_speed_time               = 60
#low_speed_rate               = 100
#resume_downloads             = false
stream_bundle                 = true
post_update_reboot            = true
log_level                     = message
#send_download_authentication = true

[device]
product                   = KaRo-SOM
model                     = QS93-5210
serialnumber              = 00-0C-C6-0E-51-AA
hw_revision               = 2
baseboard                 = qsbase93
key2                      = value

Please note:

  • Add port 8080 to the server-IP address if the hawkBit™ application is installed in a Docker container.

  • The target_name must match the “Controller Id” name in hawkBit™’s Targets definition.

  • The auth_token key must match the appropriate key hawkBit™’s Targets definition.

  • Set stream_bundle = true, because there is not enough space on the device to store the bundle first.

  • post_update_reboot = true cause the updater client to reboot the device after installing the bundle. This will cause the new update to be booted.

  • all the keys, specified in the [device]-section are imported into the database as attributes for the corresponding target upon initial contact with the hawkBit™ server.

hawkBit™ base server setup

hawkBit™ can either be installed as a Docker image or the source code can be cloned and rebuild. For detailed informations of all the options please refer to the Quick Start section of the hawkBit™ documentation

For a monolith configuration and if you want to start also the hawkBit UI, you can use, for PostgreSQL:

git clone https://github.com/eclipse-hawkbit/hawkbit.git
cd hawkbit/docker/postgres
docker compose -f docker-compose-monolith-with-ui-postgres.yml up -d

Access hawkBit™ Management API via Swagger-UI

Swagger UI is an open-source tool that automatically generates interactive, browser-based documentation for APIs from an OpenAPI Specification. It allows developers to visualize, document, and test RESTful API endpoints directly in the browser without writing any backend code or implementation logic.

With the Swagger UI you are able to explore the whole Management API in detail. To enter the UI, please access the following page in your Internet browser:

http://localhost:8080/

Control Management API via hawkBit™-UI

The Eclipse hawkBit™ UI is a graphical user interface for the Eclipse hawkBit open-source backend, designed to manage software and firmware updates (OTA) for IoT and edge devices. It enables administrators to visualize device rollouts, manage software repositories, and monitor update progress.

Please note, not all of the Management API’s functionality is available there. The Swegger UI is significantly more powerful in terms of its range of features.

To enter the hawkBit™-UI, please access the following page in your Internet browser:

http://localhost:8088/

Custom partitioning and system.conf

For creating a custom partitioning and configure rauc to your needs, you should create your own yocto-layer according to “Create Custom Layer" in the Yocto Guide.

The implemented rauc configuration is just an example, you will need to tailor the partitioning and system.conf according to your needs.

We decided to setup a redundant system with the following structure:

├── bootfs
│   └── bootfsB
├── rootfs
│   └── rootfsB
└── userfs
    └── userfsB

If you want to change this, you can edit the uuu.auto script in your deploy directory.

After changing the partitioning, you should copy the system.conf from <your-bsp>/layers/meta-karo-distro/dynamic-layers/recipes-core/rauc/files/ to your own layer: <your-bsp>/layers/meta-mydistro/dynamic-layers/recipes-core/rauc/files/ and chenge it there according to your needs.

For more informations, please refer to RAUC partitioning