About this guide

This guide describes all the important concepts and functions of IOT Creators' Connected Device Platform (CDP) and explains the REST Application Programming Interface (API) that are exposed to developers.
For more information on the REST API, see the API Reference Guide.

CDP Overview

The IOT Creators' Connected Device Platform (CDP) is a platform for co-ordination of communication between applications and devices. It is based on horizontal platform architecture that allows for mix-and-match deployment of individual or all components to meet varying consumer demands and strategies across a wide array of use cases and verticals. CDP platform provides granular REST APIs that is used by northbound applications.

These APIs allows multiple applications to:
• access device data
• filter device data
• send data and commands to devices
• manage device lifecycle
• manage resources

CDP platform integrates with southbound devices and gateways which are protocol agnostic, that is,
several adaptations are possible by providing integration layer between devices and gateways.

Groups

Application provider belongs to a group and it is application provider's own space for devices.
Additionally, the application provider is free to create their sub-groups within their allocated group in a hierarchy. When a device is registered in CDP, the device is added into a group. Application provider can perform various operations as well as subscribe for events or resources on the devices within its group and subgroup.

Application enablement

Application enablement is done using the available APIs. When subscribed to lifecycle events,
applications are notified when devices register or unregister. There are two approaches to read a
resource data. They are to,
• send a read request for a resource
• subscribe to a resource
• get notifications when there is a change in the resource value
CDP supports the following features:
• Subscribe to lifecycle events for a particular group. The events can be registration, de-registration,
update, and expiration. All the devices can be monitored. The devices to be monitored can be
filtered with the following criteria:
– make
– model
– firmware version
– serial numbers
• Subscribe to data resource for a particular group. It is possible to filter based on different criteria.
• APIs that enable applications to:
– read the list of devices
– query data resources on those devices
– read and update existing subscription details

Process flow

Process flow defines the sequence of events that must be performed by the client application to
request or post data to the devices. This flow involves:
• Application registration
• Subscription
– Lifecycle events subscription
– Resource events subscription
• Endpoints
– Add gateway
– Add endpoint
– List endpoints for a gateway
– List all endpoints
– Get endpoint details
– Delete endpoint
• Resources
– Write resource
– Read resource
– Execute resource
– Delete resource

Figure 2: Process flow shows these processes in a hierarchical manner:

Registration

Using this flow, CDP client registers its call back information, including the callback URL on the CDP platform.

Following are the pre-requisites for an CDP client to register on the CDP platform:

• The user must be created on the CDP platform
• Using the same credentials, the CDP client must register on the CDP platform
• Call back URL
• Call back URL credentials

The CDP platform sends responses to the requests posted by application, and notifications for any lifecycle events or resource subscriptions through the call back URL.

During registration, the CDP platform automatically checks if the callback URL provided is valid, that is, it verifies if the CDP client is reachable at that address. This is to ensure that CDP platform sends notifications to the correct URL. In case, CDP client is not reachable, registration will fail with 400 error code.

Subscription

Subscription flow is used to enable CDP client to query device data, device status, and check for fault events generated by these devices. This includes lifecycle related events such as new device registration, deregistration, device data update, device lifecycle expiry, and so on.
Subscription is the process by which the CDP client application user can subscribe either for resource or lifecycle events after the registration process is completed on CDP platform. When the subscription request is posted on CDP platform, it responds with a subscription ID that CDP users can store in the database to track details of what they have subscribed for.

Subscription APIs exposed by CDP platform can be used to do the following functions:

• Create Subscription - This API is to used create a new subscription in CDP platform that can be
either for lifecycle events or for resource events. Filter criteria can be assigned based on either
device serial numbers or based on device manufacturer make, model, and firmware version.
If it is not possible to observe some or all resources of any device, CDP platform will not report the
data to callback URL. It will only validate the request based on JSON structure and accept it for
processing at a later stage. The response to this HTTP request will be success and subscription
ID will be returned.

