Client Libraries & SDKs

Device Message 2.1

1. Overview

This document will help you understand the format of message which are getting exchanged from device to cloud and
cloud to device.

2. Acquire Connection and Connecting to IoTHub

You can either use IoTConnect REST API to get MQTT connection details to acquire connection or you can use Azure
SDK with connection string approach to acquire connection

2.1 MQTT Library – Using IoTConnect REST API
2.2 Azure SDK – Using Connection String & DPS

2.1 MQTT Library – Using REST API

REST APIs to device/framework does not support of Azure SDK or connection string-based connectivity. The user would
have to construct the connection string based on the provided information.

Discovery API

This is REST API to get the Identity API URL. IoTConnect can have multiple Discovery Url, so finding a specific URL
associated to your account is very important. You can find your associated discovery URL in the Key Vault of your
account.


If you do not find the discovery URL, your account will be using the default discovery URL
https://discovery.iotconnect.io/

Base Url:

URL_FROM_KEY_VAULT or https://discovery.iotconnect.io/

Endpoint:

/api/sdk/sid/[COMPANY_SID]

Method

GET

Example:

Request
https://discovery.iotconnect.io/api/v2.1/dsdk/sid/[COMPANY_SID]
Response

{

 

“d”: {

 

“ec”: 0,

// Error Code: [Ref] 0 – No error

“bu”: “”,

// Base URL of the Identity service

“log:mqtt”: {

// MQTT connection details to optionally send device logging

“hn”: “”,

// Hostname of MQTT broker

“un”: “”,

// Username to connect MQTT broker

“pwd”: “”,

// Password to connect MQTT broker

“topic”: “”

// Topic on which log messages can be sent

},

 

“log:https”: “”

// HTTPS url where log message needs to send [POST API]

},

 

“status”: 200,

 

“message”: “Success”

// based on value of ec

// 0 – Success

// 1 – Invalid value of SID

// 2 – Company not found

// 3 – Subscription Expired

}

 

2.1.2: Identity API

On success of Discovery Call, you will get the URL of the Identity API. This API will provide additional values that will
required to establish the device connection, send telemetry data etc.

Base Url: URL_PROVIDED_BY_DISCOVERY_API
Endpoint: uid/[DEVICE_UNIQUE_ID]
Method GET

Identity Response

{

 

“d”: {

 

“ec”: 0,

// Error Code: [Ref] 0 – No error

“ct”: 200,

 

“meta”: {},

// Device Meta information

“has”: {},

// Device ability information

“p”: {},

// Protocol information

}

 

}

 

Device Meta information i.e. d.meta will have different structure based on device type which
is Normal Device or Gateway Device

Values for meta

{

 

“df”: 60,

// Data Frequency defined on template to control device data send frequency

“cd”: “”,

// Unique code with 7 or 8 characters.

“at”: 1,

// Authentication type of device. [Ref]

“gtw”: {

// **

“tg”: “”,

// String represents the gateway Tag

“g”: “”,

// GUID represents the device GUID

},

 

“edge”: 0,

// 1 – If device is Edge Device

“pf”: 1,

// TBD. 1 – If need to add prefix while enrolling into Azure DPS

“hwv”: “”,

// Hardware version of the firmware pushed by OTA

“swv”: “”

// Software version of the firmware pushed by OTA Device software version

“v”: 2.1

// Message Protocol Version

}

 

** gtw will be null if device is not Gateway

Values of has

{

 

“d”: 0,

// If 1 – Gateway Device can send 204 message to get all child devices

“attr”: 1,

// If 1 – Device can send 201 message to get all attribute details

“set”: 0,

// If 1 – Device can send 202 message to get updates on settings/twins

“r”: 0,

// If 1 – Edge Device can send 203 message to get all rules

“ota”: 0

// If 1 – Device can send 205 message to get pending OTA

}

 

Protocol information i.e. d.p will have different structure based on authentication type. You
can use protocol information provided in Identity API response to connect MQTT and start sending D2C on topic based
on message type and subscribe c2d topic to receive cloud message.

