hawkBit compatibility

Qawk speaks Eclipse hawkBit 1.1.0. Not a subset, not a dialect: the same operations, the same JSON, the same status and error codes, the same query language, paging and download headers. This page says exactly what that claim covers, how it is kept true, and where it is deliberately broken.

What is implemented

API	Path	Operations
Direct Device Integration	`/{tenant}/controller/v1`	All 16.
Management	`/rest/v1`	All 153.

That includes targets with their attributes, metadata, tags, types, groups, auto-confirmation, actions and action history; software modules and artifacts; distribution sets and their types; rollouts with groups, thresholds and the approval flow; target filters with auto-assignment; and tenant configuration.

Good to know

The authoritative list is the server's own. Qawk serves hawkBit's OpenAPI document where hawkBit serves it, filtered to the operations it really implements — so a generated client cannot be built against something that is not there:

curl -s 'https://qawk.example.com/v3/api-docs/swagger-config'
curl -s 'https://qawk.example.com/v3/api-docs/Management%20API' > management.json

Ask the server you are actually talking to. It is the one document that cannot be out of date.

How it is kept true

A claim of compatibility is worth what tests it. Qawk's is a contract test: a flow recorded from a real hawkBit 1.1.0 is replayed against Qawk and every answer is compared field by field, against samples the real server gave. The deliberate deviations below are the test's explicit allow-list, each with its reason in the code — so a difference is either listed or a failure, and there is no third state where it quietly drifts.

python3 server/test/contract.py http://localhost:8080

Where Qawk differs, on purpose

Five differences. Each was a real problem before it was a decision.

1. A new rollout answers `ready`, not `creating`

hawkBit creates the groups in the background and answers creating. Qawk creates them in the same transaction and answers ready. A client written for hawkBit polls until ready — and gets it immediately. Nothing breaks; there is just nothing to wait for.

2. A deleted module's name and version can be used again

hawkBit soft-deletes and reserves the name for ever. That reservation is why a demo has to be torn down to start over. Qawk frees the name; the deleted rows are still kept, for the history that points at them.

3. Range requests do not each write a history entry

hawkBit writes a download entry into the action's history for every range request. A delta update reads one file in hundreds of ranges, which buries the history and pushes past status-entry limits. Qawk records only the start of a download — no Range, or one starting at 0.

4. The Management API's 401 carries no `WWW-Authenticate`

The console calls the API with fetch(), and that header makes browsers throw their own login dialog over the page. Removing it is the difference between a console that can show you a sign-in form and one that cannot.

5. A success outside a maintenance window does not finish the action

The one that actually changes behaviour, and the one to know about.

SWUpdate answers a deployment it is told to skip with closed/success and "Skipped Update." — that is what real devices send. hawkBit takes it at its word and marks the device updated when it is not, which makes maintenance windows unusable with SWUpdate.

Qawk, outside an action's maintenance window, reads that success as the skip being acknowledged: the action goes to scheduled, stays open, and the installed set does not change. When the window opens, the device is told forced and installs.

Note

Inside a window — and for every action with no window at all — the behaviour is hawkBit's exactly. The difference applies only where hawkBit's behaviour would record something untrue.

What is not there

Multi-tenancy. One tenant per server. QAWK_TENANT names the single tenant devices use in their URL. hawkBit's tenant isolation is not implemented.
hawkBit's own UI. Qawk has its own console, which also works against a stock hawkBit.
DMF / AMQP. The device-management federation interface is not implemented. Devices speak DDI over HTTP.
Object storage for artifacts. They live on a filesystem.

Migrating from hawkBit

Stand Qawk up beside it. Same network, its own database. Nothing is shared.
Point the console at it. The Qawk console works against both — run it against your hawkBit first, then against Qawk, and compare the same screens.
Move the catalogue. Module types, distribution set types, modules, artifacts and sets, through the Management API. The same script reads one and writes the other, because it is the same API on both ends.
Move a few devices. Change the url in their swupdate.cfg. Nothing else on the device changes. With a gateway token they register themselves on the first poll.
Set up what hawkBit did not have. Channels with rules so devices land where they belong, centres if your fleet has sites, system types if you have machines that must move together.
Move the rest. Then turn hawkBit off.

Careful

History does not come across. Actions, rollouts and their status entries stay in hawkBit. If you need them, keep the old server readable for as long as your retention requires. Qawk starts with the devices' current state, not their past.

Running the console against hawkBit

The console asks /qawk/v1/info first. Against a stock hawkBit that endpoint does not exist, so it shows the hawkBit part — targets, sets, modules, deployments, rollouts, filters, tags — and hides channels, centres, the orchestrator, users and the audit log. A bar warns when an endpoint it calls is missing.

python3 console/serve.py --port 8090 --hawkbit http://hawkbit:8080

Trademark

hawkBit is a trademark of the Eclipse Foundation. Qawk is not affiliated with, endorsed by or a product of the Eclipse Foundation. It is an independent implementation of the published protocols.