• View Subscription - This API is used to list all the subscriptions, subscribed by an authenticated
user. This is a synchronous API call and the response is returned in the form of a list of subscriptions containing complete details which include subscription ID, serial numbers, manufacturer details, resource conditions, deletion policy, and events. Single subscription details
can also be retrieved by passing subscription ID in request URL.

• Delete Subscription - This API is used to delete all the subscriptions, subscribed by an authenticated user. A single subscription can be deleted by passing the subscription ID in request
URL.

• View, Delete, and Add Serial Numbers - This API is used to add, view, or delete serial numbers
from an existing subscription. CDP platform exposes APIs that allows the CDP client to add,
view, or delete a device or list devices that are subscribed for. These APIs are only applicable
for subscriptions having filter criteria defined as serial number, and are not valid for subscriptions
having a filter for manufacturer data.

Resource subscription

By using Resource subscription APIs, subscriptions can be created based on filter criteria that may be either serial numbers or manufacturer data. CDP Clients may require devices to notify the status or value of a resource under certain conditions. Conditional filtering can be applied based on a number of different criteria. For a defined resource, it is possible to indicate either or all the options from the below conditions while subscribing to the resources:
• The less than the value of the resource: The minimum period that the device must wait prior to reporting a value to the server.
• The greater than the value of the resource.
• The step value that the resource must change prior to reporting to the server.

The process flow for resource subscription is as follows:

1. The CDP client needs to register itself on the CDP platform with a valid callback URL information.
2. The CDP client submits the request to subscribe to the resource. This request may be for single or group of devices based on serial numbers or based on manufacturer data. Conditional filters will
   be included in the request to define conditions on which resource will be observed.
3. CDP platform observes the resources based on the given conditions and when it is met, notification is sent to callback URL indicating the change of resource value.
4. Provision for e-mail or SMS notifications can also be done.

Lifecycle events subscription

Using Lifecycle Events Subscription APIs, subscriptions can be created based on filter criteria that
may be either serial numbers or manufacturer data. Lifecycle events for a device include registration,
deregistration, update, and expiry.

• Registration: When a new device is attached to the gateway and is registered with CDP platform,
a notification is sent to callback URL if subscribed, so that CDP client application manages the
device and its resources.

• Deregistration: Whenever a device is detached from the gateway, a deregistration notification
is sent to applications if CDP client has subscribed for this event. Based on this notification,
applications can decide further actions for the device such as to stop observing resources on a
deregistered device.

• RegisterUpdate: An endpoint device which is already attached to gateway can send a
RegisterUpdate. The gateway will initiate a getConnectedDeviceDetails on the end-device
and obtains the latest resource values from the end-device. It can also push fault policies and data
policies if applicable and a notification is sent to callback URL if subscribed, so that CDP client
application can manage the device and its resources.

• Expiry: During registration of devices, lifetime of the device is sent to the gateway. Based on
the lifetime of the device, an expiration time is calculated. Gateway will remove devices from its
registry once the expiration time of end device is reached and a notification is sent to callback
URL if subscribed, so that CDP client application can manage the device and its resources.

1. The CDP client needs to register itself on the CDP platform with a valid callback URL information.
2. The CDP client submits the request to subscribe for lifecycle events, that is, registration, deregistration, update, and expiry. This request may be for a single device or a group of devices with
   known serial numbers or based on manufacturer data.
3. When a new device registers on CDP platform, it updates the device information (for example,manufacturer data and supported resources) in its database, and a callback notification of
   successful registration is sent to the application.
4. SMS or e-mail notification can also be sent to enterprise workforce system for new device
   registration.

Endpoints and resources

All the devices registered with CDP platform are referred to as Endpoints and information made
available by them is referred as to Resource.
CDP platform provides a set of APIs which can be used to:
• Add endpoint
• Delete endpoint
• Query endpoints and resources
• Delete endpoints and resources

Add endpoint

