At a handful of devices, a spreadsheet may feel sufficient. At hundreds, operators need to answer: which physical unit is this, who owns it, what firmware should it run, what did it last report, and can it still be trusted? A device registry is not just a MAC-address list; it is the operational record linking identity, lifecycle, desired configuration and observed health.
Keep a stable logical ID independent of mutable network addresses. MAC address, IP and display name are attributes, not authorization credentials. Enrollment should bind a physical unit to an owner, site and hardware revision, while credential issuance happens through a controlled process. Never reuse a retired identity for a replacement board.
A normalized registry can store device identity, model/revision, installation location, owner, credential reference, support status and lifecycle status. Telemetry belongs in time-series or event storage; the registry should hold the latest summary needed to find and operate the device. Keep desired configuration separate from reported state, with version and update time on both. Their difference is useful drift information, not something to overwrite silently.
Useful fields include first enrollment, last authenticated contact, firmware and bootloader versions, configuration revision, sensor health, last error, update cohort and maintenance owner. Keep secrets outside ordinary inventory rows; store a reference to a secret manager or credential service instead.
Heartbeats should include device ID, monotonic sequence, firmware version, uptime or reset cause, and compact health flags. The server adds its own receipt time. Define expected reporting interval per device class and derive states such as healthy, late, stale, quarantined or retired. “Connected” does not prove a sensor is sampling or the configuration is current.
Use idempotent event keys and tolerate delayed reports. Clock drift means event time and receipt time should remain separate. A fleet view should filter by site, hardware revision, firmware cohort, stale duration and open incident rather than presenting thousands of cards.
Track desired firmware/configuration separately from what each device confirms. A rollout record should identify artifact version, signature or digest, cohort, authorization, start time, outcome and rollback status. ESP-IDF OTA rollback can return to a previous working application after a failed new image; registry state should distinguish “downloaded,” “booted pending verification” and “confirmed healthy.” A command to update is not proof the update succeeded.
| Registry field or event | Why it matters | Access boundary |
|---|---|---|
| Logical ID and hardware revision | Stable joins across network changes and repairs | Enrollment and support operators |
| Credential reference/status | Rotation, revocation and incident response | Never expose private key material in UI |
| Desired vs reported state | Detects configuration and firmware drift | Command changes require authorization |
| Last-seen and health | Finds stale or failing fleet segments | Filter by site and operational role |
| Lifecycle state | Controls activation, quarantine and retirement | Transitions are audited |
Separate read-only visibility, site operations, credential administration and firmware release approval. A support user may inspect health without retrieving secrets or issuing actuation commands. Scope every API query and command to authorized sites and device IDs. Log actor, reason, request ID and before/after state for sensitive transitions.
Quarantine a lost, compromised or returned device before reassigning it. Revoke credentials, stop command delivery, preserve needed security evidence and mark physical disposition. For a replacement unit, create a new identity and link it to the service ticket rather than copying the old identity. End-of-support devices need an explicit policy for updates, access and data retention.
A useful ESP32 registry connects a unique logical identity to lifecycle, access, desired configuration and observed health. Keep secrets out of inventory, separate desired from reported state, make OTA outcomes explicit and audit enrollment through retirement. That gives operators a fleet they can reason about, not a spreadsheet that merely counts devices.