Values of p [Non-TPM Auth Type]

{

 

“n”: “mqtt”,

// A string represents the name of protocol.

“h”: “”,

// A string represents the mqtt host name to connect

“p”: 8883,

// A fixed integer represents port to connect mqtt host

“id”: “”,

// A string represents the mqtt client id

“un”: “”,

// A string represents the username for mqtt connection

“pwd”: “”,

// A string represents the password to connect mqtt broker **

“topics”: {}

// Object contains the topics for device to send and receive messages

}

 

** Comes if auth type is Token, for Symmetric Key, X509 Certificate this will not be part of json

Values of p [Auth Type TPM]

{

 

“h”: “”,

// A string represents the mqtt host name to connect

“rid”: “”,

// A string represents registration id (if device is not acquired)

}

 

Values of p.topics

{

 

“rpt”: “”,

// A string represents the publish topic of reporting message

“erpt”: “”,

// A string represents the publish topic of edge reporting message **

“flt”: “”,

// A string represents the publish topic of fault message

“od”: “”,

// A string represents the publish topic of offline message

“hb”: “”,

// A string represents the publish topic of heartbeat message

“erm”: “”,

// A string represents the publish topic of rule matched message **

“ack”: “”,

// A string represents the publish topic to send acknowledgements

“dl”: “”,

// A string represents the publish topic to send Device Logs

“di”: “”,

// A string represents the publish topic to send Device Identity messages

“c2d”: “”

// A string represents the topic for subscribe to receive cloud to device messages

}

 

** Only comes if device is Gateway Type

Values of p [If protocol is https]

{

 

“n”: “https”,

// A string represents the name of protocol.

“url”: “”,

// A string represents the mqtt host name to connect

“auth”: “”,

// A string represents the authorization of url

}

 

For MQTT there is support for Twin Property management as well. For this below additional topic needs
to be subscribed

$iothub/twin/PATCH/properties/reported/?$rid=1

Send twin to this topic to report property update

$iothub/twin/PATCH/properties/desired/#

Subscribe this topic to receive desired property value

$iothub/twin/GET/?$rid=0

Publish blank message to receive all device twin

$iothub/twin/res/#

Subscribe this topic to receive all device twin

For direct method below additional topics needs to be subscribed

$iothub/methods/POST/{method name}/?$rid={request id}

Subscribe to receive direct method intimation

$iothub/methods/POST/#

Single subscription to receive all direct method calls

Note: The number of subscriptions per device is limited to 5. It is therefore recommended not
to subscribe to each direct method individually

Working with HTTPS

If protocol information specifies ‘https’ as the name of protocol then you have only single operation
available to do, which is sending telemetry by making POST call at given url specified in protocol information i.e.
p.url, along with this there are additional header needs to be added as mentioned in below table.

Url:

[p.url]

Header
  1. “accept”: “application/json”
  2. “content-type”: “application/json”
  3. “authorization”: [p.auth]
  4. “iothub-app-cd”: [meta.cd]
  5. “iothub-app-v”: [meta.v]

Method

POST

Body

[SENSOR_DATA_JSON]

p.url: The value which received from Identity API response in protocol information

p.auth: The value which received from Identity API response in protocol information

2.2 Azure SDK – Using Connection String & DPS

Connection String:

If you are building your SDK on top of Azure IoT SDK, which are based on connection string to create
connection with IoTHub. You can find device connection string at the connection information tab on Device.

You can create Device SDK Client, provide the connection string, and connect to the
broker.

Azure Device Provisioning Service:

If you are using Azure IoT SDK with DPS then you need Scope ID and global service
endpoint. Platform support two types of DPS, one is dedicated to Sphere Device and other is general purpose. In
either case you need to raise support ticket to enable DPS

DPS for Non-Sphere Device

DPS info for Sphere Device

You can create Azure DPS client object with required information and get IoTHub connection.
Assumption: SDK Assume that enrollment is done for TPM device

For TPM we need below information at device end

  • ScopeID
  • Global Service Endpoint

