A unit is a box that hosts gateways, one per port: a Stellar Bench, with its CAN, serial and SpaceWire ports. The cell sees its units as a fleet: each with its serial number, its software and hardware revision, its health, and the gateways it hosts.
Registration#
A unit registers with the kind unit, its serial number as instance name, the software of
its agent and a unit section:
{
"kind": "unit",
"instance": "SB-00042",
"software": {"name": "stellar-bench-agent", "version": "1.2.0"},
"heartbeat_period_ms": 1000,
"public_key": "U…",
"unit": {
"hardware_revision": "K24-carrier-B",
"gateways": ["sb-00042-can0", "sb-00042-uart1", "sb-00042-spw0"]
}
}The reconciler refuses a unit without its unit section, an empty hardware revision, or a
gateway name that is not a token. The gateways register themselves, each with its own name; the
unit lists them, so the fleet ties each gateway to its box. Its heartbeats carry its health, like
any instance.
Once registered, a unit receives a JWT limited to its registration, its heartbeat and its control verbs: nothing of the telemetry or the telecommands of the targets, which go through its gateways.
The fleet#
GET /v1/units lists the units: serial number, software and version, hardware revision, alive
and health (with the reason of a degraded unit), last heard, and for each gateway whether it is
registered, its health and the links bound to it. The web console shows them under
Configure › Fleet.
Verbs#
| Request | Verb | Who | Effect |
|---|---|---|---|
POST /v1/units/{serial}/selftest | selftest | anyone | Runs the self-test of the unit; the reply is its report |
POST /v1/units/{serial}/update with {"image": <url>, "version": <semver>} | update | supervisor | Installs a signed image on the inactive slot (A/B) and switches to it at the next boot |
POST /v1/units/{serial}/reboot | reboot | supervisor | Reboots the unit |
The API calls the verb on stellar.ctl.rpc.unit.<serial>.<verb> and returns the reply of the
unit: 404 unit::unknown when no unit answers, 422 unit::refused with its reason when it
refuses (a bad signature, an image of another hardware…), 504 unit::timeout after 30 s,
403 unit::not-supervisor for an update or a reboot by someone else, 400 for another verb or
an update without its image and version.
The verification of the image, the A/B slots and the rollback belong to the agent of the unit.
Claiming a unit for a cell and its enrolment package come with stellar-admin later.