Device Identity Messages

To retrieve more information on attributes, settings/shadow, rules, etc device must send JSON with a specific message type.

Message Type	Description
200	Get Device Hello message
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 Pending OTA(s)
206	Get Pending Command(s)
209	Get Pending OTA(s) & Command(s)
221	Create Child Device
222	Delete Child Device

Get Device Hello message

Once you get connected to IoTConnect must send hello message first to get its device identity at IoTConnect along with the metadata, Device ability information and protocol information.

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

Request:
{
    "mt": 200
}

Response:
{
    "d": {
        "ec": 0,
        "ct": 200,
        "meta": {
            "at": 1,
            "df": 60,
            "cd": "Unique code with 7 or 8 characters",
            "edge": 0,
            "pf": "aws|az",
            "hwv": "Hardware version of the firmware pushed by OTA",
            "swv": "Software version of the firmware pushed by OTA",
            "v": 2.1
        },
        "has": {
            "d": 1,
            "attr": 1,
            "set": 1,
            "r": 0,
            "ota": 0
        },

        "p": {
            "n": "mqtt",
            "h": "A string represents the mqtt host name to connect",
            "p": 8883,
            "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": {
                "rpt": "A string represents the publish topic of 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",
                "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",
            }
        },
        "dt": "YYYY-MM-DDTHH:MM:SS.SSSZ"
    },
    "status": 200,
    "message": "Device info loaded successfully."
}
** "ec": error code, possible Values 0, 1, 2, 3, 4, 5, 6.
** "meta.edge": if 1 then device is Edge Device; else 0
** "meta.v": Message Protocol Version, possible values 1.0, 2.0, 2.1
** "has.d": if 1 then device has child device, device must send 204 message to get all child devices; else 0
** "has.attr": if 1 then device has attributes, device must send 201 message to get all attribute details; else 0
** "has.set": if 1 then device has setting, device must send 202 message to get updates on settings; else 0
** "has.r": if 1 then its edge device, device must send 203 message to get all rules; else 0
** "has.ota": if 1 then device has pending update, device must send 205 message to get pending OTA; else 0

Request:
{
    "mt": 200
}

Response:
{
    "d": {
        "ec": 0,
        "ct": 200,
        "meta": {
            "at": 1,
            "df": 60,
            "cd": "Unique code with 7 or 8 characters",
            "gtw": {
                "tg": "String represents the gateway Tag",
                "g": "GUID represents the device GUID",
            },
            "edge": 0,
            "pf": "aws|az",
            "hwv": "Hardware version of the firmware pushed by OTA",
            "swv": "Software version of the firmware pushed by OTA Device software version",
            "v": 2.1
        },
        "has": {
            "d": 1,
            "attr": 1,
            "set": 1,
            "r": 0,
            "ota": 0
        },

        "p": {
            "n": "mqtt",
            "h": "A string represents the mqtt host name to connect",
            "p": 8883,
            "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": {
                "rpt": "A string represents the publish topic of 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",
                "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",
            }
        },
        "dt": "YYYY-MM-DDTHH:MM:SS.SSSZ"
    },
    "status": 200,
    "message": "Device info loaded successfully."
}

** "ec": error code, possible Values 0, 1, 2, 3, 4, 5, 6
** "meta.edge": if 1 then device is Edge Device; else 0
** "meta.v": Message Protocol Version, possible values 1.0, 2.0, 2.1
** "has.d": if 1 then device has child device, device must send 204 message to get all child devices; else 0
** "has.attr": if 1 then device has attributes, device must send 201 message to get all attribute details; else 0
** "has.set": if 1 then device has setting, device must send 202 message to get updates on settings; else 0
** "has.r": if 1 then its edge device, device must send 203 message to get all rules; else 0
** "has.ota": if 1 then device has pending update, device must send 205 message to get pending OTA; else 0

Click here for more details on values of ec tag

Get Device Attributes

Send MQTT message having below JSON. Without this information, the platform will discard the message!!

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

Request:
{
    "mt": 201
}

