f4278c45ef
* Maintenance Window: Introduced dynamic update to polling time. (#245) Resolves #245 Added new configuration parameters and controller handling that can be used to enable reduction in polling time near to start of a maintenance window. - The device may only get to know of start of maintenance window when the device polls the server. If a window is available, server responds with maintenanceWindow as 'available' and the update as 'forced'. Hence, as the time for start of a maintenance window approaches, the device should poll the server more often in order to decrease the possibility of missing the maintenance window start time due to non-alignment of polling with the start time, or due to packet losses and other network issues. - Additional configuration parameter is introduced that will be used to specify the minimum number of times the controller should poll between current time and the start of maintenance window. Using this parameter, an "inverse exponential back-off" scheme for reducing the polling time is implemented. - Implemented inverse exponential back-off for polling. For example, considering default polling-time = 00:05:00, min-polling-time = 00:00:30, maintenance-window-poll-count = 3, we expect that controller should poll the server 3 times between current time and start of a maintenance window. Thus in following scenario controller will get to know of start of maintenance 3 secs after scheduled start. Whereas without this scheme, delay may be as much as 4 minutes. time until start: 00:21:00; polling time: 00:05:00 time until start: 00:16:00; polling time: 00:05:00 time until start: 00:11:00; polling time: 00:03:40 time until start: 00:07:20; polling time: 00:02:27 time until start: 00:04:53; polling time: 00:01:38 time until start: 00:02:10; polling time: 00:00:43 time until start: 00:01:27; polling time: 00:00:30 time until start: 00:00:57; polling time: 00:00:30 time until start: 00:00:27; polling time: 00:00:30 time until start: -00:00:03; polling time: 00:05:00 - Once a maintenance window starts, the polling time is reverted to default. Polling time is not changed near the end of a maintenance window. Signed-off-by: Christian Storm <christian.storm@siemens.com> Signed-off-by: Himanshu Kumar Singh <himanshu.singh@siemens.com> Signed-off-by: Raju HS <raju.hs@siemens.com> * Maintenance Window: Updated the DMF API. Added maintenance window handling for DMF API. Currently no timer or scheduler is used to send updates to devices when a maintenance window becomes available. The device can simulate a poll behaviour by sending a message on UPDATE_ACTION_STATUS topic. Depending on whether there is a maintenance window available or not, server should send DOWNLOAD_AND_INSTALL or DOWNLOAD_AND_SKIP. - Additional action status (DOWNLOADED) and event topic (DOWNLOAD_AND_SKIP) - Server sends DOWNLOAD_AND_SKIP or DOWNLOAD_AND_INSTALL based on maintenance window using ControllerManagement Signed-off-by: Christian Storm <christian.storm@siemens.com> Signed-off-by: Himanshu Kumar Singh <himanshu.singh@siemens.com> Signed-off-by: Raju HS <raju.hs@siemens.com> * Maintenance Window: Added tests for DDI and Management APIs. Added test cases for DDI and Management API to test for maintenance window related logic. - Tests for Management API for DistributionSet assignment with and without valid maintenance schedule specified. - Tests for lapsed maintenance schedule. - Additional test helper methods. Signed-off-by: Christian Storm <christian.storm@siemens.com> Signed-off-by: Himanshu Kumar Singh <himanshu.singh@siemens.com> Signed-off-by: Raju HS <raju.hs@siemens.com> * Maintenance Window: Added new fields, enums, APIs and helper classes. Extended the data model and Action API to support maintenance schedule. Also provided helper classes to parse cron expression and calculate maintenance window based on the schedule. - DOWNLOADED status added to Action interface for controller to record action status. - Extra fields and APIs are added to Action to set schedule, duration and time zone of maintenance window. - Maintenance schedule can be defined using: a cron expression (e.g. "0 30 10-13 ? * WED,FRI" for 30 minutes past the hour, between 10:00 AM and 01:59 PM, only on Wednesday and Friday), a duration (e.g. "00:30:00" for 30 minutes) and the time zone (e.g. "+02:00" for CET summer time or "+00:00" for UTC) relative to which maintenance window start time is calculated. - Extra APIs added to check if a maintenance schedule is defined or lapsed and if a maintenance window is available based on the schedule. - Added database fields to store the schedule, duration and timezone of maintenance window. - Added helper classes to parse and calculate the maintenance window schedule. - Added exception handling classes to handle invalid maintenance window schedule. Signed-off-by: Christian Storm <christian.storm@siemens.com> Signed-off-by: Himanshu Kumar Singh <himanshu.singh@siemens.com> Signed-off-by: Raju HS <raju.hs@siemens.com> * Maintenance Window: Extended JSON model for REST APIs. Extended the JSON model to support defining and communicating the maintenance window information using the REST APIs. - Additional JSON objects are defined to extend request and response bodies. - When requesting a distribution set assignment to a target, the maintenance schedule information can be specified. Example below specifies a maintenance schedule at 11:00 PM, only on Saturday, only in 2017, for 30 minutes. Maintenance window start time is then calculated relative to the time zone specified, in this case CET summer time. $ curl 'http://127.0.0.1:8080/rest/v1/targets/2/assignedDS' -i -X POST -H 'Content-Type: application/json;charset=UTF-8' -d '{ "forcetime" : "0", "id" : "1", "type" : "forced", "maintenanceWindow": { "schedule": "0 0 23 ? * SAT 2017", "duration": "00:30:00", "timezone": "+02:00" } }' - When device requests the action information it gets to know if there is a 'maintenance schedule' for this action or not based on presence of maintenanceWindow field in the response. The value of maintenanceWindow is either 'available' (i.e. the maintenance window is now available as per defined schedule and the update can progress) or 'unavailable' (implying that maintenance window is not available now and update should not be attempted). If there is no 'maintenance schedule' defined, the field is null or not present. $ curl 'http://127.0.0.1:8080/default/controller/v1/2/deploymentBase/1?c=411629670' -i -H 'Accept: application/hal+json' HTTP/1.1 200 OK Content-Type: application/hal+json;charset=UTF-8 Content-Length: 1665 { "id": "1", "deployment": { "download": "forced", "update": "forced", "chunks": [ { "part": "os", "version": "1", "name": "1", "artifacts" : [ { "filename" : "binary.tgz", "hashes" : { "sha1" : "8b71973e835cd0718827238b1cf89f0079e44dae", "md5" : "a90218782025c48e09ba0436cf30d029" }, "size" : 5, "_links" : { "download" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz" }, "md5sum" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz.MD5SUM" }, "download-http" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz" }, "md5sum-http" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz.MD5SUM" } } } ] } ], "maintenanceWindow": "available" } } Signed-off-by: Christian Storm <christian.storm@siemens.com> Signed-off-by: Himanshu Kumar Singh <himanshu.singh@siemens.com> Signed-off-by: Raju HS <raju.hs@siemens.com> * Maintenance Window: Added additional UI elements. Added additional UI elements to specify maintenance window schedule in hawkBit UI while assigning distribution set(s) to target(s). - Added UI control to hawkBit UI when distribution set assignment is confirmed. - Also added required theme updates and resource strings. Signed-off-by: Christian Storm <christian.storm@siemens.com> Signed-off-by: Himanshu Kumar Singh <himanshu.singh@siemens.com> Signed-off-by: Raju HS <raju.hs@siemens.com> * Maintenance Window: Modified DDI and Mgmt APIs for maintenance window. Modified controller management and deployment management to handle maintenance window schedule in Management API and DDI API. - Modified REST endpoints to accept and respond with maintenance window information. $ curl 'http://127.0.0.1:8080/rest/v1/targets/2/assignedDS' -i -X POST -H 'Content-Type: application/json;charset=UTF-8' -d '{ "forcetime" : "0", "id" : "1", "type" : "forced", "maintenanceWindow": { "schedule": "0 0 23 ? * SAT 2017", "duration": "00:30:00", "timezone": "+02:00" } }' - Check for availability of a maintenance window based on the schedule. - Device gets go-ahead to install by change in ETAG and 'update' status to 'forced' when it polls during an available maintenance window. $ curl 'http://127.0.0.1:8080/default/controller/v1/2/deploymentBase/1?c=411659461' -i -H 'Accept: application/hal+json' HTTP/1.1 200 OK Content-Type: application/hal+json;charset=UTF-8 Content-Length: 1665 { "id": "1", "deployment": { "download": "forced", "update": "forced", "chunks": [ { "part": "os", "version": "1", "name": "1", "artifacts" : [ { "filename" : "binary.tgz", "hashes" : { "sha1" : "8b71973e835cd0718827238b1cf89f0079e44dae", "md5" : "a90218782025c48e09ba0436cf30d029" }, "size" : 5, "_links" : { "download" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz" }, "md5sum" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz.MD5SUM" }, "download-http" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz" }, "md5sum-http" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz.MD5SUM" } } } ] } ], "maintenanceWindow": "available" } } - In case the current available maintenance window lapses, the device is again sent 'update' status as 'skip'. The device may choose then to abort the update and restart during next available window. $ curl 'http://127.0.0.1:8080/default/controller/v1/2/deploymentBase/1?c=411659455' -i -H 'Accept: application/hal+json' HTTP/1.1 200 OK Content-Type: application/hal+json;charset=UTF-8 Content-Length: 1665 { "id": "1", "deployment": { "download": "forced", "update": "skip", "chunks": [ { "part": "os", "version": "1", "name": "1", "artifacts" : [ { "filename" : "binary.tgz", "hashes" : { "sha1" : "8b71973e835cd0718827238b1cf89f0079e44dae", "md5" : "a90218782025c48e09ba0436cf30d029" }, "size" : 5, "_links" : { "download" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz" }, "md5sum" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz.MD5SUM" }, "download-http" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz" }, "md5sum-http" : { "href" : "http://127.0.0.1:8080/api/v1/default/download/controller/2/softwaremodules/8/filename/binary.tgz.MD5SUM" } } } ] } ], "maintenanceWindow": "unavailable" } } - In case the entire maintenance schedule lapses, before device is able to send the completed status, the action is canceled. $ curl 'http://127.0.0.1:8080/default/controller/v1/2' -i -H 'Accept: application/hal+json' HTTP/1.1 200 OK Content-Type: application/hal+json;charset=UTF-8 Content-Length: 340 { "config": { "polling": { "sleep": "00:05:00" } }, "_links": { "cancelAction": { "href": "http://127.0.0.1:8080/default/controller/v1/2/cancelAction/1" }, "configData": { "href": "http://127.0.0.1:8080/default/controller/v1/2/configData" } } } Signed-off-by: Christian Storm <christian.storm@siemens.com> Signed-off-by: Himanshu Kumar Singh <himanshu.singh@siemens.com> Signed-off-by: Raju HS <raju.hs@siemens.com>
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: 
Documentation
Contact us
- 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.
Examples and Extensions
Next to the hawkBit core hosted here the project maintains as well examples and extension repositories.
hawkBit sandbox
We offer a sandbox installation that is free for everyone to try out hawkBit. However, keep in mind that the sandbox database will be reset from time to time. It is also not possible to upload any artifacts into the sandbox. But you can use it to try out the Management UI, Management API and DDI API.
https://hawkbit.eu-gb.mybluemix.net/UI/
In addition the following vendors offer free trial accounts for their hawkBit compatible products:
Device Integration
hawkBit does not provide off the shelf clients for devices as part of the project. The long term goal is to provide an Eclipse hono integration which will provide connectivity through various IoT protocols and as a result allows a wide range of clients to connect to hawkBit. However, the hawkBit Direct Device Integration (API) API is HTTP/JSon based which should allow any update client to integrate quite easily.
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 which is a python-based hawkBit client application and library for the RAUC update framework.
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
Open the update server in your browser:
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.
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
Build and start hawkBit Update Server
$ git clone https://github.com/eclipse/hawkbit.git
$ cd hawkbit
$ mvn clean install
$ java -jar ./hawkbit-runtime/hawkbit-update-server/target/hawkbit-update-server-#version#.jar
Start hawkBit Device Simulator (optional)
$ git clone https://github.com/eclipse/hawkbit-examples.git
$ cd hawkbit-examples
$ mvn clean install
$ java -jar ./hawkbit-device-simulator/target/hawkbit-device-simulator-#version#.jar
Generate getting started data with the Management API example (optional)
$ java -jar ./hawkbit-example-mgmt-simulator/target/hawkbit-example-mgmt-simulator-#version#-exec.jar
Releases and Roadmap
- In the upcoming release 0.2:
- Rollout management for large scale update campaigns.
- Clustering capabilities for the update server.
- Upgrade of Spring Boot and Vaadin dependencies (Boot 1.4, Vaadin 7.7).
- Improvements on modularization and customizability based on Spring's auto-configuration mechanism.
- Provide Spring Boot Starters for custom apps based on hawkBit.
- Provide standard runtime by means of Spring Boot based hawkBit update server (and hopefully a docker image).
- And of course tons of usability improvements and bug fixes.
- Future releases
- Complete repository refactoring.
- Integrate with Eclipse hono as DMF provider.
- Flexible DMF messaging infrastructure (e.g. with Spring Cloud Stream).
- Migrate to Spring Framework 5, Spring Boot 2 and Vaadin 8
- Re-evaluate JPA as persistence provider (e.g. look into jOOQ)
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.