Note: RPI – Exceptional case where without enabling DPS these devices use to get working. With 2.1
onwards they need to enable DPS first. Till now RPI is using default DPS (IoTConnect’s private DPS).

Find required device sdk from Azure IoT Device SDKs and use Key Vault and device connection string to acquire and connect to
IoTHub.

Once you get connected to IoTHub using either connection string or DPS, device must send hello
message first to get its identity at IoTConnect along with metadata

{

“mt”: 200,                      // Message type

“sid”: “”                          // Company SDK Identity from Key Vault section of your portal account

}

  1. !!IMPORTANT – Without this information platform will discard the message!!

    • MQTT Library Approach – NA

    • Azure SDK Approach – You need to add message below properties

    v – 2.1

    di – 1

On failure, you will receive the following JSON

{

“d”: {

“ec”: 1,                       // Error code > 0. Ref Table

“ct”: 200                     // Command type

}

}

Note: In case of Sphere or dedicated IoTHub for solution or any other usecase sid can be
blank. Hello message with blank sid will be sent by Device and IoTConnect verify its validity and provide valid;
else it will return ec=8 i.e., Connection Not Allowed.

On success IoTConnect will send json like Identity API returns, the only difference is, response of
Hello wont contains d.p

i.e., Protocol Information

200 Hello message Response

{

 

“d”: {

 

“ec”: 0,

// Error Code: [Ref] Possible Values 0, 1, 2, 3, 4, 5, 6

“ct”: 200,

 

“meta”: {},

// Device Meta information

“has”: {},

// Device ability information

}

 

}

 

Device Meta information i.e. d.meta will have different structure based on device type which
is Normal Device or Gateway Device. Minor change in response if its normal device then gtw will be null

Values for d.meta

{

 

“df”: 60,

// Data Frequency defined on template to control device data send frequency

“cd”: “”,

// Unique code with 7 or 8 characters.

“gtw”: {

**

“tg”: “”,

// String represents the gateway Tag

“g”: “”,

// GUID represents the device GUID

},

 

“edge”: 0,

// 1 – If device is Edge Device

“pf”: 1,

// TBD

“hwv”: “”,

// Hardware version of the firmware pushed by OTA

“swv”: “”

// Software version of the firmware pushed by OTA Device software version

“v”: 2.1

// Message Protocol Version

}

 

** For normal device gtw will be null

Values of d.has

{

 

“d”: 0,

// If 1 – Gateway Device can send 204 message to get all child devices

“attr”: 1,

// If 1 – Device can send 201 message to get all attribute details

“set”: 0,

// If 1 – Device can send 202 message to get updates on settings/twins

“r”: 0,

// If 1 – Edge Device can send 203 message to get all rules

“ota”: 0

// If 1 – Device can send 205 message to get pending OTA

}

 

Till now we got Device meta data using MQTT or Azure SDK Approach. Now all
communication will share same protocol regardless of approach in terms of JSON structure. You need to make sure the
publish part is little bit different based on approach.

  1. Device Identity Messages

To retrieve more information on attribute, setting, rules etc device must send json with specific message type.

Message Type

Description

201

Get Device Template Attributes

202

Get Device Template Setting/Twin

203

Get Edge Rule. This works if your device is Edge device

204

Get child devices. This works if your device is Gateway device

205

Get the pending OTAs

3.1 Get Device Attributes

Send MQTT message having below JSON

{

“mt”: 201

}

  1. !!IMPORTANT – Without this information platform will discard the message!!

    • MQTT Library Approach – You need to send message on di topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    di – 1

 

Response

{

 

“d”: {

 

“att”: [{

 

“p”: “”,

// Parent attribute name (empty – this is a top-level attribute, not nested in an object)

“dt”: 1,

// Data type of attribute. Can be 0 or 11 Ref

“tg”: “”,

// Tag of parent/child device **

“d”: [{

 

“tg”: “”,

// Tag of parent/child device **

“ln”: “”,

// Local name of attribute (attribute name) *

“dt”: 0,

// Data type of attribute * Ref

“dv”: “”,

// Data validation – If applied

“sq”: 1,

// Sequence of attribute *

“tw”: “”,

// Tumbling window time: Ref **

}

 

]

 

}

 

],

 

“ct”: 201,

// Response of message type 201

“ec”: 0

// 0 – No error, 1 – Server Error

}

 

}

 