A registered application user having valid account on CDP can create a new endpoint device using
CDP’s application REST API so that new endpoint can register itself and/or start reporting data to CDP depending on the protocol supported by the endpoint. For creating an endpoint on a device, group name, device protocol name, and protocol specific parameters are mandatory as input to the API. Supported protocols are as follows:
• HTTP for devices supporting HTTP. (Including UDP and CoAp Custom adaptation layers)

For more information on API structure and example requests, see M2M API Reference Guide.

Delete endpoint

A registered application user having a valid account on CDP can delete an endpoint device using CDP's application REST API.

The serial Number of the endpoint needs to be passed in the API call to delete the endpoint from CDP. If the serial number is not passed, then the request is rejected with adequate error message.

Endpoint details

When an CDP client is registered on CDP platform, using the APIs it can access the Endpoints that
are registered in a group.

Figure 6: Getting Endpoint details shows the flow using which a user can
retrieve a list of serial number of the devices (endpoints) belonging to a particular group and complete
the information about an endpoint.

Figure 6: Getting Endpoint details

• List all the Endpoints: Using this API, client application can retrieve serial numbers of the devices in a group by chunks, that is, specifying the start and end offset. Using this API, you can retrieve the total number of devices in the group by specifying the start and end offset as 0.

• List Endpoints for a gateway: Using this API, a registered client application user can retrieve the serial numbers of the devices in a group that are connected to a particular gateway. Input parameters required are gateway serial number, start and end offset values, and group name for which device list needs to be retrieved. The number of devices connected to a gateway can be retrieved by specifying the start and end offset as 0.

• Get Endpoint details: Using this API, client application can retrieve detailed information about an endpoint. This is an asynchronous request and the response of the API will be a request ID. After the request is completed, the requester receives a notification on registered callback URL with the device details and all its supported resources.

For more information on API structure and example requests, see the API Reference Guide.

Resources

A registered CDP client CDP platform can send a request to read/write/execute/delete a specific resource of a given device. For such requests, the response is notified on the registered callback URL later as an asynchronous response.

Notice: CDP APIs are device and protocol agnostic. Reference to LWM2M in this guide is only for illustration purpose and to provide users of this guide any overall idea on how these APIs work. Resource paths for devices may differ for different device/protocol types.
In general, resource path refers to address of resource which you want to read, write, execute, delete and can be as simple as integer values as in case of LWM2M or can be complex structures depending on specific protocol being used. For the NB-IOT CoAp and UDP adapters pre-defined resources are used please refer to the specific chapter for more details on this.

Notifications

In response to a particular request from CDP client, the CDP platform sends an event notification
through the callback URL. These notifications can be:
• Observations for resource subscriptions
• Responses to read, write, execute, and delete requests
• Lifecycle events

Observations

When an CDP client subscribes to a resource with conditional filters, the CDP platform generates a subscription ID and responds to the client with this ID and response message. Based on the conditions specified in the subscription request, whenever there is an observation from the device, the CDP platform will send the response to callback URL. The response will contain the following information:
• Subscription ID
• Serial number of device
• Time Stamp
• Value of one or more resources

Following is a sample response sent to CDP client for a resource subscription (call back URL):

{
    "reports": [
        {
            "serialNumber": "IMEI:358878080020537",
            "timestamp": 1524582877912,
            "subscriptionId": "fab4fabf-3e60-401a-bbea-cef815635d98",
            "resourcePath": "uplinkMsg/0/data",
            "value": "aabbccdd"
        }
    ],
    "registrations": [],
    "deregistrations": [],
    "updates": [],
    "expirations": [],
    "responses": []
}

Resource responses

Resource responses are the notifications that CDP platform sends to callback URL for any
asynchronous request for a resource (read, write, execute, and delete) or Endpoint (Endpoint details).
The response to a particular request to read data from a device will include:
• Request identity
• Manufacturer data (make, model, firmware)
• Group name
• Other device details like IMSI, device address, device identifier address, and a list of zero or more resources and their values.

