Device Management¶
1. Introduction¶
TCUP Device Management (DM) service makes it easy to connect wide range of devices and gateways to the cloud and allows remotely monitor and manage them. Device management provides a scalable, bidirectional device, network efficient communication capability between devices and applications. It enables remote monitoring of devices and sensors, querying device status and values of device specific resources, and allows applications to send commands or instructions to devices. An end user application can access the device or its resources through API invocation.
A device being managed by TCUP Device Management service runs a special software called Device Management agent. Each device needs to be registered with the server. Once the device is registered and the agent is run, users will be able monitor and operate the devices using TCUP Device Management portal or API calls.
TCUP Device Management (DM) is offered in two flavors based on underlying protocol of implementation –
OMA Lightweight (LWM2M ) based DM
TCP based DM
Feature wise both DM service are almost similar with API compatibility mostly. However, there are some inevitable changes like DTLS and TLS due to underlying protocol change.
1.1 Intended Audience¶
The intended audience of this document is anyone who wants to have an overview of TCUP Device Management Service. After going through this document, the user will understand the capability of TCUP Device Management Service in IoT platform.
2. Key Concepts for LWM2M Based DM¶
Following are some key concepts of the TCUP LWM2M Device Management Service:
2.1 Device Management Agent¶
This is a specially created software executable that runs on the device and implements the Light Weight Machine to Machine (LWM2M) device management protocol. The agents define and maintains data related to the device including data related to sensors and actuators connected to the device in form of resource and objects. An end user application can use APIs to access these resources to for various device management operations.
2.2 Resource and Object¶
Each property or parameter of a device is modelled as a resource as explained above. Similar set of resources may be clubbed under a LWM2M object. The objects and resources are structured in form a hierarchical resource tree. As an example, in an on-board vehicle computer, the vehicle location data (latitude, longitude, altitude) as recorded by the sensor attached to the on-board computer can be modelled as an LWM2M resource object.
2.3 Constrained Application Protocol (CoAP)¶
This is the network transport protocol used within the LWM2M device management protocol. It allows query and update of resource and object data.
2.4 Pre-registration¶
Preregister is the prerequisite to registration. In this step a user performs creates entries in the device database for pre-authorized devices. This needs to be completed before actual device registration. Device ID (or EPN) is provided by the user through the DM portal user interface or API call. The DM agent needs to provide a valid device ID for registration to complete.
2.5 Registration/ Re-registration and De-registration¶
A device registration process is needed for commissioning a new device into the system. The agent initiates the registration process. Once this is done the DM server is notified about the new device’s ID, IP, its resources and access privileges. TCUP supports device-initiated registration only. Reregistration is the process of renewal of registration information with the server. Deregistration is the process for deletion of devices.
2.6 Request and Response¶
Users can execute read or write operations device resources via DM API, the request is served by the request handler of CoAP resource in device agent.
2.7 Observe and Notify¶
The process offers a pub-sub alternate to request-response paradigm. The ‘observe’ is initiated by the user via DM Service to opt in and opt out for automatic notifications from dynamic observable resources. The users do not need to poll the device every time, they get automatic notification from device to DM server either periodically or on satisfying a condition such as a value change of a sensor resource or crossing a threshold.
2.8 Datagram Transport Layer Security (DTLS) Key Generation¶
The CoAP network protocol can be secured using DTLS. A unique DTLS key has to be generated against each preregistered device and pre-shared with the device for the DTLS security protocol to work.
2.9 Command to Device¶
This process facilitates dispatching and executing commands from DM server to device. Developer needs to write callback function to implement actual operation triggered by command.
3. Key Concepts for TCP Based DM¶
Following are some key concepts of the TCP based TCUP Device Management Service:
3.1 Device Management Agent¶
This is a specially created software executable that runs on the device and implements the TCP based device management client. The agent communicates over TCP socket with the DM server. The agent defines and maintains data related to the device including data related to sensors and actuators connected to the device in form of resource. An end user application can use APIs to access these resources to for various device management operations. The device agent is a TCP socket client which connects to TCP DM server. Device agent periodically sends heartbeat packets to the DM server that denotes device connectivity status. The DM server sends the pending instructions (like resource query, resource update, resourced subscription) to the agent against the heartbeat.
3.2 Resource¶
Each device parameter of any type (static, dynamic, editable, sensor) is modelled as a resource. The resources are serialized in binary serialization protocol called Protobuf.
3.3 Request and Response¶
This is the network transport protocol used within the LWM2M device management protocol. It allows query and update of resource and object data.
3.4 Pre-registration¶
Preregister is the prerequisite to registration. In this step a user performs creates entries in the device database for pre-authorized devices. This needs to be completed before actual device registration. Device ID (or EPN) is provided by the user through the DM portal user interface or API call. The DM agent needs to provide a valid device ID for registration to complete.
3.5 Registration/ Re-registration and De-registration¶
A device registration process is needed for commissioning a new device into the system. The agent initiates the registration process. Once this is done the DM server is notified about the new device’s ID, IP, its resources and access privileges. TCUP supports device-initiated registration only. Reregistration is the process of renewal of registration information with the server. Deregistration is the process for deletion of devices.
3.6 Transport Layer Security (TLS) Authentication¶
The TCP protocol can be secured using TLS / SSL based authentication. The TLS / SSL keys are created and shared by certificate service which are then manually provisioned on the devices.
4. Functional Capabilities¶
The following are some of the major functional capabilities of Device Management Service:
Creating a catalog or list of managed devices and managing & monitoring of devices on this list
A rich query, search and filter interface to the device list is provided. Various options for sort and search is provided. Device can also be searched based on device name or group of device can be searched based on device type/ model/ group.
DM service allows user to retrieve all/ specific resources and their near real time values associated with a particular device. Data from remote connected devices can be retrieved and passed on to applications, browsers or real-time stream processing engines.
It is possible for applications to update the value associated with an editable (writable) resource. This can be used as a way to send commands or instructions to devices.
It is possible for applications to update the value associated with an editable (writable) resource. This can be used as a way to send commands or instructions to devices.
Allows an application to receive notifications from a resource either periodically or based on resource value crossing a set threshold value whenever the value changes. This is also known as resource subscription. Notification interval period or threshold setting can be customized in DM agent based on application requirement.
Allows an administrator to retrieve and update the DTLS channel security key for a device in case of DM LWM2M. For DM TCP the TLS keys need to be renewed through certificate management service and reprovisioned manually on device.
DM service allows a user to create a command and schedule it to be sent to at a later time. Command can also be queued for disconnected device so that it can be executed when it connects back with DM server.
Allows the administrator to block a registered device. Once blocked, a resource will not get refreshed, subscribed or updated. An unblock option is also provided.
4. Purpose/Usage¶
TCUP DM service fulfils one of the most important critical functional requirements of any IoT applications, i.e connecting IoT devices to backend/ cloud, data acquisition from devices and remote monitoring and management.
In particular, DM service enables two way communication between devices and applications i.e receiving/ querying data from devices and sending data and instructions to devices.
5. Examples¶
Consider an example of a temperature monitoring system. The temperature is measured by a wall mounted sensor mote. The sensor mote is connected to a gateway via the Zigbee. The gateway is connected to TCUP cloud backend via a wireless internet connection. The gateway runs a Linux OS. A DM agent software is running on the gateway. This agent connects to the DM Server instance running in the cloud.
There is a need to raise an alert when the temperature exceeds a threshold. An LED lamp connected to GPIO pin of the gateway needs to be lit when this happens. The application also makes use of TCUP Message Routing service and Action service rules to meet the requirements.
The application is modelled in TCUP as follows:
A customized DM agent is developed. The agent defines resources corresponding to the readings from temperature sensor and the LED lamp.
To read the temperature value, the applications needs to make a read request with the temperature resource name.
The LED lamp can be toggled by writing values ‘1’ or ‘0’ alternatively on the resource mapped to the LED lamp.
Temperature resource is subscribed and DM server gets periodic notification on updated temperature value.
DM server forwards the received temperature data to TCUP message queue. The Message Routing service picks up this data from the message queue.
A Message Routing rule process the temperature value and compares the value against a threshold specified in the rule. When the temperature exceeds the limit, a message is generated for the Action service rule to fire.
An Action rule is invoked every time it receives a message corresponding to the exceeded threshold rule. This rule executes a DM API call to update the resource value for toggling the LED lamp.
The DM agent running on gateway toggles the GPIO pin on the gateway when it receives the updated LED resource value via the API call.
6. Reference Documents¶
For more details about this service please refer to the following documents:
API Guide