Eclipse hawkBit™ - Update Server

Eclipse hawkBit is an domain independent back end solution for rolling out software updates to constrained edge devices as well as more powerful controllers and gateways connected to IP based networking infrastructure.

Build:

License:

Docker:

Documentation

see hawkBit Documentation

Contact us

• Having questions about hawkBit? Check Stack Overflow
• Want to chat with the team behind hawkBit?
• Having issues with hawkBit? Open a GitHub issue.
• You can also check out our Project Homepage for further contact options.

hawkBit evaluation

The following vendors offer free trial accounts for their hawkBit compatible products:

• Bosch IoT Rollouts
• Kynetics Update Factory

Device Integration (Client libraries)

hawkBit exposes HTTP/JSON based Direct Device Integration (API) API that allow any update client to integrate quite easily.

The Eclipse Hara subproject aims to provide a reference agent software implementation of the Eclipse hawkBit device API. The hara-ddiclient repository provides:

• a Kotlin library that facilitates and speeds up the development of DDI API clients running on the JVM
• a virtual-device application which provides:
  • a reference example on how to use the library
  • a configurable virtual device that can be used for different testing scenarios

The hara-ddiclient library has reached version 2.x, and has been successfully used in production for years.

Other open-source hawkBit Clients

There are clients outside of the Eclipse IoT eco system as well, e.g.:

• SWupdate which is a Linux Update agent with focus on a efficient and safe way to update embedded systems.
• rauc-hawkbit-updater which is a hawkBit client for the RAUC update framework written in C/glib.
• rauc-hawkbit which is a python-based hawkBit client demo application and library for the RAUC update framework.
• hawkbit-rs provides a couple of Rust crates to help implement and test hawkBit clients.
• Zephyr-RTOS: The Zephyr OS is a small-footprint kernel designed for use on resource-constrained and embedded systems: from simple embedded environmental sensors and LED wearables to sophisticated embedded controllers, smart watches, and IoT wireless applications.
• ChirpStack: ChirpStack Gateway OS uses SWUpdate for handling updates which can be integrated with Eclipse hawkBit. ChirpStack is an open-source LoRaWAN Network Server which can be used to to setup private or public LoRaWAN networks.

Runtime dependencies and support

Java Runtime Environment: 21

SQL database

(Optional) RabbitMQ: 3.6,3.7,3.8

Getting Started

We are providing a Spring Boot based reference Update Server including embedded H2 DB for test and evaluation purposes. Run with docker:

docker run -d -p 8080:8080 hawkbit/hawkbit-update-server

The monolith update server will start on port 8080 with default configuration and H2 database. The default user admin:admin is configured.

The Swagger UI is available at: http://localhost:8080/swagger-ui/index.html

See below for how to build and run the update server on your own. In addition we have a guide for setting up a complete landscape.

Note: this docker image supports both DDI and DMF APIs. However, in order to have DMF API working you shall have started additionally RabbitMQ on localhost:5672 with user guest/guest. Then the DMF will use / vhost. See more at guide -> Configure RabbitMQ connection settings.

hawkBit (Spring boot) starters

Next to the Update Server we are also providing a set of Spring Boot Starters to quick start your own Spring Boot based application.

Clone, build and run hawkBit

Clone and build

git clone https://github.com/eclipse-hawkbit/hawkbit.git
cd hawkbit
mvn clean install

Start hawkBit Update Server

java -jar ./hawkbit-monolith/hawkbit-update-server/target/hawkbit-update-server-0-SNAPSHOT.jar

The monolith update server will start on port 8080 with default configuration and H2 database. The default user admin:admin is configured.

The Swagger UI is available at: http://localhost:8080/swagger-ui/index.html

Start hawkBit UI

java -jar ./hawkbit-ui/target/hawkbit-ui.jar

Log in to hawkbit UI with default admin:admin user.

Start hawkBit Device Simulator

• Enable gateway token authentication - on update server set tenant configuration properties ( via Swagger UI or hawkBit UI):
  • authentication.gatewaytoken.enabled=true and
  • authentication.gatewaytoken.key=<gw_token>)
• Start demo Device Simulator - in the script below edit the environment properties accordingly.
  • DDI url http://localhost:8080 is default URL when running monolith update server.
  • Set hawkbit_tenant_gatewaytoken to the configured gateway token (authentication.gatewaytoken.key))
  • Then run:

export hawkbit_server_ddiurl=http://localhost:8080
export demo_controller_id=demo
export hawkbit_tenant_gatewaytoken=gw_token

java -jar ./hawkbit-sdk/hawkbit-sdk-demo/target/hawkbit-sdk-demo-0-SNAPSHOT.jar

• Execute start command in the simulator console to start the device simulation.
• Your device will be registered automatically on the update server and will start polling for updates.

Generate getting started data with the Management API example (optional)

java -jar ./hawkbit-example-mgmt-simulator/target/hawkbit-example-mgmt-simulator-#version#-exec.jar

Status and API stability

hawkBit is currently in '0.X' semantic version. That is due to the need that there is still content in hawkBit that is in need for refactoring. That includes the maven module structure, Spring Boot Properties, Spring Boot auto configuration as well as internal Java APIs (e.g. the repository API ).

However, the device facing DDI API is on major version 'v1' and will be kept stable.

Server facing and DMF API are Management API are on v1 as well. However, we cannot fully guarantee the same stability during hawkBit's 0.X development but we will try as best we can.