1. What the shadow is for
Devices on a mobile network are online only in bursts. If an application writes configuration straight to the device, the write can be lost or applied out of order while the device sleeps. A device shadow keeps a JSON state document in the cloud and splits the configuration the application wants (desired) from the state the device actually reports (reported). The application talks only to the shadow. When the device comes online, the platform pushes the difference, so the race goes away by design. On the SimtoLink Device Management Platform the shadow is a first-class object, and it shares that state with config push and the rules engine.
2. How it works
Shadow document
JSON with metadata, desired, reported, and delta. Each update bumps the version and rejects a stale write.
How state converges
After the application PATCHes desired, the platform diffs it into a delta. When the device comes online it pulls the delta, applies it, and reports its state. The two sides converge over time.
Conflicts and rollback
A version vector catches concurrent writes and rejects the stale one. You can roll back to an earlier version. A highly sensitive parameter needs a second approval.
3. The sync, in short
4. What the platform provides
| Capability | What it does |
|---|---|
| Desired and reported stay apart | The application writes only the desired state. The device reports only what it actually is. The platform computes the difference and pushes it |
| Versioning and conflict detection | Each update bumps the version and rejects a stale write, so two people cannot overwrite each other |
| Offline command cache | While the device sleeps, commands wait in the shadow. After it comes online the difference is pushed, and a weak link can acknowledge in batches |
| RBAC | Write access to desired fields follows the role. A sensitive parameter can require a second approval or a two-person review |
| Visible diff and alerts | The console shows the live gap between desired and reported. A field that has not converged raises an alert |
5. Document shape and versions
A typical document has metadata (version and timestamp), desired, reported, and delta. Each update bumps the version and rejects a stale write, so two operators cannot overwrite each other. A large field, such as a full page of rules, can be split or stored as an object URL, so the shadow stays small.
6. The sync itself
When the application PATCHes desired, the platform diffs it against reported and builds a delta. The device pulls or subscribes to that delta when it is online, applies it, and reports its state. If some fields cannot take effect yet, the device should report why they are pending. The shadow keeps an unconverged mark and raises an alert. On a weak link, connection resilience lets the device acknowledge in batches.
7. How this relates to a digital twin
The shadow is for live synchronization. A digital twin can add simulation and a historical track on top of it. On some projects, SimtoLink customers use the shadow as the twin’s live layer and write batched aggregates into time-series storage. For cloud and edge working together, see cloud-edge digital shadow sync.
8. Permissions and audit
Who may change desired is an RBAC question. Support might change only display settings, while engineering can change the sampling interval. Every change is written to the audit log, and you can roll back to an earlier version. A sensitive parameter, such as an unlock command, can require a second approval or a two-person review.
9. What not to do
Do not use the shadow as a high-frequency message queue. High-frequency telemetry still belongs on the telemetry path. Do not store a secret in clear text in the shadow; store a reference token. Desired and reported should follow the same schema, or the delta fills up with noise.
10. Performance and quotas
Cap the document size and the update rate. A huge JSON makes the diff expensive and the storage bill worse. For a fleet-wide configuration change, use a configuration template and a batched job, rather than writing a giant desired document to a million devices at once.
11. Test and accept
In integration tests, include out-of-order reports, a field that fails partway, and a replay after the network drops, and check that the version and the pending mark behave as expected. The acceptance list covers rejected conflicting writes, rollback, and complete audit fields.
12. Summary
A device shadow lets what the cloud intends and what the site actually is converge, even on a weak network. The SimtoLink Device Management Platform offers a versioned shadow API, a visible diff, linked alerts, and quotas, so application teams write less of their own state machine. See also remote control and cloud-edge digital shadow sync. For a review of the shadow data model and a load-test plan, contact the SimtoLink solutions team.