** “tg” will come if it is Gateway Device

** “tw” will come if it is Edge Device

3.2 Get Device Settings (twin)

Send MQTT message having below JSON

{

“mt”: 202

}

  1. !!IMPORTANT – Without this information platform will discard the message!!

    • MQTT Library Approach – You need to send message on di topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    di – 1

Response [No settings / Twin available]

{

 

“d”: {

 

“set”: null,

// No Settings / Twin

“ct”: 202,

// Response of message type 202

“ec”: 0

// 0 – No error, 1 – Server Error

}

 

}

 

Response

{

 

“d”: {

 

“set”: [{

 

“ln”: “”,

// Local name of setting/Twin

“dt”: 0,

// Data type of setting * Ref

“dv”: “”

// Data validation – If applied. Ref

}

 

],

 

“ct”: 202,

 

“ec”: 0

// 0 – No error, 1 – Server Error

}

 

}

 

3.3 Get Rules for Edge Device

This message works for Edge Gateway only. For Edge Gateway, it’s required to have all
rules defined in portal to do evaluation before sending message. To get all rules defined on device template, Send
MQTT message having below JSON

{

“mt”: 203
}

  1. !!IMPORTANT – Without this information platform will discard the message!!

    • MQTT Library Approach – You need to send message on di topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    di – 1

Response

{

 

“d”: {

 

“r”: [{

 

“g”: “”,

// GUID to identify rule (To be used in 4.4 Edge Rule Match )

“es”: “”,

// Event Subscription GUID

“con”: “”,

// The rule condition. Using a special format that can be parsed with IoTConnect SDKs

“cmd”: “”

// If command needs to execute on device if rule matched

}

 

],

 

“ct”: 203,

// Response of message type 203

“ec”: 0

// 0 – No error, 1 – Server Error

}

 

}

 

Note: The condition rule (con) is using a special format that can be parsed with IoTConnect SDKs. This feature is built
for edge gateways that are capable to execute rules directly on gateway.

Response [no rule available]

{

“d”: {

“r”: null,                     // No Rule

“ct”: 203,                   // Response of message type 203 “ec”: 0                // 0 – No error, 1 – Server Error

}

}

3.4 Get Child Devices for Gateway Device

This message works only for Gateway Device. For Gateway Device, it’s required to have list of child
devices that have been added to portal. To get child device. Send MQTT message having below JSON

{

“mt”: 204
}

  1. !!IMPORTANT – Without this information platform will discard the message!!

    • MQTT Library Approach – You need to send message on di topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    di – 1

Response

{

“d”: {

“d”: [

{

“tg”: “”,              // Tag of child device

“id”: “”               // Uniqueid of child device

}],

“ct”: 204,                    of message type 204

“ec”: 0                        // 0 – No error, 1 – Server Error

}

}

3.5 Get Device OTA Update

To get the pending OTA message device. Send MQTT message having below JSON

{

“mt”: 205
}

  1. !!IMPORTANT – Without this information platform will discard the message!!

    • MQTT Library Approach – You need to send message on di topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    di – 1

  Response                                                                                                                                                                                                             

{

 

“d”: {

 

“ota”: {

 

“cmd”: “ota”,

// OTA command which defined in the template

“ack”: “”,

// Acknowledgement GUID

“ver”: {

 

“sw”: “”,

// Software version

“hw”: “”

// Hardware version

},

 

“urls”:

[// It will contain multiple urls along with respective tag of child/parent devices.

{

 

“url”: “”,

// Downloadable OTA update url

“fileName”: “”

// Name of the OTA file with extension

“tg”: “”

// Tag of child/parent device which have OTA update file defined in firmware upgrade

}

 

]

 

},

 

“ct”: 205,

// Response of message type 205

“ec”: 0

// 0 – No error, 1 – Server Error

}

 

}

 

