Eclipse hawkBit (OTA)

Technical Preview

Overview

One client-mode connector, EclipseHawkbit, for the Eclipse hawkBit Management API. hawkBit is an open-source server for rolling out software and firmware updates to devices. Each device is a target (identified by its controller id), each piece of firmware or software is a software module, modules are bundled into a distribution set, and a rollout deploys a set to a filtered group of targets in stages. Use the connector to drive updates from the broker: register a device when it first appears on the UNS, push a firmware set to one machine, watch the action until it finishes, or start a staged rollout to a whole line and pause it if the error rate climbs.

Event	Request	Notes
ListTargets	`GET /targets?{query}`	`query` = pre-encoded `q` (FIQL), `offset`, `limit`, `sort`
GetTarget	`GET /targets/{controller_id}`
CreateTargets	`POST /targets`	JSON array of targets; returns `201`
UpdateTarget	`PUT /targets/{controller_id}`	Returns `200` with the updated target
DeleteTarget	`DELETE /targets/{controller_id}`	Returns `204`
GetTargetAttributes	`GET /targets/{controller_id}/attributes`	Attributes the device reported; `204` when none yet
CreateTargetMetadata	`POST /targets/{controller_id}/metadata`	JSON array of `{key, value}`; returns `201`
GetAssignedDistributionSet	`GET /targets/{controller_id}/assignedDS`
GetInstalledDistributionSet	`GET /targets/{controller_id}/installedDS`	`204` until the device reports a finished install
AssignDistributionSet	`POST /targets/{controller_id}/assignedDS`	`[{"id": <set>, "type": "forced"}]`; returns `200` with the action ids
ListTargetActions	`GET /targets/{controller_id}/actions?{query}`	Deployment history of one device
GetTargetAction	`GET /targets/{controller_id}/actions/{action_id}`
CancelTargetAction	`DELETE /targets/{controller_id}/actions/{action_id}`	Returns `204`; `405` when the action can no longer be cancelled
ListActions	`GET /actions?{query}`	All actions, filterable with FIQL
ListSoftwareModules	`GET /softwaremodules?{query}`
CreateSoftwareModules	`POST /softwaremodules`	JSON array; `type` is a module type key such as `os` or `application`
ListDistributionSets	`GET /distributionsets?{query}`
GetDistributionSet	`GET /distributionsets/{distribution_set_id}`
CreateDistributionSets	`POST /distributionsets`	JSON array; `type` is a set type key such as `os` or `os_app`
AssignSoftwareModules	`POST /distributionsets/{distribution_set_id}/assignedSM`	`[{"id": <module>}]`; returns `204`
GetDistributionSetStatistics	`GET /distributionsets/{distribution_set_id}/statistics`	Action and rollout counts by status
ListRollouts	`GET /rollouts?{query}`
GetRollout	`GET /rollouts/{rollout_id}`
CreateRollout	`POST /rollouts`	Target filter, groups, success / error conditions; returns `201`
StartRollout	`POST /rollouts/{rollout_id}/start`	Returns `204` once the rollout is `ready`
PauseRollout	`POST /rollouts/{rollout_id}/pause`	Returns `204`
ResumeRollout	`POST /rollouts/{rollout_id}/resume`	Returns `204`
ListRolloutGroups	`GET /rollouts/{rollout_id}/deploygroups?{query}`	Deployment groups and their status

Every request is relative to /rest/v1. Replies arrive on <topic>/response.

Authentication

hawkBit is self-hosted or run by a vendor. Every event sends Authorization: {authorization}, so pass the whole header value:

"Basic <base64(user:password)>" for a hawkBit user. The stock server ships with admin / admin on tenant DEFAULT; change it before the server is reachable from anywhere else.
"Bearer <token>" when hawkBit is configured for OAuth 2.0 or OpenID Connect.

Keep it in a broker secret (suggested HAWKBIT_AUTHORIZATION) and map it in with GET SECRET. Wrong credentials return 401; a user without the right permission gets 403.

Basic Syntax

Set BASE_ADDRESS to your hawkBit server, with no trailing slash. For a local server that is http://localhost:8080, with USE_SSL "false".

