.. |br| raw:: html

   <br/>

.. _rauc-guide-index:

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 :ref:`mainline-yocto-guide-index`


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

#. Add the following to ``conf/local.conf``:

   .. code-block:: text

      DISTRO_FEATURES:append = " rauc"

#. Compile the image.

   .. prompt::
      :prompts: $

      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.

#. Program your module using uuu and reset it.
   You can also do your own partitioning of the module. Refer to :ref:`partitioning`.
   By default there are two redundant systems on the board for rauc.

#. After reset run

   .. prompt::
      :prompts: U-Boot >

      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.

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

   .. prompt::
      :prompts: root@txmp-1570:~#

      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

   .. code-block:: text

      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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   .. code-block:: text

      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.

   .. code-block:: text

      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:



   .. prompt::
      :prompts: root@txmp-1570:~#

      ps aux | grep rauc




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



   .. prompt::
      :prompts: root@txmp-1570:~#

      rauc service &

Create a bundle on host PC
~~~~~~~~~~~~~~~~~~~~~~~~~~

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

   .. code-block:: text

      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

   .. code-block:: text

      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

   .. code-block:: text

      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.

   .. code-block:: text

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

   .. prompt::
      :prompts: root@txmp-1570:~#

      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. 



   .. _partitioning:

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
   ":ref:`create-custom-layer`\" in the :ref:`yocto-guide-index`\ .

   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:

   .. code-block:: text

     ├── 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`_


   .. _`RAUC documentation`: https://rauc.readthedocs.io/
   .. _`RAUC partitioning`: https://rauc.readthedocs.io/en/latest/integration.html#emmc