Response:
{
    "d": {
        "att": [{
                "p": "Parent attribute name (empty – this is a top-level attribute, not nested in an object)",
                "dt": 1,
                "d": [{
                        "ln": "Local name of attribute (attribute name)",
                        "dt": 0,
                        "dv": "Data validation – If applied",
                        "sq": 1,
                        "tw": "Tumbling window time",
                    }
                ]
            }
        ],
        "ct": 201,
        "ec": 0
    }
}
** "dt": Data type of attribute, click here for reference
** "tw": Tumbling window time, click here for reference
** "ec": if 0 then no error; 1 for error

Request:
{
    "mt": 201
}

Response:
{
    "d": {
        "att": [{
                "p": "Parent attribute name (empty – this is a top-level attribute, not nested in an object)",
                "dt": 1,
                "tg": "Tag of parent/child device",
                "d": [{
                        "tg": "Tag of parent/child device",
                        "ln": "Local name of attribute (attribute name)",
                        "dt": 0,
                        "dv": "Data validation – If applied",
                        "sq": 1,
                        "tw": "Tumbling window time",
                    }
                ]
            }
        ],
        "ct": 201,
        "ec": 0
    }
}
** "dt": Data type of attribute
** "tw": Tumbling window time
** "ec": if 0 then no error; 1 for error

Get Device Settings (shadow)

Send MQTT message having below JSON. Without this information, the platform will discard the message!!

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

Request:
{
    "mt": 202
}

Response:
{
    "d": {
        "set": [{
                "ln": "Local name of setting",
                "dt": 0
                "dv": "Data validation"
            }
        ],
        "ct": 202,
        "ec": 0
    }
}
** "ec": if 0 then no error; 1 for error

Click here for more details on values of dt tag
Click here for more details on values of tw tag
Click here for more details on values of dv tag

Get Edge Rule

This message works for Edge Gateway only. For Edge Gateway, it’s required to have all
rules defined in the portal to do an evaluation before sending a message. To get all rules defined on the device template, Send
MQTT message having below JSON. 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

Request:
{
    "mt": 203
}

Response:
{
    "d": {
        "r": [{
                "g": "A string represents rule guid",
                "es": "A string represents event subscription guid",
                "con": "A string represents the rule condition.",
                "cmd": "A string represents command which needs to execute on device if rule matched",
            }
        ],
        "ct": 203,
        "ec": 0
    }
}
** "ec": if 0 then no error; 1 for 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 the gateway.

Get child devices

This message works only for Gateway Devices. For Gateway Device, it’s required to have a list of child
devices that have been added to the portal. To get child’s device. Send MQTT message having below JSON. Without this information, the platform will discard the message!!

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

Request:
{
    "mt": 204
}

Response:
{
    "d": {
        "d": [{
                "tg": "Tag of child device",
                "id": "Uniqueid of child device",
            }
        ],
        "ct": 204,
        "ec": 0
    }
}
** "ec": if 0 then no error; 1 for error

Get Pending OTA(s)

To get pending OTA message to device, send MQTT message having below JSON request. Without this information, the platform will discard the message!!

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

Request:
{
    "mt": 205
}

Response:
//If there is no any pending OTA available.
{
	"ct": 205,
	"ec": 0,
	"dt": "2024-10-04T13:21:13.5085569Z"
}

//If pending OTA available.
{
	"ct": 1,
	"v": 2.1,
	"cmd": "ota",
	"ack": "A string represents guid of acknowledgement",
	"sw": "1.0.0",
	"hw": "1.0.0",
	"urls": [
		{
			"url": "A string represents downloadable url of OTA",
			"fileName": "A string represents name of the OTA file with extension"
		}
	]
}
** "cmd": command text, default is ota, can be changed from template

Request:
{
    "mt": 205
}

Response:
//If there is no any pending OTA available.
{
	"ct": 205,
	"ec": 0,
	"dt": "2024-10-04T13:21:13.5085569Z"
}

//If pending OTA available.
{
	"ct": 1,
	"v": 2.1,
	"cmd": "ota",
	"ack": "A string represents guid of acknowledgement",
	"sw": "1.0.0",
	"hw": "1.0.0",
	"urls": [
		{
			"url": "A string represents downloadable url of OTA",
			"fileName": "A string represents name of the OTA file with extension",
			"tg": "A string represents tag of device"
		}
	]
}
** "cmd": command text, default is ota, can be changed from template

Get Pending Command(s)

