TCP connection which device established to the CoAP Gateway is now authenticated but not authorized. Before the devices becomes reachable, TCP connection needs to be authorized. As this flow describes operation of a new device, device needs within the first connection Sign Up - register with the plgd.cloud (see 8.1.4). The authorization code received during the OCF Cloud Provisioning process described in the diagram above is be by the CoAP Gateway exchanged for an access and refresh token and returned back to the device. This process is in more detail described in the OCF Cloud Security Specification (see 6.2).
Successful registration to the plgd.dev is followed by authorization request called Sign In. Sign In is required right after successfully established TCP connection to the CoAP Gateway, otherwise the device won’t be reachable - marked as online. Other device requests are blocked as well unless the device successfully Signs In. Successful autorization precedes validation of the JWT Access Token.
Device capabilities are represented in form of resources. Configuration if the resource is published (remotely accessible over plgd.cloud) or not is part of the IoTivity-Lite API. If the resource is publised or not is up to the device vendor which might want to have some resources accessible only on the proximity network. Resources information which are published to the plgd.cloud provides insights into device capabilities. Clients are interested not only in the resource href - location on which they can request resource representation, but mainly in the resource type as this allows them to filter only capabilities they are able to control.
As an example, if you have an client application which controls the light, it will search the Resource Directory for all lights user have at home - filter resources by resource type oic.r.switch.binary. Other resources like temperature, moisture, etc. are not of any interest, as application doesn’t understand their representation.
Information which is published doesn’t contain resource representation, only resource information as described here (see 18.104.22.168.2).
Resource publish request is forwarded to the Resource Aggregate which registers a new resource. This process makes the resource discoverable.
The plgd.cloud starts observation of every successfully published resource by sending the OBSERVE request. Each of the received notification from the device is send to the Resource Aggregate to record the change.
As the response to the resource observation request contains actual representation, CoAP Gateway doesn’t have to pull the data at all. Additional responses called notifications are by the device send whenever the representation of the device changes.
Resource Publish & Subscription
From this moment on, device is reachable to all authorized clients and devices. Resource update requests received by particular Gateway where the client is connected are forwarded to the Resource Aggregate. Successful command validation precede storing and publishing of this event to the Event Bus, to which is the CoAP Gateway subscribed. If the update request event targets the device hosted by this instance of the CoAP Gateway, UPDATE is forwarded over the authorized TCP channel to the device. Device response is forwarded to the Resource Aggregate which issues resource updated event updating the resource projection and informing client that the update was successful.
Delete a device
At some point, user might want to delete the device from the plgd Cloud. There are two possibilities how to achieve it.
Disconnect the device from the plgd Cloud using Onboarding Tool
Device is at this point requested to disconnect from the plgd Cloud from the local network, by the Onboarding tool. This process covers multiple steps:
Send the SignOff message which deregisters the device
Close the TCP connection
Cleanup of the cloud configuration resource
Force disconnect by the plgd Cloud
User might decide to delete the device directly using the plgd API. This approach is handy when it comes to stale devices, which cannot be anymore requested by the Onboarding Tool to disconnect and you want to cleanup your list of devices in the plgd Cloud.
Every transaction on the device’s resource is scoped to the single aggregate - Resource Aggregate. The RA builds it’s internal state, which is a projection of a single fine-grained event stream. When the aggregate receives a new command from any of the plgd gateway, the command is validated and after successful validation event describing the action is created and persisted in the EventStore. After successful write to the EventStore, event is published to the EventBus.
After every successful write to the EventStore, an event is published on the event bus. Other plgd services are subscribed to the event bus to be notified when the change in the system / on the devices occurs or is requested. One such party is a resource directory, which aggregates resource models in memory for fast retrieve requested by the plgd gateways. Gateways are subscribed as well to be able to synchronously process device’s resource updates.
plgd cloud uses NATS messaging system as it’s event bus.
We are using pure NATS, not NATS Streaming nor Jetstream.
plgd cloud persist events in an event store, which is a database of events. The store has an API for adding and retrieving device’s events. Events needs to be versioned and written in a correct order. To achieve the consistency, optimistic concurrency control method is applied during each write.
After the event is successfully written into the event store, it’s distributed to the event bus which notifies all subscribers about the change asynchronously.
The plgd cloud defines an EventStore interface what allows integration of different technologies to store the events. During the last 2 years the project evaluated multiple technologies for both EventStore and EventBus:
Device’s data are in the MongoDB organized per devices. For each connected device a new collection is created. Each event is modeled as a new document.
Details Query resources B of device d9dd7…
Get latest snapshot
a. Find document where _id == B.s
b. Get version of latest snapshot event
Find documents where aggregateID == B && version >= latestSnapshot.version
Details Query all resources of device d9dd7…
Get latest snapshots of all resources
a. Find documents where aggregateID == snapshot && version == -1
b. Get versions of latest snapshot events per each resource
Find all documents per each resourcewhere aggregateID == snapshot.aggregateID && version >= latestSnapshot.version