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 for your module.

Until now, we only tested rauc with the QSMP* and TXMP* modules. More to come…

Note

QSMP, TXMP use Mainline Yocto BSP Guide

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

  2. Append DISTRO_FEATURES:append in your conf/local.conf with the features rauc and u-boot-fw-utils. This should look like the following

    DISTRO_FEATURES:append = " alternatives-symlinks-relative rauc u-boot-fw-utils"
    

    Adjust the system.conf compatible string for your board

    [system]
    compatible=txmp-1570
    bootloader=uboot
    data-directory=/data/
    

    The system.conf can be found under <your-bsp>/layers/meta-karo-distro/dynamic-layers/recipes-core/rauc/files/system.conf

  3. Compile the image.

bitbake karo-image-<distro>

Note

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.

  1. 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.

  2. 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.
  1. Boot your board. Run

rauc service &

in linux on the board to activate rauc.

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

Run the following command on the modules linux commandline

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

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

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 were successful.

Custom partitioning and system.conf

Because the implemented rauc configuration is just an example by us, you are able to change the partitioning and change the system.conf which is used by rauc.

We decided to setup a redundant system with 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 need to adapt the system.conf under <your-bsp>/layers/meta-karo-distro/dynamic-layers/recipes-core/rauc/files/ .

For more informations, please refer to RAUC partitioning