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:
- 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.
The following vendors offer free trial accounts for their hawkBit compatible products:
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.
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.
| Database | H2 | MySQL/MariaDB | PostgreSQL |
|---|---|---|---|
| DDLs maintained by project | ✅ | ✅ | ✅ |
| Test dependencies defined | ✅ | ✅ | ✅ |
| Docker image with driver provided | ✅ | :white_check_mark | ✅ |
| JDBC driver | H2 | MariaDB Connector/J | PostgreSQL JDBC Driver |
| Status | Test, Dev | Production grade | Test, Dev |
Required only for the DMF (AMQP) API. CI runs against rabbitmq:3-management-alpine.
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-serverThe 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.
Next to the Update Server we are also providing a set of Spring Boot Starters to quick start your own Spring Boot based application.
git clone https://github.com/eclipse-hawkbit/hawkbit.git
cd hawkbit
mvn clean installStart hawkBit Update Server
java -jar ./hawkbit-monolith/hawkbit-update-server/target/hawkbit-update-server-0-SNAPSHOT.jarThe 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.jarLog 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=trueandauthentication.gatewaytoken.key=<gw_token>)
- Start demo Device Simulator - in the script below edit the environment properties accordingly.
- DDI url
http://localhost:8080is default URL when running monolith update server. - Set
hawkbit_tenant_gatewaytokento the configured gateway token (authentication.gatewaytoken.key)) - Then run:
- DDI url
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
startcommand 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.
The former hawkbit-example-mgmt-simulator (in the archived
hawkbit-examples repository) is no longer maintained. Use the
hawkBit SDK instead - hawkbit-sdk-mgmt provides a Management API client and
hawkbit-sdk-demo contains device (DeviceApp), multi-device (MultiDeviceApp, with a
setup command for target authentication) and DMF (DmfApp) examples. See hawkBit SDK.
- Single module / single test (
-ambuilds required modules too):
mvn -pl hawkbit-repository/hawkbit-repository-jpa -am test -Dtest=ClassName -Dsurefire.failIfNoSpecifiedTests=false- Code format (Spotless with eclipse_codeformatter.xml, only files changed against
origin/master-ratchetFrom):mvn spotless:apply/mvn spotless:check - License headers:
mvn license:check -PcheckLicense - Tests use embedded H2 by default. To run against PostgreSQL:
mvn verify -Dspring.jpa.database=POSTGRESQL -Dspring.datasource.url=jdbc:postgresql://localhost:5432/hawkbit \
-Dspring.datasource.username=<user> -Dspring.datasource.password=<password>- AMQP (DMF) tests need RabbitMQ with management plugin on localhost (
5672,15672), userguest:guest. - JPA vendor is EclipseLink by default; build/test with Hibernate via
-Djpa.vendor=hibernate.
| Module | Content |
|---|---|
| hawkbit-core | Core shared classes (tenancy, security, utilities) |
| hawkbit-ql-jpa | Query language (RSQL) to JPA Specifications |
| hawkbit-artifact | Artifact storage |
| hawkbit-repository | Repository API and JPA implementation (EclipseLink / Hibernate, Flyway) |
| hawkbit-rest | Common REST API / core |
| hawkbit-mgmt | Management API, resources, starter, server |
| hawkbit-ddi | Direct Device Integration API, resources, security, starter, server |
| hawkbit-dmf | Device Management Federation API (AMQP), starter, server |
| hawkbit-mcp | MCP (Model Context Protocol) server and starter |
| hawkbit-autoconfigure | Spring Boot auto-configuration |
| hawkbit-monolith | Monolith starter and Update Server |
| hawkbit-ui | Vaadin based UI |
| hawkbit-sdk | SDK (device, DMF, Management API clients) and demo |
- Quick start, Base setup, Database setup
- Architecture, Data model, Clustering, Throttling
- Authentication, Authorization
- Management API, DDI API, DMF API
- hawkBit SDK, MCP server, UI
- Contributing
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 DMF API and 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.