Device Lifecycle: Logical vs Physical¶

The platform separates a logical device — an id, a name, a config, an organization — from the physical hardware that currently serves it. This split is what makes prepare-ahead, hardware replacement and cloning possible without reflashing anything.

A device's config, history and identity belong to the logical device. The box in the rack is an implementation detail that can be swapped.

The states¶

Status	Meaning
`prepared`	A logical device with no token and no hardware. Its config can be built ahead of time.
`holding`	A freshly-enrolled physical unit that has phoned home but belongs to no organization yet.
`assigned`	A device belonging to a customer organization.

The claim primitive¶

Everything below is built on one operation: ClaimGateway.

Fold a freshly-enrolled holding-zone unit into an existing device. Moves the unit's identity token + hardware onto the target and retires the placeholder; the box adopts the target on its next reconnect, no reflash.

The physical unit never learns it was reassigned at flash time. It enrolls normally, lands in the holding zone, and is then folded into whichever logical device should own it. On its next reconnect it is that device.

graph LR
  F[Flash + enroll] --> H[holding-zone unit]
  P[CreateDevice] --> PR[prepared device<br/>config staged]
  H -->|ClaimGateway| PR
  PR --> A[assigned device<br/>config applies on claim]

The four operations¶

CreateDevice — stage before hardware exists¶

Stage a logical device before its hardware exists. Creates a prepared device (id, name, optional org) with no token or hardware, so its config can be built ahead of time; a holding-zone unit is folded in later via ClaimGateway.

This is the prepare-ahead flow: build the customer's whole config in the office, ship the box, claim it on arrival. The staged config applies automatically when the claim happens.

CloneDevice — seed from an existing device¶

Create a new prepared device seeded with a copy of an existing device's current config (as a draft). Same as create-ahead plus the config copy; the clone gets its own id, identity, and hardware later.

For rolling out the twentieth branch office that looks like the previous nineteen. The copy lands as a draft, so it is edited before it is ever applied.

Hardware replacement¶

A failed box is replaced by claiming a new holding-zone unit into the existing logical device. The device keeps its id, config, history and organization; only the hardware underneath changes. The swap is recorded as a Hardware replaced device event.

Reenroll — move between environments¶

Move a connected gateway to another environment. Pushes a reenroll command carrying the target nexus/realtime URLs and a one-time enrollment token minted in that environment; the agent enrolls there and only then drops its current identity.

The ordering matters: the agent acquires its new identity before discarding the old one, so a failed reenroll leaves a device that is still reachable rather than a brick.

Assignment¶

AssignGateway sets org_id and status='assigned', and also moves an already-assigned device between organizations. UnassignGateway clears org_id and returns the device to the holding zone (status='holding').

Flashing is deliberately separate from ownership — which is why a newly-enrolled device waits in the holding zone instead of guessing whose it is.

Governance¶

Identity and lifecycle changes are not config versions, so they are recorded separately and merged into the same history feed:

Governance audit trail: identity/lifecycle changes (hostname, display name, model, org assignment, hardware replacement) that are not config versions.

See ListDeviceEvents and the user-facing History page.