Note
Use plgd Client Application for easy device discovery, ownership configuration and provisioning for the plgd hub!
The CoAP gateway acts as a CoAP Client, communicating with IoT devices, which serve as CoAP Servers following the OCF specification. As the component diagram describes, the responsibilities of the gateway are:
Before a device becomes operational and is able to interact with other devices, it needs to be appropriately onboarded. The first step in onboarding the device is to configure ownership (see 5.3.3) where the legitimate user who owns/purchases the device uses one of the Owner Transfer Methods (OTMs) within the Onboarding tool to establish ownership. Once ownership is established, the OBT provisions the device (see 5.3.4), after which the device can be provisioned for the plgd hub (see 8.1.2.3). After successful provisioning, the device should establish a TLS connection (see 7.2) using certificate based credentials.
Use plgd Client Application for easy device discovery, ownership configuration and provisioning for the plgd hub!
The TCP connection which the device established to the CoAP Gateway is now authenticated, but not authorized. In order for the device to be reachable, the TCP connection must be authorized. This flow describes the operation of a new device; within the first connection the device must Sign Up - register with the plgd hub (see 8.1.4). The authorization code received during the OCF Cloud Provisioning process described in the diagram above is exchanged by the CoAP Gateway for an access and refresh token and returned to the device. This process is described in more detail in the OCF Cloud Security Specification (see 6.2).
Successful registration to plgd.dev is followed by an authorization request called Sign In. Sign In is required right after a 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 authorization precedes validation of the JWT Access Token.
Only JWT access tokens are supported on the device.
Device capabilities are represented in the form of resources. Configuration in terms of whether the resource is published (remotely accessible over plgd hub) or not, is handled by the IoTivity-Lite API. Whether the resource is published is up to the device vendor, who might want to have some resources accessible only on the proximity network. Resource information which is published to the plgd hub 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 a client application which controls lighting, it will search the Resource Directory for all lights the user has at home – filtering resources by resource type oic.r.switch.binary. Other resources, with data like temperature, moisture, etc. are not of any interest, as the application doesn’t understand their representation.
Information which is published doesn’t contain resource representation, only resource information as described here (see 6.1.3.2.2).
{
"di":"e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"links":[
{
"anchor":"ocf://e61c3e6b-9c54-4b81-8ce5-f9039c1d04d9",
"href":"/myLightSwitch",
"rt":[
"oic.r.switch.binary"
],
"if":[
"oic.if.a",
"oic.if.baseline"
],
"p":{
"bm":3
},
"eps":[
{
"ep":"coaps://[fe80::b1d6]:1111",
"pri":2
},
{
"ep":"coaps://[fe80::b1d6]:1122"
}
]
}
],
"ttl":600476
}
A resource publish request is forwarded to the Resource Aggregate, which registers a new resource. This process makes the resource discoverable. The plgd hub starts observation of every successfully published resource by sending the OBSERVE request. Each of the received notifications from the device is sent to the Resource Aggregate to record the change.
As the response to the resource observation request contains actual representation, the CoAP Gateway doesn’t have to pull the data at all. Additional responses called notifications are sent by the device whenever the representation of the device changes.
If you want to know more about Device Twin and it’s state changes, please go to Device Twin section.
From this moment on, the device is reachable to all authorized clients and devices. Resource update requests received by a particular Gateway to which the client is connected are forwarded to the Resource Aggregate. Successful command validation precedes storing and publishing of this event to the Event Bus to which the CoAP Gateway is subscribed. If the update request event targets the device hosted by this instance of the CoAP Gateway, an UPDATE is forwarded over the authorized TCP channel to the device. The device response is forwarded to the Resource Aggregate, which issues a resource updated event, updating the resource projection and informing the client that the update was successful.
If you want to know more about Device Twin and it’s state changes, please go to Device Twin section.
A client requesting resource observation will immediately start to receive notifications without additional requests to the device over the CoAP Gateway. As the plgd hub is by default observing the resources of all connected devices, the Gateway responsible will just subscribe to the Event Bus and forward requested notifications. Handling of CRUDN operations is the same for every Gateway.
Reconnecting is a crucial operation in IoT devices, but it can also be an expensive one. The process consists of multiple steps, including establishing a TLS connection, refreshing the token, signing in, publishing resources, and synchronizing the device twin.
It’s worth noting that during the reconnect process, the device’s CPU may be heavily utilized.
The system’s retry mechanism works by trying to establish a connection at set time intervals. These intervals are 2, 4, 8, 16, 32, and 64 seconds. If all the attempts fail, the device restarts the process from the beginning. When a connection is successfully established, the retry mechanism is reset and the connection is maintained using the keep-alive mechanism.
The first step in the reconnect process is to establish a secure connection using Transport Layer Security (TLS). This ensures that all data transmitted between the device and the server is encrypted and protected from unauthorized access.
After the connection has been established, the device needs to refresh its token, which is similar to the sign-in operation. This is necessary to obtain a new access token that can be used to sign in to the device.
The device then needs to authorize itself by signing in. This process is necessary to ensure that only authorized devices are able to access the resources on the server.
More information about the Device Authorization can be found here.
If new resources have been added or the module has been restarted, the device needs to publish these resources to the server. This process is necessary to ensure that all devices have access to the most up-to-date information.
More information about the Publish Resources can be found here.
The final step in the reconnect process is to synchronize the device twin. This is necessary to ensure that the contents of the IPM resources on the device match the contents on the server. Currently, this process is always done, but it will be improved in the future through the use of etags.
More information about the Device Twin can be found here.
At some point, a user might want to delete a device from the plgd hub. There are two ways to achieve this.
Through Onboarding Tool, a device is requested to disconnect from the plgd hub and from the local network. There are three steps:
A user might decide to delete the device directly using the plgd API. This approach is handy for stale devices, which cannot any longer be requested to disconnect through the Onboarding Tool; thus enabling a clean up of the list of devices in the plgd hub.
Every transaction on the device’s resource is scoped to the single aggregate – the Resource Aggregate. The RA builds its 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 gateways, the command is validated and after successful validation an event describing the action is created and persisted in the EventStore. After successful write to the EventStore, the event is published to the EventBus.
To prevent conflicts during the write to EventStore, the Optimistic concurrency control method is used.
More detailed flows on which commands trigger which events can be found in the commands proto file.
WIP 8.1.2.2 OCF Cloud User Authorization of Mediator
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 a change in the system / on the devices occurs or is requested. One such party is the resource directory, which aggregates resource models in memory for fast retrieve on request by the plgd gateways. Gateways are subscribed also, to enable synchronous processing of devices’ resource updates.
The plgd hub uses the NATS messaging system as its event bus.
We use pure NATS, not NATS Streaming nor Jetstream.
The plgd hub persists each resource state mutation as a separate record called an event. This enables us to reconstruct past states, use events as a foundation to understand user behaviour, or even explore a tamper-proof audit log. The plgd hub adopts Event Sourcing and CQRS patterns to support flexibility, scalability and trackability of the system.
Accepted commands are represented as PendingChange events; resource state changes received from connected devices are represented as ResourceChanged events. All these events are persisted in the EventStore, with the possibility to define your own cleanup policies to remove old events in case they are no longer needed.
plgd makes it simpler to build a successful IoT initiative – to create a proof of concept, evaluate, optimize, and scale.