Following is a sample response sent to CDP client for read resource:

{"reports":[],
"registrations":[],
"deregistrations":[],
"updates":[],
"expirations":[],
"responses":[{"serialNumber":"DEVKIT_779",
"timestamp":1484122186492,
"requestId":"4b587794-6624-4b7b-8c97-3046ce512f26",
"creationDate":null,
"make":null,
"model":null,
"firmwareVersion":null,
"groupName":TMNL,
"imsi":null,
"address":null,
"freeFormAddress":null,
"protocol":"LWM2M",
"resources":[{"resourcePath":"3/0/7","value":"{\"3/0/7/1\":\"5000\",\"3/0/
7/0\":\"3800\"}"}],
"result":{"code":0,"subCode":null,"reason":"Success"}}]}

Following is the sample response sent to CDP client for Get Endpoint resource request:

{"reports":[],
"registrations":[],
"deregistrations":[],
"updates":[],
"expirations":[],
"responses":[{"serialNumber":"DEVKIT_779",
"timestamp":1484127724491,
"requestId":"c4588a2e-faa5-4f17-a3a6-401bb1c6de28",
"creationDate":null,
"make":null,
"model":null,
"firmwareVersion":null,
"groupName":null,
"imsi":null,
"address":null,
"freeFormAddress":null,
"protocol":"LWM2M",
"resources":[{"resourcePath":null,"value":"{\"connectivity/0/
routerIpAddress/0\":\"192.168.1.1\",\"access/1/objectId\":\"1\",\
"connectivity/0/availableNetworkBearer/0\":\"0\",\"connectivity/0/
linkUtilization\":\"5\",\"access/2/ACL/1\":\"1\",\"server/1/lifeTime\":
\"60\",\"access/3/objectId\":\"4\",\"access/2/ACL/0\":\"15\",\"access/
1/ACL/0\":\"15\",\"device/0/powerSourceCurrent/1\":\"900\",\"device/0/
powerSourceCurrent/0\":\"125\",\"device/0/powerSourceVoltage/1\":\"5000\",\
"access/1/accessControlOwner\":\"102\",\"device/0/model\":\"Lightweight M2M
Client\",\"server/1/defaultMinimumPeriod\":\"20\",\"access/3/
accessControlOwner\":\"101\",\"device/0/powerSourceVoltage/0\":\"3800\
",\"access/3/ACL/0\":\"1\",\"device/0/utcOffset\":\"+02:00\",\"access/3/
ACL/1\":\"1\",\"access/4/objectId\":\"5\",\"access/4/accessControlOwner\
":\"-1\",\"firmware/0/updateResult\":\"0\",\"server/1/binding\":\"U\",\
"device/0/currentBindingMode\":\"U\",\"access/4/objectInstanceId\":\"-1\",
\"firmware/0/State\":\"1\",\"connectivity/0/networkBearer\":\"0\",\"device/
0/firmwareVersion\":\"1.0\",\"device/0/freeMemory\":\"15\",\"access/2/
objectInstanceId\":\"0\",\"device/0/serialNumber\":\"345000123\",\"access/
3/objectInstanceId\":\"0\",\"device/0/state/0\":\"0\",\"connectivity/0/apn/
0\":\"internet\",\"device/0/manufacturer\":\"Open Mobile
Alliance\",\"device/0/batteryLevel\":\"100\",\"access/2/objectId\":\"3\",\
"device/0/availablePowerSources/0\":\"1\",\"device/0/availablePowerSources/
1\":\"5\",\"access/0/accessControlOwner\":\"101\",\"device/0/currentTime\":
\"Thu May 02 06:40:15 EDT 2013\",\"server/1/shortServerId\":\"101\",\"access/4/ACL/1\":\"16\",\
"access/4/ACL/0\":\"1\",\"access/0/objectInstanceId\":\"0\",\"connectivity/
0/linkQuality\":\"2\",\"access/2/accessControlOwner\":\"101\",\"server/1/
notificationStoring\":\"true\",\"connectivity/0/IPAddress/0\":\"192.168.
0.100\",\"server/1/disableTimeout\":\"3600\",\"access/1/objectInstanceId
\":\"1\",\"server/1/defaultMaximumPeriod\":\"60\",\"connectivity/0/
radioSignalStrength\":\"92\",\"access/0/objectId\":\"1\",\"access/0/ACL/0\
":\"15\"}"}],
"result":{"code":0,"subCode":null,"reason":"Success"}}]}