** “tg” will come if it is Gateway Device

Response [no OTA available]

{

“d”: {

“ota”: null,                 // No OTA available

“ct”: 205,                   // Response of message type 205 “ec”: 0                // 0 – No error, 1 – Server Error

}

}

3.6 Create Child Device [Only for Gateway Type]

Send below JSON message with property di = 1 needs to be sent form device to create child device

{

 

“mt”: 221,

 

“d”: {

 

“g”: “”,

// g from hello response or REST response. Its gateway device GUID

“dn”: “”,

// String represents the child device display name

“id”: “”,

// String represents the child device unique id

“tg”: “”

// String represents the tag of child device

}

 

}

 

Response

{

 

“d”: {

 

“ec”: 0,

// Error Code: [Ref] Possible Values 0, 1, 2, 3, 4, 5, 6, 7, 8

“ct”: 221,

 

}

 

}

 

3.7 Delete Child Device [Only for Gateway Type]

Send below JSON message with property di = 1 needs to be sent from device to delete child device

{

 

“mt”: 222,

 

“d”: {

 

“id”: “”

// String represents the child device unique id

}

 

}

 

  1. !!IMPORTANT – Without this information platform will discard the message!!

    • MQTT Library Approach – You need to send message on di topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    di – 1

Response

{

 

“d”: {

 

“ec”: 0,

// Error Code: [Ref] Possible Values 0, 1

“ct”: 222,

 

}

 

}

 

  1. Device to Cloud Messages [D2C]

Once device has all required details, it can start sending telemetry to IoTConnect. Telemetry may
vary based on device type structure. IoTConnect accepts various types of telemetry data from device based on device
type defined in IoTConnect Portal.

    1. Reporting Message
    2. Fault Message
    3. Edge Reporting Message
    4. Edge Rule Matched Message
    5. Heartbeat Message
    6. Acknowledgement Message
    7. Device Log Message

    1. Reporting Message

  1. This is a normal message that a device should send to report their sensor value

    !!IMPORTANT!!

    • MQTT Library Approach – You need to send message on rpt topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    mt – 0

 

Device Message

{

 

“dt”: “”,

// Current date time, format YYYY-MM-DDTHH:MM:SS.SSSZ

“d”: [{

// Can have multiple value

“id” :””,

// Parent/child device unique id **

“tg”: “”,

// Tag of respective parent/child device **

“dt”: “”,

// Current date time, format YYYY-MM-DDTHH:MM:SS.SSSZ

“d”: {

 

“attrName1”: “attVal”,

// String attribute

“attrName2”: 1,

// Number attribute

“attrName3”: {

// Object attribute

“attrName4”: -240

// Number attribute

}

 

}

 

}

 

]

 

}

 

** “tg” will come if it is Gateway Device

** “id” will come if it is Gateway Device

    1. Fault

The device can send a fault message if something is invalid coming from the sensor or the value is
not falling into the data validation applied to that device. The JSON format will be the same as reporting

    1. Edge Reporting

This message is sent by Edge Device; it can be Normal Edge device and Gateway Edge device.

  1. !!IMPORTANT!!

    • MQTT Library Approach – You need to send message on erpt topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    mt – 1

Edge Device

{

 

“dt”: “”,

// Current date time, format YYYY-MM-DDTHH:MM:SS.SSSZ

“d”: [{

// Can have multiple value

“id”: “”,

// Parent/child device unique id **

“tg”: “”,

// Tag of respective parent/child device **

“dt”:””,

// Current date time, format YYYY-MM-DDTHH:MM:SS.SSSZ

“d”: {

 

“attrName1”: [

// Number attribute

1.0,

// Min

5.0,

// Max

6.0,

// Sum

3.0,

// Average

2.0,

// Count

5.0

// Latest Value

],

 

“attrName2”: {

// Object attribute

“childAttr1”: [

// Child attribute name

1.0,

// Min

5.0,

// Max

6.0,

// Sum

3.0,

// Average

2.0,

// Count

5.0

// Latest Value

]}

 

}

}

]

 

}

 

