> ## Documentation Index > Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt > Use this file to discover all available pages before exploring further. # Eclipse hawkBit (OTA) > Client-mode REST API connector for Eclipse hawkBit over-the-air updates: register and update devices, assign firmware to a device and follow its actions, create software modules and distribution sets, and create, start, pause and resume staged rollouts Technical Preview ## Overview One client-mode connector, **EclipseHawkbit**, for the [Eclipse hawkBit](https://eclipse.dev/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": , "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": }]`; 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 `/response`. ## Authentication hawkBit is self-hosted or run by a vendor. Every event sends `Authorization: {authorization}`, so pass the whole header value: * `"Basic "` 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 "` 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"`. ```lot theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}} 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`: ```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}} { "authorization": "Basic ", "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`: ```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}} { "authorization": "Basic ", "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](https://eclipse.dev/hawkbit/apis/mgmt_api/) filter: ```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}} { "authorization": "Basic ", "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`: ```json theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}} { "authorization": "Basic ", "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 Register new machines as they appear and check rollout progress on a timer: ```lot theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}} 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`. ## Related * [REST API Connectors](/latest/lot-language/routes/rest-api-routes) * [REST API app templates](/latest/lot-language/routes/rest-api-apps/index) * [Mender](/latest/lot-language/routes/rest-api-apps/mender) * [balena](/latest/lot-language/routes/rest-api-apps/balena) * [Eclipse Ditto](/latest/lot-language/routes/rest-api-apps/eclipse-ditto) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.