Lifecycle events

When an CDP client subscribes to lifecycle events, that is, registration, deregistration, update
or expiry, the CDP platform generates a subscription ID and responds to the client with this ID and
response message. Whenever there is an event related to device lifecycle, the CDP platform sends a
notification to Callback URL. These lifecycle events notification will contain the following information:
• Subscription ID
• Type of event (registration, deregistration, update, and expiry)
• Serial number of the device
• Timestamp
• Device resource details (make, model, group, and so on)

Following is a sample response sent to CDP client for the lifecycle events:
• Registration

{"reports":[],
"registrations":[{"serialNumber":"DEVKIT_110","timestamp":1484128315712,
"make":"Open
Mobile Alliance","model":"Lightweight M2M
Client","firmwareVersion":"1.0","groupName":"DM.TEST",
"imsi":"N/A","address":"345000123","protocol":"LWM2M","tags":"N/A",
"subscriptionId":"260d588c-8c1c-405e-8e65-3cef145f90bb"}],
"deregistrations":[],
"updates":[],
"expirations":[],
"responses":[]}

• De-registration

{"reports":[],
"registrations":[],
"deregistrations":[{"serialNumber":"DEVKIT_110",
"subscriptionId":"534e237c-0f4a-42a8-99e1-a8408e0165a0",
"timestamp":1484129514691}],
"updates":[],
"expirations":[],
"responses":[]}

• Update

{"reports":[],
"registrations":[],
"deregistrations":[],"updates":[{"serialNumber":"DEVKIT_
110","subscriptionId":"1e025d3d-0119-4ddf-ad92-2e65ebdaa56d",
"timestamp":1484128901444}],
"expirations":[],
"responses":[]}

• Expiration

{"reports":[],
"registrations":[],
"deregistrations":[],
"updates":[],
"expirations":[":[{"serialNumber":"DEVKIT_110",
"subscriptionId":"729b1a62-01a3-470c-97aa-ebd350811198",
"timestamp":1469079441972],
"responses":[]}

CoAp and UDP adapter specific notes

Data is exchanged between CDP and NB-IOT devices (or endpoints) through the sGI interface or the MME’s T6 interface (in case of Non IP) – via MO-Data-Request and MT-Data-Request (see 3GPP spec 29.128).

A downlink (MT) communication is triggered from the CDP platform through a write request on a pre-defined object resource “downlinkMsg/0/data.”

An uplink (MO) communication is triggered by the NB-IOT endpoint autonomously, and the data is sent upstream to the CDP platform as part of a subscription on a pre-defined object resource “uplinkMsg/0/data.”

To recap; these 2 specific adapters support resource constrained devices that can not describe and manage their own resources. These adapters add an predefined resource context to data send up and down to these resource contrained devices. For more information see the LWM2M chapter.

The resource objects for now are;

(object / objectinstance / resource)

uplinkMsg/0/data
downlinkMsg/0/data
*device/0/serialNumber

These objects can be used for resource subscription calls
In the future we plan to extend these fixed objects to include more network related data

LWM2M

[OMA Lightweight M2M] (https://en.wikipedia.org/wiki/OMA_LWM2M) is a protocol from the Open Mobile Alliance for M2M or IoT device management. It relies on the COAP protocol for its data transports.
In this figure an overview of the OMA LWM2M architecture is shown

The data in the endpoint is structure according to this virtual model

The model is fixed and virtual for the resource constrained devices.

Abbreviations