DEFINE ROUTE EclipseHawkbit WITH TYPE REST_API
    ADD REST_API_CONFIG
        WITH BASE_ADDRESS "https://YOUR_HAWKBIT_HOST"
        WITH ENABLE_CLIENT "true"
        WITH USE_SSL "true"
        WITH REQUEST_TIMEOUT '30'
        WITH DEFAULT_CONTENT_TYPE "application/json"
        # Smoke: ListTargets / GetTarget (GET), CreateTargets, CreateDistributionSets, AssignDistributionSet (POST), UpdateTarget (PUT), CreateRollout + StartRollout, cleanup DELETE.
    ADD EVENT ListTargets
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetTarget
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateTargets
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/targets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT UpdateTarget
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target/update"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target/update/response"
        WITH METHOD "PUT"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT DeleteTarget
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target/delete"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target/delete/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetTargetAttributes
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-attributes/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-attributes/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/attributes"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateTargetMetadata
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-metadata/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-metadata/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/metadata"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetAssignedDistributionSet
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-assigned-ds/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-assigned-ds/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/assignedDS"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetInstalledDistributionSet
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-installed-ds/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-installed-ds/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/installedDS"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT AssignDistributionSet
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-assigned-ds/assign"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-assigned-ds/assign/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/assignedDS"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListTargetActions
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-action/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-action/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/actions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetTargetAction
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-action/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-action/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/actions/{value.json.action_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CancelTargetAction
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/target-action/cancel"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/target-action/cancel/response"
        WITH METHOD "DELETE"
        WITH ENDPOINT "/rest/v1/targets/{value.json.controller_id}/actions/{value.json.action_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListActions
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/action/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/action/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/actions?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListSoftwareModules
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/software-module/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/software-module/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/softwaremodules?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateSoftwareModules
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/software-module/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/software-module/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/softwaremodules"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT ListDistributionSets
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/distributionsets?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetDistributionSet
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/distributionsets/{value.json.distribution_set_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateDistributionSets
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/distributionsets"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT AssignSoftwareModules
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set-modules/assign"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set-modules/assign/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/distributionsets/{value.json.distribution_set_id}/assignedSM"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT GetDistributionSetStatistics
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set-statistics/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/distribution-set-statistics/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/distributionsets/{value.json.distribution_set_id}/statistics"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT ListRollouts
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/rollouts?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT GetRollout
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/get"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/get/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/rollouts/{value.json.rollout_id}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
    ADD EVENT CreateRollout
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/create"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/create/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/rollouts"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Content-Type" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY "{value.json.body}"
    ADD EVENT StartRollout
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/start"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/start/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/rollouts/{value.json.rollout_id}/start"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT PauseRollout
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/pause"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/pause/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/rollouts/{value.json.rollout_id}/pause"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT ResumeRollout
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout/resume"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout/resume/response"
        WITH METHOD "POST"
        WITH ENDPOINT "/rest/v1/rollouts/{value.json.rollout_id}/resume"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"
        WITH BODY ""
    ADD EVENT ListRolloutGroups
        WITH SOURCE_TOPIC "cloud-iot/eclipse-hawkbit/rollout-group/list"
        WITH DESTINATION_TOPIC "cloud-iot/eclipse-hawkbit/rollout-group/list/response"
        WITH METHOD "GET"
        WITH ENDPOINT "/rest/v1/rollouts/{value.json.rollout_id}/deploygroups?{value.json.query}"
        WITH HEADERS
            ADD "Accept" "application/json"
            ADD "Authorization" "{value.json.authorization}"

MQTT examples

Request bodies go under body, so control fields like authorization and controller_id are not sent to hawkBit. List events always need a query field; send "" when you have no filter. Register a device: publish to cloud-iot/eclipse-hawkbit/target/create:

{
  "authorization": "Basic <base64 user:password>",
  "body": [{"controllerId": "press-07", "name": "Press 07", "description": "porto/line1/press07"}]
}

hawkBit returns 201 with the new target, or 409 if the controller id already exists. Push firmware to one machine: publish to cloud-iot/eclipse-hawkbit/target-assigned-ds/assign:

{
  "authorization": "Basic <base64 user:password>",
  "controller_id": "press-07",
  "body": [{"id": 12, "type": "forced"}]
}

The reply has assigned, alreadyAssigned and assignedActions with the new action id. Use "type": "soft" to let the device choose when to install. Follow the update: publish {"authorization": "...", "controller_id": "press-07", "query": "limit=5&sort=id%3ADESC"} to cloud-iot/eclipse-hawkbit/target-action/list, or read one action on cloud-iot/eclipse-hawkbit/target-action/get with action_id. cloud-iot/eclipse-hawkbit/target-installed-ds/get returns 204 until the device reports a finished install. Find devices with failed updates: publish to cloud-iot/eclipse-hawkbit/target/list with a pre-encoded FIQL filter:

{
  "authorization": "Basic <base64 user:password>",
  "query": "q=updateStatus%3D%3Derror&limit=50"
}

Roll out to a whole line: create the rollout on cloud-iot/eclipse-hawkbit/rollout/create, wait until rollout/get shows "status": "ready", then publish {"authorization": "...", "rollout_id": 3} to cloud-iot/eclipse-hawkbit/rollout/start:

{
  "authorization": "Basic <base64 user:password>",
  "body": {
    "name": "fw-2.4-line-1",
    "distributionSetId": 12,
    "targetFilterQuery": "description==porto/line1/*",
    "amountGroups": 2,
    "successCondition": {"condition": "THRESHOLD", "expression": "80"},
    "successAction": {"action": "NEXTGROUP", "expression": ""},
    "errorCondition": {"condition": "THRESHOLD", "expression": "20"},
    "errorAction": {"action": "PAUSE", "expression": ""}
  }
}

rollout/pause and rollout/resume take the same rollout_id; rollout-group/list shows each group’s progress.

Helper actions

DEFINE ACTION HawkbitRegisterMachine
ON TOPIC "porto/line1/+/online" DO
    SET "auth" WITH GET SECRET "HAWKBIT_AUTHORIZATION"
    SET "machine" WITH TOPIC POSITION 3
    PUBLISH TOPIC "cloud-iot/eclipse-hawkbit/target/create" WITH { "authorization": {auth}, "body": [ { "controllerId": {machine}, "name": {machine}, "description": "porto/line1" } ] }

DEFINE ACTION HawkbitFailedUpdates
ON EVERY 15 MINUTES DO
    SET "auth" WITH GET SECRET "HAWKBIT_AUTHORIZATION"
    PUBLISH TOPIC "cloud-iot/eclipse-hawkbit/target/list" WITH { "authorization": {auth}, "query": "q=updateStatus%3D%3Derror&limit=50" }

A 409 on the create response just means the machine is already registered. Restrict who can publish to cloud-iot/eclipse-hawkbit/# with a rule: its payloads carry the credentials and can push firmware to devices.

Notes

Errors come back on the response topic: 400 for bad JSON or a bad FIQL filter, 401 for missing or wrong credentials, 403 for a missing permission, 404 for an unknown target, action, set or rollout, 405 when an action can no longer be cancelled, 409 for a duplicate id or a rollout in the wrong state, 423 when a distribution set is locked, and 429 when a quota is exceeded.
query must be URL-encoded. hawkBit filters use FIQL, for example controllerId==press* or updateStatus==error.
A distribution set is only deployable once it holds its required modules (AssignSoftwareModules). Uploading the firmware file itself is a multipart upload and is not covered by this template; do it in the hawkBit UI or with a script.
Devices talk to hawkBit over its separate Direct Device Integration (DDI) API or the Device Management Federation (DMF) API. This template covers the Management API only.
Rollouts are created asynchronously: start one only after GetRollout reports ready, or hawkBit answers 409.

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Coreflux Portal

Using AI with Coreflux

Product Updates

Overview

Authentication

Basic Syntax

MQTT examples

Helper actions

Notes

​Overview

​Authentication

​Basic Syntax

​MQTT examples

​Helper actions

​Notes

​Related

Overview

Authentication

Basic Syntax

MQTT examples

Helper actions

Notes

Related