APIs DMO API Features

This page describes the services provided by the Device Management Orchestration (DMO) API. The description here is organized according to the functionality available to developers from the API. It is not a detailed description of how the API works, but rather a functional view of what an IoT developer can do with the API.

Provision one or many devices asynchronously Copied!

Provision a list of devices in the T IoT Hub and in the underlying device communcation layer, enabling them to connect and send data using one of the supported protocols for device communication. This operation also enables the automatic synchronization of the device data in T IoT Hub, allowing direct and convenient device data access for applications. Device provisioning is triggered by creating a provisioning request container instace with the list of node devices to be provisioning.

Remove one or many devices asynchronously Copied!

Remove the devices from the T IoT Hub and the underlying device communication layer by requesting the deletion of their corresponding nodes. That triggers the deletion of all of its data, including related containers and content items. After that the devices are not able to connect to the T IoT Hub.

Automatic update of device management data Copied!

For supported protocols and registered devices, the T IoT Hub automatically recognizes selected device management information published by the device, including model, battery status, location and last communication time and keep the latest values in standarized resources called management objects under the device’s node. This depends on the capability of the device to send the data using standard objects known by the T IoT Hub.

Automatic creation of device data structure Copied!

For supported protocols and registered devices the T IoT Hub automatically creates an application entity to hold the device payload data and it creates under it a structure of containers according the device resource structure. That allows API clients to address and manipulate the data of individual device resources.

Automatic collection of device payload Copied!

For all supported protocols and registered devices, the T IoT Hub collects all new data provided by the device (payload including sensor readings and device management information) and make that available as content items in the respective resource container in DMO. These content items preserve the raw payload data as it was sent by the device and due to the hierarchical organization of the containers the data can be fine granular searched, retrieved or subscribed to by API clients. That means client applications can access the collected data over the API in either synchronous (with search and retrieve) or asynchronous way (with subscriptions and notifications).

Configuration of data collection parameters Copied!

This allows API clients to tailor the frequency with which registered devices in supported protocols publish new data individually per device objects or resource.

Send raw data to device Copied!

For supported protocols and registered devices, it is possible for API clients to send data to device by writing to containers representing the target resources.

Trigger execution of device resources Copied!

For supported protocols and registered devices, it is possible for API clients to send execute request to the device by writing to containers representing the target resources.

Retrieve any resource based on path Copied!

API clients can directly address device management data (nodes and management objects) or device payload data (application entities, containers and instances) using the name and path of the target resource.

Retrieve any resource based on ID Copied!

API clients can directly address device management data (nodes and management objects) or device application data (application entities, containers and instances) using the unique ID of the target resource.

Search multiple resources based on filter criteria Copied!

It is possible to retrieve resources based on different criteria like resource type, label, serial number, name and other individual attributes. Search can be limited to sub-set of the resources based on the hierarchical organization of the resource structure (tree-based). Search is applicable to all API resources, incuding device management data (nodes and management objects) as well as device payload data (application entities, containers and content instances).

Retrieve latest and oldest content item (payload) of container Copied!

API clients can directly address the latest or the oldest content item in a container. For registered devices of supported protocols, that allows direct retrieval of the latest message sent by a device for individual resources.

Subscribe to individual resources Copied!

Any resource addressable by the API can be subscribed to. API clients can create or manage their own subscriptions, which allows them to listen to events related to the subscribed resources. That provides client applications with an asynchronous mechanism to access the device data collected by T IoT Hub.

Receive notification on new resource instances Copied!

Based on subscriptions, API clients are notified when new resources are available. This could be used for receiving notificatons when new devices or application are registered, or new device payload is available.

Receive notifications on resource updates Copied!

API clients are notified when subscribed resources are changed.

Receive notification on resource deletion Copied!

API clients are notified when subscribed resources are deleted.

Create/update/delete nodes Copied!

Nodes are used to represent physical devices. They are used to trigger the registration of devices for supported protocols. Besides that, applications can create themselves generic nodes, not tight to any particula protocol, or they can update node attributes to add own labels.

Create/update/delete management objects Copied!

Management objects are used to represent different management aspects of a device like: device info, battery, credentials, network information. Some management object data is synchronized automatically for registered devices of supported protocols. In addition to that, API clients can use the API to direclty set management object data. This can be used to extend the device data or to manually override the synchronized data. In that case, the overriden data is not synchronized with the device.

Application self-registration Copied!

Client applications have to register themselves by DMO before they can use the API. That allows them to use the API, register devices, retrieve and modify their data. Besides they can create their own data containers. Applications in this case could be end-user applications or services that process device data for specific use cases or they could also be applications running on devices, which access directly DMO API over REST.

Application de-registration Copied!

Client applications can remove their registration and delete their own data.

Create/update/delete containers Copied!

Client applications can create their own containers, to maintain their own data inside the T IoT Hub, which can be shared with other applications. That opens the possibility for an ecosystem of applications to enrich device data and share capabilities with each other. It also enables device manufacturers or integrators to create adapters to connect devices of any other technology to the T IoT Hub.

Create and delete content instances Copied!

Client application can publish their data under containers. It allows applications to extend or enrich device, push data to devices or share it with each other. That also allows sending device data directly to T IoT Hub using the REST API, in case the application is running on devices and it is able to use REST over HTTP.