** “tg” will come if it is Gateway Device

** “id” will come if it is Gateway Device

    1. Edge Rule Match

Edge Device should send this message when any rule is evaluated as true on telemetry data. JSON
format will have all information of rule and telemetry data

  1. !!IMPORTANT!!

    • MQTT Library Approach – You need to send message on erm topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    mt – 2

 

{

 

“dt”: “”,

// Current date time, format YYYY-MM-DDTHH:MM:SS.SSSZ

“d”: [{

 

“rg”: “”,

// Rule GUID from rule response

“ct”: “”,

// Rule condition from rule response

“cv”: {

// Telemetry condition value

“attrname”: {

 

“attrname”: value

}

 

},

 

“sg”: “”,

// event subscription GUID from rule response

“d”: [{

// Device telemetry data

“attrname”: value

}

 

],

 

“id”: “”,

// Child/Parent device uniqueid

“dt”: “”,

// Current time stamp in format YYYY-MM-DDTHH:MM:SS.SSSZ

“tg”: “”

// Child/Parent device tag

}

 

]

 

}

 

** “tg” will come if it is Gateway Device

    1. Heartbeat Message

  1. !!IMPORTANT!!

    • MQTT Library Approach – You need to send message on hb topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    mt – 5

Need to send blank message

{
}

4.6 Acknowledgement Message

4.6.1 Device Command acknowledgement:

Following JSON should be sent by device to the cloud to acknowledge Device Command

  1. !!IMPORTANT!!

    • MQTT Library Approach – You need to send message on ack topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    mt – 6

Message Format

{

 

“dt”: “”,

// Current time stamp in format YYYY-MM-DDTHH:MM:SS.SSSZ

“d”: {

 

“ack”: “”,

// Acknowledgement GUID

“type”: 0,

// Fixed – Acknowledgement of Command

“st”: 0,

// Status of Acknowledgement Ref

“msg”: “”,

// Your custom message for acknowledgement

“cid”: “”

// Applicable if ack is being sent for child device otherwise null **

}

 

}

 

** Add “cid” only if acknowledgement is for child device, else should be omitted.

4.6.2 OTA Command acknowledgement:

Following JSON should be sent by device to the cloud to acknowledge OTA Command

  1. !!IMPORTANT!!

    • MQTT Library Approach – You need to send message on ack topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    mt – 6

Message Format

{

 

“dt”: “”,

// Current time stamp in format YYYY-MM-DDTHH:MM:SS.SSSZ

“d”: {

 

“ack”: “”,

// Acknowledgement GUID

“type”: 1,

// Fixed – Acknowledgement of OTA

“st”: 0,

// Status of Acknowledgement Ref

“msg”: “”,

// Your custom message for acknowledgement

“cid”: “”

// Applicable if ack is being sent for child device otherwise null **

}

 

}

 

** Add “cid” if device is gateway and acknowledgement is for child device, else should be omitted.

4.6.3 Module Command acknowledgement:

Following JSON should be sent by device to the cloud to acknowledge Module Command

  1. !!IMPORTANT!!

    • MQTT Library Approach – You need to send message on ack topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    mt – 6

Message Format

{

 

“dt”: “”,

// Current time stamp in format YYYY-MM-DDTHH:MM:SS.SSSZ

“d”: {

 

“type”: 2,

// Fixed – Acknowledgement of Module

“st”: 0,

// Status of Acknowledgement Ref

“msg”: “”,

// Your custom message for acknowledgement

}

 

}

 

4.7 Device Log Message

This message type allows device to send logs over MQTT

  1. !!IMPORTANT!!

    • MQTT Library Approach – You need to send message on dl topic found in protocol information under topics object

    • Azure SDK Approach – You need to add message below properties

    cd – meta.cd [Unique code received in Hello Message response]

    v – meta.v [Message protocol version received in Hello Message response]

    mt – 7

Message can be json or text.

If you do not find the discovery URL

  1. Cloud to Device commands [C2D]

