IoTConnect SDK
Device Command C2D
JSON payload for users who use Bring your own SDK method to received Device Commands.
{
"cmdType": "0x01",
"data": {
"cpid": "<cpid>",
"guid": "<guid>", //Device Guid
"uniqueId": "<cpid-uniqueid>",
"command": "OnOff ::Manual Command::",
"ack": false,
"ackId": "<guid>",
"cmdType": "0x01"
}
}
{
"cmdType": "0x01",
"data": {
"cpid": "<cpid>",
"guid": "<guid>", //Device Guid
"uniqueId": "<cpid-uniqueid>",
"command": "OnOff ::Manual Command::",
"ack": false,
"ackId": "<guid>",
"cmdType": "0x01"
}
}
cpid: It indicates the CPID of the device’s company
ack: Acknowledgement status
command: Command Text
uniqueId: It is the device uniqueID
cmdType: Command type constant code 0x01 – Device command, 0x02 – OTA COmmand
ackId: Acknowledgement ID/GUID
guid: Command GUID
Retry Policy: If the device offline/disconnected from the IotConnect then the Device will not receive the device command, Platform will not resent when its online.
OTA Command C2D
JSON for the OTA command Cloud to Device payload
Device and Edge Device
{
"cmdType": "0x02",
"data": {
"cpid": "<cpid get it from portal>",
"guid": "<device_guid>",
"uniqueId": "<uniqueId>",
"command": "ota",
"ack": false,
"ackId": "<acknowledgement_guid>",
"cmdType": "0x02",
"ver": {
"sw": "<Software Version>",
"hw": "<Hardware Version>",
},
"urls": [{
"url": "<url1>",
"tag": "
},
{
"url": "<url2>",
"tag": "
}]
}
}
{
"cmdType": "0x02",
"data": {
"cpid": "<cpid get it from portal>",
"guid": "<device_guid>",
"uniqueId": "<uniqueId>",
"command": "ota",
"ack": false,
"ackId": "<acknowledgement_guid>",
"cmdType": "0x02",
"ver": {
"sw": "<Software Version>",
"hw": "<Hardware Version>",
},
"urls": [{
"url": "<url1>",
"tag": "
},
{
"url": "<url2>",
"tag": "
}]
}
}
Gateway and Edge Gateway Device
{
"cmdType": "0x02",
"data": {
"cpid": "<cpid get it from portal>",
"guid": "<device_guid>",
"uniqueId": "<uniqueId>",
"command": "ota",
"ack": false,
"ackId": "<acknowledgement_guid>",
"cmdType": "0x02",
"ver": {
"sw": "<Software Version>",
"hw": "<Hardware Version>",
},
"urls": [{
"url": "<url1>",
"tag": "<child device1 tag>"
},
{
"url": "<url2>",
"tag": "<child device1 tag>"
},
{
"url": "<url1>",
"tag": "<child device2 tag>"
},
{
"url": "<url1>",
"tag": "<Gateway device tag>"
}]
}
}
{
"cmdType": "0x02",
"data": {
"cpid": "<cpid get it from portal>",
"guid": "<device_guid>",
"uniqueId": "<uniqueId>",
"command": "ota",
"ack": false,
"ackId": "<acknowledgement_guid>",
"cmdType": "0x02",
"ver": {
"sw": "<Software Version>",
"hw": "<Hardware Version>",
},
"urls": [{
"url": "<url1>",
"tag": "<child device1 tag>"
},
{
"url": "<url2>",
"tag": "<child device1 tag>"
},
{
"url": "<url1>",
"tag": "<child device2 tag>"
},
{
"url": "<url1>",
"tag": "<Gateway device tag>"
}]
}
}
urls: OTA Firmware bundle file URLs to update the firmware
ver: Firmware version
tag: It is the associated tag with the device and template (Blank for normal Device)
– sw: Software version of the Firmware
– hw: Hardware version of the Firmware
If you are using less than 2.0 version then follow the below JSON for the payload.
{
"cmdType": "0x02",
"data": {
"cpid": ",
"guid": ",
"uniqueId": ",
"command": "ota ,",
"ack": false,
"ackId": ",
"cmdType": "0x02",
"ver": {
"sw": "1.0.0",
"hw": "1.0.0"
},
"urls": [","]
}
}
{
"cmdType": "0x02",
"data": {
"cpid": ",
"guid": ",
"uniqueId": ",
"command": "ota ,",
"ack": false,
"ackId": ",
"cmdType": "0x02",
"ver": {
"sw": "1.0.0",
"hw": "1.0.0"
},
"urls": [","]
}
}
Retry Policy: If device offline/disconnected from the IotConnect then Device will not receive OTA command, But when its online again or connected with IotConnect Platform will resent all OTA command to Device.
Module Command
JSON payload for users who use Bring your own SDK method to received Module Commands.
{
"cmdType": "0x03",
"data": {
"cpid": "<cpid>",
"guid": "<guide>",
"uniqueId": "<device id>",
"command": "module",
"ack": false,
"ackId": "5334453f-cd4d-49ac-a755-4ecf368d2732",
"cmdType": "0x03",
"urls": [
{
"url": "
}
]
}
}
{
"cmdType": "0x03",
"data": {
"cpid": "<cpid>",
"guid": "<guide>",
"uniqueId": "<device id>",
"command": "module",
"ack": false,
"ackId": "5334453f-cd4d-49ac-a755-4ecf368d2732",
"cmdType": "0x03",
"urls": [
{
"url": "
}
]
}
}
Template Attribute Change
JSON payload for users who are not using our SDK or bring your own SDK users to received Template Attribute Change commands.
{
"cmdType": "0x10",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
{
"cmdType": "0x10",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
Template Settings Change
JSON payload for users who are not using our SDK or bring your own SDK users to received Template Settings Change commands.
{
"cmdType": "0x11",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
{
"cmdType": "0x11",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
Rule Change Command
JSON payload for users who are not using our SDK or bring your own SDK users for Rule Change commands.
{
"cmdType": "0x15",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
{
"cmdType": "0x15",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
Device Change Command
JSON payload for users who are not using our SDK or bring your own SDK users for Rule Change commands.
{
"cmdType": "0x13",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
{
"cmdType": "0x13",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
Password Change Command
JSON payload for users who are not using our SDK or bring your own SDK users for Rule Change commands.
{
"cmdType": "0x12",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
{
"cmdType": "0x12",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
Hard Stop Command
JSON payload for users who are not using our SDK or bring your own SDK users for Rule Change commands.
{
"cmdType": "0x99",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
{
"cmdType": "0x99",
"data": {
"cpid": "<cpid>",
"guid": "<guide>", //Device Guid
"uniqueId": "<device id>",
"command": null,
"ack": false,
"ackId": null
}
}
NOTE : Attribute, Setting, Rule, Device, Password change, Hard Stop commands will be handled internally in IoTConnect SDK. So it will be available for non IoTConnect SDK only. Also, it is not required acknowledgment.
Device Twin Message
To get all whole device twin you need to publish blank message on $iothub/twin/GET/?$rid=0 topic, IoTConnect (iothub) will send whole device twin on $iothub/twin/res/# topic, so you need to subscribe $iothub/twin/res/# topic.
You will receive Twin property in the below JSON format.
{
"desired": {
"frm_version": 1.5
"$version": 48
},
"reported": {
"$version": 44
}
}
{
"desired": {
"frm_version": 1.5
"$version": 48
},
"reported": {
"$version": 44
}
}
desired: Native property of the Twin message
– frm_version: It is the property and value added into the iotconnect portal from “Template -> Twin property”
reported: Native property of the Twin message
$version: Version will be auto increment done by IoTHub for both desired and reported properties.
On change of desired property for the device, a message from IoTConnect (IotHub) will be published and you can receive it on $iothub/twin/PATCH/properties/desired/# topic. So, you need to subscribe to this topic to receive desired property value.
You will receive Twin Desired property in the below JSON format.
{
"frm_version": 1.6,
"$version": 49
}
{
"frm_version": 1.6,
"$version": 49
}
Device Attributes
User can get the list of attributes associated with the device by using the getAttributes() method provided in the
SDK. Here, you can see the attribute sample JSON with the type of device.
Non-edge device attributes
[{
"device": {
"id": "dee02"
},
"attributes": [{
"ln": "Temperature",
"dt": "number",
"dv": "5 to 20, 25"
},
{
"ln": "gyroscope",
"dt": "object",
"d": [{
"ln": "x",
"dt": "number",
"dv": "
},
{
"ln": "y",
"dt": "string",
"dv": "red, gray, blue"
},
{
"ln": "z",
"dt": "number",
"dv": "-5 to 5, 10"
}]
}]
}]
[{
"device": {
"id": "dee02"
},
"attributes": [{
"ln": "Temperature",
"dt": "number",
"dv": "5 to 20, 25"
},
{
"ln": "gyroscope",
"dt": "object",
"d": [{
"ln": "x",
"dt": "number",
"dv": "
},
{
"ln": "y",
"dt": "string",
"dv": "red, gray, blue"
},
{
"ln": "z",
"dt": "number",
"dv": "-5 to 5, 10"
}]
}]
}]
id: Device’s unique ID
ln: Local name / Attribute name
dt: Data type (“number”, “string”, “object”)
dv: Data Validation text included data range and particular value
Non-edge Gateway device attributes
[{
"device": {
"id": "ABG515GTY912",
"tg": "gateway"
},
"attributes": [{
"ln": "Temperature",
"dt": "number",
"dv": "5 to 20, 25",
"tg": "gateway"
},
{
"ln": "gyroscope",
"dt": "object",
"tg": "gateway",
"d": [{
"ln": "x",
"dt": "number",
"dv": ",
"tg": "gateway"
},
{
"ln": "y",
"dt": "string",
"dv": "red, gray, blue",
"tg": "gateway"
},
{
"ln": "z",
"dt": "number",
"dv": "-5 to 5, 10",
"tg": "gateway"
}]
}]
},
{
"device": {
"id": "ABG515GTY912-01",
"tg": "child1"
},
"attributes": [{
"ln": "Humidity",
"dt": "number",
"dv": "5 to 20, 25",
"tg": "child1"
}
]
}]
[{
"device": {
"id": "ABG515GTY912",
"tg": "gateway"
},
"attributes": [{
"ln": "Temperature",
"dt": "number",
"dv": "5 to 20, 25",
"tg": "gateway"
},
{
"ln": "gyroscope",
"dt": "object",
"tg": "gateway",
"d": [{
"ln": "x",
"dt": "number",
"dv": ",
"tg": "gateway"
},
{
"ln": "y",
"dt": "string",
"dv": "red, gray, blue",
"tg": "gateway"
},
{
"ln": "z",
"dt": "number",
"dv": "-5 to 5, 10",
"tg": "gateway"
}]
}]
},
{
"device": {
"id": "ABG515GTY912-01",
"tg": "child1"
},
"attributes": [{
"ln": "Humidity",
"dt": "number",
"dv": "5 to 20, 25",
"tg": "child1"
}
]
}]
id: Device’s unique ID. Always, the first object of the array for the Gateway device and rest for the
Gateway’s Child device.
tg: Tag is used for the association of the device and attributes.
Edge device attributes
[{
"device": {
"id": "ddd"
},
"attributes": [{
"ln": "Temperature",
"dt": "number",
"dv": "5 to 20, 25",
"tw": "15s"
},
{
"ln": "gyroscope",
"dt": "object",
"tw": "15s",
"d": [{
"ln": "x",
"dt": "number",
"dv": ",
"tw": "15s"
},
{
"ln": "y",
"dt": "string",
"dv": "red, gray, blue",
"tw": "15s"
},
{
"ln": "z",
"dt": "number",
"dv": "-5 to 5, 10",
"tw": "15s"
}]
}]
}]
[{
"device": {
"id": "ddd"
},
"attributes": [{
"ln": "Temperature",
"dt": "number",
"dv": "5 to 20, 25",
"tw": "15s"
},
{
"ln": "gyroscope",
"dt": "object",
"tw": "15s",
"d": [{
"ln": "x",
"dt": "number",
"dv": ",
"tw": "15s"
},
{
"ln": "y",
"dt": "string",
"dv": "red, gray, blue",
"tw": "15s"
},
{
"ln": "z",
"dt": "number",
"dv": "-5 to 5, 10",
"tw": "15s"
}]
}]
}]
tw: Tumbling windows time. It indicates to send the value of attribute/sensor data by interval of
defined number of seconds.
Edge Gateway device attributes
[{
"device": {
"id": "ABG515GTY912",
"tg": "gateway"
},
"attributes": [{
"ln": "Temperature",
"dt": "number",
"dv": "5 to 20, 25",
"tg": "gateway",
"tw": "60s"
},
{
"ln": "gyroscope",
"dt": "object",
"tg": "gateway",
"tw": "90s",
"d": [{
"ln": "x",
"dt": "number",
"dv": ",
"tg": "gateway",
"tw": "90s"
},
{
"ln": "y",
"dt": "string",
"dv": "red, gray, blue",
"tg": "gateway",
"tw": "90s"
},
{
"ln": "z",
"dt": "number",
"dv": "-5 to 5, 10",
"tg": "gateway",
"tw": "90s"
}]
}]
},
{
"device": {
"id": "ABG515GTY912-01",
"tg": "child1"
},
"attributes": [{
"ln": "Humidity",
"dt": "number",
"dv": "5 to 20, 25",
"tg": "child1",
"tw": "60s"
}]
}]
[{
"device": {
"id": "ABG515GTY912",
"tg": "gateway"
},
"attributes": [{
"ln": "Temperature",
"dt": "number",
"dv": "5 to 20, 25",
"tg": "gateway",
"tw": "60s"
},
{
"ln": "gyroscope",
"dt": "object",
"tg": "gateway",
"tw": "90s",
"d": [{
"ln": "x",
"dt": "number",
"dv": ",
"tg": "gateway",
"tw": "90s"
},
{
"ln": "y",
"dt": "string",
"dv": "red, gray, blue",
"tg": "gateway",
"tw": "90s"
},
{
"ln": "z",
"dt": "number",
"dv": "-5 to 5, 10",
"tg": "gateway",
"tw": "90s"
}]
}]
},
{
"device": {
"id": "ABG515GTY912-01",
"tg": "child1"
},
"attributes": [{
"ln": "Humidity",
"dt": "number",
"dv": "5 to 20, 25",
"tg": "child1",
"tw": "60s"
}]
}]