Fleet
Manage your product's devices in the field: see every unit, the firmware each one runs, and roll out updates — from the web, the CLI, or CI.
Fleet is per-project. The project holds the firmware releases; the fleet holds the devices running them. Devices check in on their own schedule to report what they're running and pick up whatever you've published for them, so a rollout is two commands: publish a release, point devices at it.
Enabling fleet on a project
Open the project and press Fleet (or type g f from anywhere in the
project), then Enable fleet. Enabling needs write access on the project's
fleet/ path — see Roles.
Enabling shows the project's data-plane key exactly once. You only need it if your own services accept uploads from these devices and want to verify their tokens — store it if that's you, and see Verifying device tokens.
The fleet page
The fleet page lists every device: serial, tags, hardware revision, the
firmware it reports, the firmware it should be running, and when it was
created. Press / to search — matching serials, tags, and notes.
The page is deliberately read-only. Provisioning and rollouts are tooling operations, done with the CLI below, and every fleet action shows up in the project's activity feed like everything else.
Provisioning a device
Create a device and get its token:
embedhub fleet mint myorg/myproject 100000000042 --hw 1.0 --tags site-pune,rack-2
The device token is printed exactly once — bake it into the device during manufacturing. If it's lost, revoke the device and mint a new one.
The token is the device's only credential: it authenticates check-ins, firmware downloads, and uploads to your own services. Tags and notes are yours to organize with — set them at mint time or later:
embedhub fleet meta myorg/myproject 100000000042 --tags site-pune,rack-5
embedhub fleet meta myorg/myproject 100000000042 --notes "Ask for Ramesh at the gate."
A device that's lost, stolen, or retired stops working on its next request:
embedhub fleet revoke myorg/myproject 100000000042
Publishing firmware
A fleet release is a firmware binary already in the project's releases/
folder, promoted with a version:
embedhub push firmware.bin myorg/myproject --path releases
embedhub fleet publish myorg/myproject releases/firmware.bin --version v0.3.0 --hw 1.0
Releases are immutable: publishing the same version again with identical
content does nothing, and publishing it with different content is refused —
cut a new version instead. A release can be pinned to a hardware revision
(--hw) or left to fit any hardware, and --min-fw marks the oldest
firmware allowed to take the update.
embedhub fleet releases myorg/myproject
Rolling out
Point a device at a version:
embedhub fleet set-target myorg/myproject 100000000042 v0.3.0
The device picks it up on its next check-in, downloads the release — downloads resume where they left off if the connection drops — verifies it, and reboots into it. The rollout is complete when the device reports the new version; the fleet page shows each device's running firmware next to its target until then.
To roll out to a group, target every device carrying all of the given tags — a dry run until you confirm:
embedhub fleet set-target myorg/myproject v0.3.0 --tags site-pune,rack-2
# Would set target v0.3.0 on 12 device(s) tagged site-pune+rack-2: ...
embedhub fleet set-target myorg/myproject v0.3.0 --tags site-pune,rack-2 --yes
Revoked devices are never part of a rollout. The same --tags filter works
on embedhub fleet devices to see a group before touching it.
Two properties worth knowing:
- Setting a target before publishing the release is safe. Nothing is offered to the device until a matching release exists.
- A lower version is a rollback, honored deliberately. Point the device back at the previous release and it downgrades the same way it upgrades.
A freshly provisioned device is never offered anything until you set its target — its first check-in adopts whatever firmware it arrived with.
Verifying device tokens from your own services
If your product uploads data to services you run, those services can verify that an upload really comes from one of your devices without keeping their own token list: they hold the project's data-plane key (shown once at enable) and ask EmbedHub whether a presented device token is valid, getting back the device's serial and project. A revoked device's uploads stop verifying too — one revocation severs everything.
Fleet CLI reference
| Command | Does |
|---|---|
embedhub fleet status <org>/<project> | Device and release counts |
embedhub fleet devices <org>/<project> | The device table (--json for scripts, --tags to filter) |
embedhub fleet mint <org>/<project> <serial> | Provision a device; prints its token once |
embedhub fleet meta <org>/<project> <serial> | Set tags and notes |
embedhub fleet revoke <org>/<project> <serial> | Revoke a device |
embedhub fleet publish <org>/<project> <path> | Promote a binary in releases/ to a release |
embedhub fleet releases <org>/<project> | List published releases |
embedhub fleet set-target <org>/<project> <serial> <version> | Roll a device to a version |
embedhub fleet set-target <org>/<project> <version> --tags <a,b> [--yes] | Roll out to every device carrying all the tags |