OTA and Command have various status based on the action.

Actions

Command

OTA

Initial Status

In Queue

In Queue

Device is offline

Waiting for Connect

Waiting for Connect

Received by Device

Sent

Sent

Device is still offline (retry policy)

Failed

Waiting for Connect

Acknowledgement

Received Ack

– NA –

OTA Command Success

– NA –

Success

OTA Command Failed

– NA –

Failed

Command Retry Policy: If device offline/disconnected; platform will wait 60 minutes to get
device online, else it will be considered as Failed. 60 minutes is default wait period, which can be changed from
configuration section

OTA Retry Policy: If device offline/disconnected; platform will wait until device get connected

5.1 Device Command C2D:

IMPORTANT: When receiving the C2D messages using an MQTT client
implementation, ensure that MQTT messages are acknowledged at MQTT level (QOS1). Otherwise, the device may be
receiving repeat C2D messages if it disconnects and comes back online withing a short time.

Following JSON will be received by device when there is any command sent from
IoTConnect portal

 

{

 

“ct”: 0,

// 0 – Device command received by device from cloud

“v”: 2.1

// version

“cmd”: “”,

// String represents the command text

“id”: “”,

// Child device UniqueID **

“ack”: “”

// GUID represents the acknowledgement id; required while sending acknowledge back to platform **

}

 

** “ack” will come ONLY if command required acknowledgement

** “id” will come ONLY if device is Gateway and its for child device

5.2 OTA Command C2D:

Following JSON will be received by device when there is any OTA sent from IoTConnect portal

 

{

 

“ct”: 1,

// 1 – OTA Command

“v”: 2.1,

// version

“cmd”: “ota”,

// String represents the command text, default is ota, can be changed from template

“ack”: “[GUID]”,

// Needs to send this in OTA Acknowledgement command

“sw”: “1.0.0”,

 

“hw”: “1.0.0”,

 

“urls”: [{

 

“url”: “<URL1>”,

// Downloadable OTA update url with expiry

“fileName”: “”,

// Name of the OTA file with extension

“tg”: “”

// Tag of device **

}, {

 

“url”: “<URL2>”

// Downloadable OTA update url with expiry

“fileName”: “”,

// Name of the OTA file with extension

“tg”: “”

// Tag of device **

}

 

]

 

}

 

** “tg” will come if it is Gateway Device

5.3 Module Command:

Following JSON will be received by device when there is any module push sent from IoTConnect portal

Module Command request

{

 

“ct”: 2,

 

“v”: 2.1

// version

“urls”: [{

 

“url”: “”

// Downloadable Module url with expiry

“fileName”: “”

// Name of the Module file with extension

}

 

]

 

}

 

* If no acknowledgement is required then json will not have ack attribute

5.4 Other Commands

Platform can send below command to ask device to do some operation. This can be metadata update
request or stop communication etc. All these messages will have below format, based on type device must react.

{

 

“ct”: 101

// Number represents the command type; possible values can be 101 to 111

“v”: 2.1

// version

}

 

Possible values of ct can be

ct

Command

Action

Device Commands

0

Device command

Device command received by device from cloud

1

OTA Command

OTA Command received by device from cloud

2

Module Command

Module Command received by device from cloud

101

Refresh Attribute.

Device must send message of type 201 to get updated attributes

102

Refresh Setting/Twin.

Device must send message of type 202 to get updated settings or twin

103

Refresh Edge Rule.

Device must send message of type 203 to get updated Edge rules

104

Refresh Child Device.

Device must send message of type 204 to get updated child devices

105

Data Frequency Change

Device needs to update frequency received in this message

Device lifecycle Commands

106

Device Deleted

Device must stop all communication and release the mqtt connection

107

Device Disabled

Device must stop all communication and release the mqtt connection

108

Device Released

Device must stop all communication and release the mqtt connection

109

Stop Operation

Device must stop all communication and release the mqtt connection

Heartbeat commands

110

Start Heartbeat

Device must start sending heartbeat

111

Stop Heartbeat

