Device shadow model¶
The device shadow is RG's canonical, vendor-neutral representation of a device. It captures the device's current settings, its reported state, the actions it supports, its firmware state, and its change history — under one schema, regardless of make, model, or firmware. Operators, RBAC, monitoring, and audit all interact with the shadow, not with each device's native quirks.
What the shadow represents¶
A device shadow is the single object everything in the platform reads and writes when it deals with a device. It holds five things: the current settings intended for the device, the reported state the device most recently confirmed, the supported actions the device exposes, the firmware state including installed version and update status, and the change history of what was modified, when, and by whom. Settings and reported state are kept distinct on purpose — the gap between "what we asked for" and "what the device confirms" is exactly what drift detection reads. Because the shadow is vendor-neutral, an operator works with the same conceptual object whether the underlying hardware is a controller, a gateway, or a camera.
Why one schema across unrelated hardware¶
A shared schema is what turns a pile of incompatible devices into a manageable fleet. When every device — across vendors, models, and firmware — presents the same shape of settings and state, operations that would otherwise require per-SKU code become uniform. Bulk change applies one intent across many devices because they share settings semantics. Drift detection compares intended settings against reported state the same way everywhere. Parity reporting flags devices whose configuration diverges from a fleet standard. Without a canonical schema, each of these would need bespoke logic per device type; with it, they are single operations over the shadow, and adding a new model means teaching one adapter to populate the shadow, not rebuilding the operation.
Settings, reported state, and drift¶
Drift is the observable difference between a shadow's intended settings and the reported state a device confirms. Because the two are stored separately, the platform can always answer whether a device is currently in its intended configuration, and if not, which fields diverge. This matters across a fleet: a bulk change can be issued once and then verified by watching reported state converge on the requested settings, device by device, without treating any single vendor specially. When a device is offline or slow to confirm, the shadow simply shows the intended settings not yet reflected in reported state — an honest, uniform signal rather than a vendor-specific error.
Constraints stated as facts¶
The shadow model is defined by plain constraints rather than a serialized schema. Every managed device has exactly one shadow, and that shadow is owned by the single cluster the device is homed to. Current settings and reported state are always represented as separate facets, so one can differ from the other. Firmware state is part of the shadow, not a side channel, so version and update status travel with the rest of the device's representation. Change history is append-only in the sense that each recorded change carries its actor and time — the shadow is the surface operators use, and its history is the operational record that pairs with the security audit trail.