The device twin represents the current state of each device’s resource. Each connected device notifies the plgd hub about every change using the CoAP Gateway observations, which are started right after the device successfully connects and authenticates. All changes are persisted in form of an audit log in the EventStore, from which is the latest version returned to clients through the Resource Directory.
The device resources can be updated by more services/users at the same time. These resource change requests are called Pending Commands. As soon as the command is successfully processed on the device, the CoAP Gateway is informed about the change through our observation channel. More details in the following diagram.
The device might be actuated also from the local network. The temperature in the room changed, or a user updated a resource over device-to-device connectivity, for example using the plgd client. This change also triggers the notify on the device, what delivers to the CoAP Gateway, subscribed device observer, information about the change what updates the twin in the plgd hub. More details in the following diagram.
Device metadata contains additional information about the device lifecycle, including connection status and twin synchronization state. The twin synchronization state informs user about the reconciliation after the reconnect or twin creation after the first sign-in to the plgd hub. There are more states and various edge cases, so let’s go through diagrams to understand all the state transitions during the device lifecycle.
The synchronization as it is described in the following sequence diagram occurs only if the batch observe is supported by the device. By default, the plgd hub requires support for the batch observe. Devices which doesn’t support it are disconnected. If you’re interested how twin synchronization state transition works for devices without batch observe support, jump here.
All changes that occur on the connected device are observed and stored in the EventStore. There are few use cases when the Twin - active observation of all changes is not desired. For example, if the device is in the maintenance state and produces test data that shall not be part of the audit log. To do so, a client needs to send the request UpdateDeviceMetadataRequest with TwinEnabled and CorrelationId.
The Twin is disabled only after the DeviceMetadataUpdated event is received and contains the same correlation id as was used in the update request. This confirmation event is received only if the device is/comes online.
Same logic as for disable Twin applies. The Twin is enabled only after the DeviceMetadataUpdated event is received and contains the same correlation id as was used in the update request. This confirmation event is received only if the device is/comes online.
Force resynchronization refers to the process of refreshing all resources from the device and updating the twin. Its primary purpose is to resolve potential synchronization issues and ensure there are no operational discrepancies between the device and its twin. It also enable the device twin.
To trigger force resynchronization, the client must send the UpdateDeviceMetadataRequest with the TwinForceResynchronization parameter. It’s important to note that force resynchronization will only take place if the device is online or comes online.
To ensure that the resynchronization is successfully completed, the client should wait for the DeviceMetadataUpdated event, wherein the TwinSynchronization.State parameter is set to IN_SYNC. This indicates that the force resynchronization process has been successfully executed and the device and its twin are now in sync.
To stop force resynchronization send CancelDeviceMetadataUpdateRequest with correlationId used in UpdateDeviceMetadataRequest.
plgd makes it simpler to build a successful IoT initiative – to create a proof of concept, evaluate, optimize, and scale.
