Adapters¶
An adapter is the component behind the device shadow that speaks a specific vendor, model, and firmware's native API. It translates canonical settings into the device's native representation and back, so operators work with one uniform shadow while each device is driven in its own dialect. The right adapter is selected per device by vendor, model, and firmware, which is what keeps mixed-firmware fleets manageable.
What an adapter does¶
An adapter is a translator with a fixed job: convert between the canonical device-shadow representation and one device family's native API. When an operator changes a setting on the shadow, the adapter renders that intent in the device's own terms and applies it through the device's native interface; when the device reports state, the adapter maps it back into canonical form. The adapter is the only component that needs to understand a given device's specifics — everything above it deals only with the shadow. This is why supporting a new model is bounded work: it means writing or extending one adapter, not teaching the whole platform a new device.
Type normalization and validation¶
Native APIs express the same idea in incompatible ways — a value one device takes as an integer, another takes as an enumerated string or a scaled unit. An adapter performs type normalization, presenting each setting in one canonical type on the shadow and converting to the device's expected form on the way out. It also produces operator-readable validation: when a requested value is out of range or malformed for the target device, the adapter surfaces a clear, human-meaningful reason rather than passing a raw device error upward. The effect is that operators reason about settings once, in canonical terms, and get consistent validation feedback across hardware that would otherwise each fail differently.
Invalidation and conditional visibility¶
Real devices have settings that depend on other settings, and an adapter encodes those relationships. Invalidation captures that changing one setting can make another stale or meaningless — turning off a feature invalidates its sub-options — so the platform doesn't present or apply a value that no longer makes sense. Conditional visibility captures that some settings only apply in certain modes, so they appear only when relevant. Both are expressed by the adapter because they are inherently device-specific: the same logical dependency differs by model and firmware. Encoding them in the adapter keeps the shadow honest — it presents the settings that actually apply to a device in its current state, not a flat list that ignores the device's own rules.
Firmware handling¶
Adapters handle firmware with the same care as settings. An adapter manages firmware operations for its device family with integrity checks on the artifact before it is applied, and with rollback awareness so an upgrade that fails or misbehaves has a defined recovery path rather than leaving the device stranded. Because firmware state lives in the device shadow, an adapter keeps the installed version and update status current, so the fleet's firmware posture is visible uniformly. This lets firmware operations participate in the same fleet-wide reporting as configuration — which devices are on which version, which have pending updates — without per-vendor tooling.
Adapter selection per device¶
Adapters are chosen per device by vendor, model, and firmware, so a fleet containing several generations of the same product line stays fully managed. Two devices of the same model on different firmware can bind to different adapter behavior when their native APIs differ, which is what prevents a firmware upgrade from silently breaking management. This per-device selection is the mechanism behind mixed-vendor and mixed-firmware support: the shadow stays constant while the adapter varies underneath it, matched to exactly what each device actually speaks.