Device must stop sending heartbeat

105 – Data Frequency Change Message

{

 

“ct”: 105

// Device frequency change command

“v”: 2.1

// version

“df”: 30

// New device frequency

}

 

Start Heartbeat command

{

 

“ct”: 110,

// Heartbeat command

“v”: 2.1

// version

“f”: 5

// Frequency of sending heartbeat from device, this is in second

}

 

  1. Reference Table

6.1 Message Types

Message Type

Description

Device Identity Message

200

Hello Message / Identity Message. To pull all metadata of device this message is required. This work with DPS and Connection String base approach

201

Get device attributes. Device should ask all attribute along with all properties to make validation

before reporting telemetry.

202

Get device settings / twins. Device should ask all twin to make sure device is doing valid twin

update.

203

Get rules for Edge device. Edge device should send this message to get rule details to evaluate rule

and send Rule Matched message

204

Get child devices of Gateway Device. Gateway device should send this message to get its child

device, this makes sure no addition device can start communicating and sending data to platform. Gateway device must send data which are defied as child

205

Get Device OTA updates. In case device missed out OTA or need pending OTA; device can send this

message to receive pending OTAs

210

Device can get all information in single message like Attribute, Settings, Devices (if Gateway), Rules (If Edge) OTA by sending this message type. There will be single response having all details

Gateway Operation Message

221

Create child device. Note: Device type must be gateway

222

Deleting child device. Note: Device type must be gateway

6.2 Error Codes

6.2.1 Hello Message & REST API

 

Error Code

Description

0

OK – No Error.

1

Device not found. Device is not whitelisted to platform

2

Device is not active

3

Un-Associated. Device has not any template associated with it

4

Device is not acquired. Device is created but it is in release state

5

Device is disabled. It’s disabled from IoTHub by Platform Admin

6

Company not found as SID is not valid

7

Subscription is expired

8

Connection Not Allowed

9

Invalid Bootstrap Certificate

10

Invalid Operational Certificate

6.2.2 Create Child Device

Error Code

Description

0

OK – No Error. Child Device created successfully

1

Message missing child tag

2

Message missing child device uniqueid

3

Message missing child device display name

4

Gateway device not found

5

Could not create device, something went wrong

6

Child device tag is not valid

7

Child device tag name cannot be same as Gateway device

8

Child uniqueid is already exists.

9

Child uniqueid should not exceed 128 characters

6.2.3 Delete Child Device

Error Code

Description

0

OK – No Error. Child Device deleted successfully

1

Child device not found

6.3 Auth Types

Message Type

Description

1

Token

2

CA Signed Certificate

3

Self-Signed Certificate

4

TPM

5

Symmetric Key

6.4 Supported Data Types

Data Type

Availability

Description

 

Attribute

Setting

 

0

Yes

Yes

Non-Object (without parent attribute)

1

Yes

Yes

Integer

2

Yes

Yes

Long

3

Yes

Yes

Decimal

4

Yes

Yes

String

5

Yes

Yes

Time

6

Yes

Yes

Date

7

Yes

Yes

DateTime

8

Yes

Yes

BIT [ 0 / 1]

9

Yes

Yes

Boolean [ true / false | True/False]

10

Yes

Yes

Duration

11

Yes

–

LatLong [ Decimal Array, Decimal (10,8), Decimal (11,8) ]

12

Yes

–

Object

6.5 Tumbling Window Time [Edge Device]

Description

It should be 1 to 999 ending with h/m/s

Minimum 60 seconds required

For example:

5h (h =     hour) 15m (m = minute) 60s (s = seconds)

6.6 Data Validations [Edge Device]

Description

Type validation values and/or validation ranges separated by commas

For example:

1, 2, 10 to 20

-100 to -500, -15

Red, Green, Blue

6.7 Command Acknowledgement Status

Message Type

Description

0

Success

1

Failed

2

Success with Acknowledgement

6.8 OTA Acknowledgement Status

Message Type

Description

0

Success

1

Failed

2

Downloading in progress

3

Download Done

4

Download failed