To get pending command to device, send MQTT message having below JSON request. Without this information, the platform will discard the message!!

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

Request:
{
    "mt": 206
}

Response:
//If there is no any pending command available.
{
	"ct": 206,
	"ec": 0,
	"dt": "2024-10-04T13:21:13.5085569Z"
}

//If pending command available.
{
	"ct": 0,
	"v": 2.1,
	"cmd": "A string represents the command text",
	"ack": "A string represents guid of acknowledgement"
}
** "ack": is optional, required when command has acknowledgement

Request:
{
    "mt": 206
}

Response:
//If there is no any pending command available.
{
	"ct": 206,
	"ec": 0,
	"dt": "2024-10-04T13:21:13.5085569Z"
}

//If pending command available.
{
	"ct": 0,
	"v": 2.1,
	"cmd": "A string represents the command text",
	"id": "A string represents child device UniqueID",
	"ack": "A string represents guid of acknowledgement"
}
** "ack": is optional, required when command has acknowledgement
** "id": it will be added when the command is for child device only.

Get Pending OTA(s) & Command(s)

To get pending OTA & Command message to device using single request, send MQTT message having below JSON request. Without this information, the platform will discard the message!!

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

Request:
{
    "mt": 209
}

Response:
//If there is no any pending OTA available.
{
	"ct": 205,
	"ec": 0,
	"dt": "2024-10-04T13:21:13.5085569Z"
}

//If pending OTA available.
{
	"ct": 1,
	"v": 2.1,
	"cmd": "ota",
	"ack": "A string represents guid of acknowledgement",
	"sw": "1.0.0",
	"hw": "1.0.0",
	"urls": [
		{
			"url": "A string represents downloadable url of OTA",
			"fileName": "A string represents name of the OTA file with extension"
		}
	]
}
** "cmd": command text, default is ota, can be changed from template

//If there is no any pending command available.
{
	"ct": 206,
	"ec": 0,
	"dt": "2024-10-04T13:21:13.5085569Z"
}

//If pending command available.
{
	"ct": 0,
	"v": 2.1,
	"cmd": "A string represents the command text",
	"ack": "A string represents guid of acknowledgement"
}
** "ack": is optional, required when command has acknowledgement

Request:
{
    "mt": 209
}

Response:
//If there is no any pending OTA available.
{
	"ct": 205,
	"ec": 0,
	"dt": "2024-10-04T13:21:13.5085569Z"
}

//If pending OTA available.
{
	"ct": 1,
	"v": 2.1,
	"cmd": "ota",
	"ack": "A string represents guid of acknowledgement",
	"sw": "1.0.0",
	"hw": "1.0.0",
	"urls": [
		{
			"url": "A string represents downloadable url of OTA",
			"fileName": "A string represents name of the OTA file with extension",
			"tg": "A string represents tag of device"
		}
	]
}
** "cmd": command text, default is ota, can be changed from template

//If there is no any pending command available.
{
	"ct": 206,
	"ec": 0,
	"dt": "2024-10-04T13:21:13.5085569Z"
}

//If pending command available.
{
	"ct": 0,
	"v": 2.1,
	"cmd": "A string represents the command text",
	"id": "A string represents child device UniqueID",
	"ack": "A string represents guid of acknowledgement"
}
** "ack": is optional, required when command has acknowledgement
** "id": it will be added when the command is for child device only.

Create Child Device

Send below JSON message with property di = 1 needs to be sent from the device to create a child device.

Request:
{
    "mt": 221,
    "d": {
        "g": "A string represents gateway device GUID",
        "dn": "A string represents the child device display name",
        "id": "A string represents the child device unique id",
        "tg": "A string represents the tag of child device"
    }
}

Response:
{
    "d": {
        "ec": 0,
        "ct": 221,
    }
}
** "ec": Possible Values 0, 1, 2, 3, 4, 5, 6, 7, 8, 9

Click here for more details on values of ec tag

Delete Child Device

Send below JSON message with property di = 1 needs to be sent from the device to delete the child device. Without this information, the platform will discard the message!!

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

Request:
{
    "mt": 222,
    "d": {
        "id": "A string represents device unique id"
    }
}

Response:
{
    "d": {
        "ec": 0,
        "ct": 222,
    }
}
** "ec": Possible Values 0, 1