Qawk documentation

Qawk is an over-the-air update server for fleets of devices, and a web console for it. It speaks Eclipse hawkBit 1.1.0, so the devices and the tools you already have work with it unchanged — and it adds what running a real fleet needs.

Get started A server, a console and three hundred simulated devices, running in five minutes. Using the console For whoever ships the update. Every screen, every button, what to press and what it does. The orchestrator Devices that work together, updated as one, in the order you decide — and rolled back as one. Install it Docker, compose or Kubernetes; HTTPS, backups, and what to check before you call it production. API reference Every endpoint of all three APIs, with the call in curl, Python, JavaScript, Go and PowerShell.

What it is

An update server has one job: get the right software onto the right machines without breaking any of them. Qawk does that job the way a fleet actually works.

It is hawkBit, so nothing has to change. All 16 operations of the device API and all 153 of the management API, with hawkBit's JSON, status codes, error codes, query language, paging and download headers. A device running SWUpdate's suricatta is pointed at a different host and carries on. A script written against hawkBit keeps working. A contract test replays a flow recorded from a real hawkBit 1.1.0 and compares every answer field by field.

And then it is more than hawkBit. Releases move down a pipeline — dev → beta → prod — through a gate that will not open until enough devices have run the release for long enough, and, when you ask for it, until a second person approves. Devices are grouped by where they physically are. Machines that work together are updated together, in order, and put back together when one of them fails.

Good to know

Written for two readers. If you press buttons in the console and need the update to go out tonight, read Using the console and nothing else. If you are wiring Qawk into something, everything else is for you.

The four ideas

Almost everything in Qawk is one of these four things. If you understand them, the rest of the documentation is detail.

Idea	What it is	Where
Channel	A set of devices that should run the same release. Channels chain into a pipeline, and a release moves from one to the next only through a gate.	Channels
Centre	Where a device physically is. A centre goes in a channel, and every device in the centre follows it — you move a place, not a list of machines.	Centres
System	Devices that work together and must be updated as one: a lane computer and the terminals attached to it. Components go in a chosen order; if one fails, the whole system goes back.	Orchestrator
Release	What a channel runs. It carries a distribution set for the devices that stand alone, and — when the channel has systems — a manifest for those.	Channels

What a day looks like

A build lands. You upload it as a distribution set, or your CI does it through the same API a person would use.
It goes to dev. One channel, a handful of machines, no ceremony. The devices that stand alone get the set; the systems get the manifest, component by component.
The gate into beta opens by itself once enough of dev is running it, long enough, with few enough failures — and once the orchestrator has finished with dev's systems. Someone looks at the gate and presses promote.
Beta runs it for a week. If too many devices fail, the release halts on its own and waits for a person.
Prod needs a second pair of eyes. The release waits in the approval queue; someone who is not you approves it; it goes out in waves, centre by centre.
A centre opens next month. Its machines register, land in the right channel from what they report about themselves, and are brought up to what that channel runs — without anyone remembering to do it.

What it is not

Documentation that only lists strengths is an advertisement. So:

TLS is not built in. Put Qawk behind a reverse proxy that terminates it. See TLS and reverse proxies.
One tenant per server. hawkBit's multi-tenancy is not implemented; QAWK_TENANT names the single tenant devices use in their URL.
Artifacts live on a filesystem, not in object storage. On Kubernetes that means a ReadWriteMany volume.
It is young. It is tested hard — a recorded hawkBit contract, end-to-end suites, ten thousand simulated devices — but it has not been running in a hundred companies for ten years, and hawkBit has.

Where to go next

If you are…	Start here
Curious, with ten minutes	Get started — the demo runs itself
The person who ships updates	Using the console
Setting a server up	Installing the server
Putting Qawk on a device	Connecting devices
Writing a script or a CI job	API reference
Coming from hawkBit	hawkBit compatibility
Wondering about the licence	Licence and credits