IoTConnect SDK
Device Command C2D
JSON payload for users who use our SDK to recived Device commands.
{
"cpid": "<cpid>", // CPID of the device's company
"ack": False, // Acknowledgement status
"command": "Test 10", // Device command
"uniqueId": "<device id>", // Device's UniqueID
"cmdType": "0x01", // Command type constant code
"ackId": "<guid>", // Acknowledgement ID/GUID
"guid": "<guid>" // Device GUID
}
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 device offline/disconnected; Platform will wait for default 60 minutes (or configured time defined in configuration) before dropping the command.
OTA Command C2D
JSON for the OTA command Cloud to Device payload
Device and Edge Device
{
"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
{
"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
tag: It is the associated tag with the device and template (Blank for normal Device)
ver: Firmware version
– 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.
{
"cpid": "<cpid>",
"guid": "<device_guid>",
"uniqueId": "<uniqueId>",
"command": "ota <URL1>,<URL2>",
"ack": false,
"ackId": "<acknowledgement_guid>",
"cmdType": "0x02",
"urls": [
"<URL1>",
"<URL2>"
]
}
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 our SDK to recived Module commands.
{
"cpid": "<cpid>",
"guid": "<guide>",
"uniqueId": "<device id>",
"command": "module",
"ack": false,
"ackId": "5334453f-cd4d-49ac-a755-4ecf368d2732",
"cmdType": "0x03",
"urls": [{
"url": ""
}]
}
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"
}]
}]
}]
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"
}
]
}]
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"
}]
}]
}]
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 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
},
"uniqueId": "<device id>",
"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”
uniqueId: UniqueId appended to know the property for which device
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
}