End-to-End Secure & Scalable IoT OTA Update System with HawkBit

November 11, 2025 min read
End-to-End Secure & Scalable IoT OTA Update System with HawkBit

Background

I successfully made an end-to-end secure Over-the-Air (OTA) software update system for remote devices, by using the open-source platform hawkBit.

The hawkBit server is ready for production. My upcoming development steps involve creating the updater service on the target device, the OTA Manager, and the custom build system for the OTA update packages. For testing the complete system, I’ve created also an additional target device simulator. This simulator is capable of simulating a fleet with a large number of devices and able to inject all kind of update errors, timeouts and other issues.

This was a highly rewarding solo project that I designed, implemented and tested from start to finish.

Introduction

This project implements a secure Over-the-Air (OTA) software update system for our devices using Hawkbit, a leading open-source platform.

Key Components:

  • Target Updater Service: A lightweight service running on the target device will periodically check for updates with the Hawkbit server. Upon finding a new version, it will securely download and install the update.
  • Hawkbit Management: A service to manage the update process. It will integrate with the customer’s client system for:
    • Generating targets into Hawkbit by using the data from the client system
    • Monitoring update progress and device health

Benefits:

  • Secure and reliable updates over the internet
  • Centralized management and control
  • Scalable solution for large device deployments
  • Integration with existing customer systems

This project ensures efficient and secure software updates, improving device functionality and security over time.

Eclipse Hawkbit in a nutshell

Eclipse hawkBit is a software update framework for IoT devices. It allows you to manage and deploy updates to edge devices, controllers, and gateways over the internet. It supports different protocols, roll-outs, and packages for your update needs. You can learn more about it on their official website or their GitHub repository.

To communicate with the target devices, the Hawkbit Direct Device Integration REST API is used.

System overview

Components

  • OTA packages: zip files containing the update files
  • Browser: for the configuration and setup of Hawkbit. Also used to upload OTA packages and monitor the update process
  • Hawkbit server: a Docker instance of Hawkbit
  • Distribution packages: a package can contain one or more OTA packages
  • Target device: device where the update will be installed and where an updater service will be running to communicate via the DDI REST API with Hawkbit
  • OTA Manager: customized service to connect a Customer Client System with the Hawkbit, via the Management REST API. This service can run anywhere and needs a connection to the Hawkbit server and the Customer Client System

Hawkbit Direct Device Integration REST API

The Hawkbit Direct Device Integration (DDI) REST API is a set of resources provided by the hawkBit update server. It is designed for communication with devices to retrieve software update tasks. Here are the key points:

  1. Controller Identification: In DDI, the target device is identified using a controllerId. The term “controller” refers to the actual service or client running on the device. This allows for multiple clients on the same target, handling different tasks like firmware updates and app management.
  2. State Machine Mapping: The DDI has a different state machine and status messages compared to the hawkBit update server. This ensures compatibility with existing devices. Future versions of DDI may alter this behavior.
  3. Feedback Messages: The DDI API enables the device to provide feedback messages to the server. These include status updates during execution, download progress, and completion results (e.g., SUCCESS or FAILURE).
  4. Artifact Download: The DDI can inform the server when it is downloading artifacts related to an action.

In short, the Hawkbit DDI REST API facilitates seamless communication between devices and the update server, allowing efficient software updates for constrained edge devices and more powerful controllers

The DDI REST API documentation can be found here: https://eclipse.dev/hawkbit/apis/ddi_api/

The Updater service

The updater service is responsible for the software updates on the target. The updates are provided by Hawkbit via distribution packages. These packages can contain updates for Docker containers, Python scripts, executables etc. The Updater service is written in Python3 and therefore platform independent. Python versions 3.6 to the latest version is supported and tested. The Updater service will run as a service in the background. Via Hawkbit it is also possible to update the Updater service itself.

OTA Manager

The OTA Manager is using the Hawkbit Management REST API to communicate with Hawkbit and the underlying targets which are connected to Hawkbit. An explanation of this API can be found in the next section The Hawkbit Management REST API. The OTA Manager can be used to interface with the customers client system. The communication can be made bi-directional:

  • Provide the customer client system with health/status data from the targets
  • Provide the Hawkbit server with data about which targets need to be connected, so it will not be necessary to create the targets manually in Hawkbit, which will save a lot of time.

With all data available, it is possible to generate the configuration files (ota.ini) for all connected targets, with targetId and corresponding token to access Hawkbit. This is not implemented at the moment. Generating config files is tailor-made per customer.

The Hawkbit Management REST API

The Hawkbit Management REST API is a powerful tool that allows you to manage and monitor software updates for devices. Here are the key points:

  1. Purpose: The Management API is a RESTful API designed for Create/Read/Update/Delete operations related to provisioning targets (devices) and repository content (software).
  2. Functionality:
  • Provisioning Targets: You can use the API to create, read, update, and delete information about devices (targets).
  • Software Repository: It also handles software-related operations, such as managing distribution sets (bundles of software artifacts) and their metadata.
  • Monitoring Updates: The API enables monitoring of software update operations via HTTP/HTTPS.
  1. Features:
  • Hypermedia Support: The API supports JSON payload with hypermedia, allowing navigation between related resources.
  • Filtering, Sorting, and Paging: You can filter, sort, and paginate results.
  • Access Control: It provides permission-based access control with standard and custom roles.
  • Authentication and Authorization: The API is protected and requires authentication and authorization based on the security concept.
  1. Versioning: HawkBit ensures backwards compatibility by maintaining consistent API interfaces across future releases. The current version is v1.

In summary, the Hawkbit Management REST API empowers efficient software management for both constrained edge devices and more powerful controllers.

The Management REST API documentation can be found here: https://eclipse.dev/hawkbit/apis/management_api/

The Target device simulator

The target device simulator is a simulator for simulating multiple target devices. Every target device runs in his own thread. It can be used to test the performance of a Hawkbit server. Remark: The real installing of a Docker container is not supported, because all the target device threads are running on the same machine. All non-Docker OTA packages with scripts and/or executables are supported.