Bridging the Gap: The RAUC hawkBit Client

Enrico Jörns | | RAUC

OTA field updates are a common requirement in modern embedded device deployments. The larger the amount of devices to control, the more important is having a good infrastructure that is reliable in updating and smart in rolling out the software.

With the RAUC update framework, we already have one of the components required for solving this challenge: an update client operating on your target and making sure that your updates are installed safely and securely.

The second component is a deployment server that manages your update artifacts, controls roll-out strategies, gives feedback about device update states, etc.

This is where the Eclipse hawkBit project comes into play. While RAUC focuses on being not much more than the update core, hawkBit focuses on being a deployment server only. This qualifies it as an ideal counterpart for RAUC.

Thus, the only question remaining is: How should we bring them together?

Evolution of rauc-hawkbit

In the middle of 2016, in the context of a customer project where unattended OTA field updates with hawkBit as the deployment infrastructure were required, Pengutronix started implementing a python-based service that runs on the target and talks to RAUC on the one side via its D-Bus interface and to hawkBit on the other side over its RESTful DDI API.

Later that year, parts of the code were reused in an internal project, a RAUC hawkBit deployment server demonstrator. We presented this at the FOSDEM in Brussels, at the Chemnitz Linux days and on the Embedded World exhibition.

Finally, in early 2017, the customer and we decided to make a reusable project out of the hawkBit client core components and provide it as open source software. The advantages that were the motivation behind doing this step are quite the same as for almost every open source project: Only this way it will have the chance to be actively maintained, used, tested and possibly improved by the community.

A few month later, after a bunch of refactoring, cleanup and testing, we now finally release the initial version (0.1.0) of this project.

See How It Works

Now, let's conclude the history lesson and start with some technical facts.

The rauc-hawkbit client uses asynchronous routines and HTTP communication abstraction provided by asyncio and aiohttp for its communication with the REST API of the hawkBit deployment server.

The communication with the D-Bus interface of RAUC is done using the corresponding glib methods from Python via the GObject introspection interface.

During its initial interaction with the server, the client identifies itself to the server and sends some meta-data that allows identification, filtering, etc. Then the client service regularly polls the deployment server for new artifacts or actions. The polling interval itself is a property set by the hawkBit server and can be adjusted to specific needs. Once hawkBit has an update available for the device, the client first downloads it and then triggers RAUC via D-Bus to install the downloaded bundle.

During installation, the client receives progress feedback from RAUC and forwards it to hawkBit, allowing the user to see the exact individual progress of each pending update. After a successful or failed update, hawkBit gets notified about the result, allowing to base roll-out strategies on this information.

Using it


Download v0.1.0 release of rauc-hawkbit or vist on GitHub or pypi

rauc-hawkbit is available in the python package index (pypi) making it easy to install for testing purposes.

For those who use Yocto/OpenEmbedded as build system, the meta-rauc layer provides a rauc-hawkbit recipe and all required dependencies. You can simply add it to your image:

IMAGE_INSTALL_append = " rauc-hawkbit"

or build it directly with bitbake:

bitbake rauc-hawkbit

The rauc-hawkbit client is designed to be both an example application as well as a base library providing the required functionality for bringing RAUC and hawkBit together. For testing, you can simply use the provided executable python script rauc-hawkbit-client. If you consider actually using it in the field, you may want to integrate it into your application, web interface or something else. In that case, you can use it as a python module via import rauc_hawkbit.

To use the example command-line application, all you need is a configuration file containing some mandatory information, such as the server address, an authentication token or the name of your target:

hawkbit_server =
ssl = false
tenant_id = DEFAULT
target_name = test-target
auth_token = ahVahL1Il1shie2aj2poojeChee6ahShu
mac_address = ff:ff:ff:ff:ff:ff
bundle_download_location = /tmp/bundle.raucb
log_level = debug

To start the rauc-hawkbit client run:

rauc-hawkbit-client -c config.cfg

Note that for this example to be fully functional, you also need to have a RAUC instance running on your device and a hawkBit instance set up on your server. Refer to this page on how to quickly set up a development instance of hawkBit.

Further Readings

Showcase: Fail-Safe (OTA) Field Updating

Enrico Jörns | | didyouknow, rauc

Being able to robustly and securely update embedded systems and IoT devices in the field is a key requirement of every product today. The update framework RAUC is the basis for a modern and future-proof solution. In this showcase we present the basic principles of a fail-safe update system and how Pengutronix can support you with implement this for your platform.

RAUC v1.5 Released

Jan Lübbe, Enrico Jörns | | RAUC

This release fixes a vulnerability in RAUC that can be exploited under certain circumstances to achieve a local privilege escalation. It provides both a mitigation for the vulnerability when using the existing bundle format as well as a new bundle format that uses dm-verity to continuously authenticate the update data while it is installed.

RAUC v1.4 Released

Enrico Jörns | | RAUC

It's been 3 weeks ago now since the tag for RAUC 1.4 was created. But it is vacation time and so we have a good excuse for communicating things with some delay. Fortunately, the media team is back now and so also those of you who haven't noticed the new release yet will be informed about notable changes.