/IOTCONNECT™ Message Protocol 2.1 is the current standard for device communication. It provides enhanced device identity messages, child device management, improved acknowledgments, and comprehensive reference tables for building custom SDKs.
/IOTCONNECT™ platform provides SDKs for different languages and platforms; however, These SDKs may not be suitable for your device due to memory or hardware limitations.
/IOTCONNECT™ provides you the ability to build your own SDKs using the same protocol that /IOTCONNECT™ SDKs use internally. Protocol 2.1 is the recommended version for all new integrations.
To start the process, call the Discovery API by passing parameters to fetch the Identity Endpoint. You need: CPID or SID, supported language, version, and environment. You can find your discovery URL in Settings > Key Vault on the portal.
On successful Discovery call, you receive the URL of the Identity API. This API provides additional values required to establish the device connection, send telemetry data, and manage device lifecycle.
To retrieve detailed information on attributes, settings / shadow, rules, and more, the device sends JSON with a specific message type:
View Device Identity Messages Details →
Get Device Hello Message: Initial handshake to register the device session and retrieve protocol information.
Get Template Attributes: Retrieve the full attribute schema defined in the device template.
Get Template Settings / Shadow: Retrieve desired property values (device twin) from the cloud.
Get Edge Rule: Retrieve rule definitions for local edge evaluation.
Get Child Devices: Retrieve list of child devices associated with this gateway device.
Get Pending OTAs: Check for queued firmware updates awaiting delivery.
Get Pending Commands: Check for queued commands awaiting delivery.
Create Child Device: Dynamically register a new child device under this gateway.
Delete Child Device: Remove a child device from this gateway.
D2C message data structures for Protocol 2.1:
View D2C Message Specifications →
Device Telemetry: Sensor data payload with attribute values, device ID, and timestamp.
OTA Acknowledgement: Firmware update status reporting (download, install, success, failure).
Device Command Acknowledgement: Command execution confirmation with status code.
Module Command Acknowledgement: Module-specific command execution confirmation.
Shadow Update Property: Device reports updated property values to synchronize with cloud twin.
C2D message data structures received by the device:
View C2D Message Specifications →
Device Command: Remote command with text payload, optional parameters, and acknowledgment ID.
OTA Command: Firmware update notification with download URL and version metadata.
Module Command: Command targeting a specific software module on the device.
Other Commands: Template change, rule change, device change, password change, hard stop notifications.
Troubleshooting and response codes for Protocol 2.1:
Message Types: Enumeration of all supported message type identifiers (mt values).
Error Codes: Hello Message errors, Create / Delete Child Device errors, REST API errors.
Auth Types: Authentication type codes (X.509, Symmetric Key, TPM, etc.).
Supported Data Types: INTEGER, LONG, DECIMAL, STRING, BIT, BOOLEAN, DATE, DATETIME, LATLONG, OBJECT, ARRAY.
Acknowledgement Status: Command acknowledgment codes (success, failed, executed) and OTA status codes.
Edge Device: Tumbling Window Time configurations and Data Validation rules for edge processing.
Protocol 2.1 is the recommended version for all new device integrations. It includes Device Identity Messages for dynamic child device management, improved acknowledgment handling, and comprehensive error reporting.
When receiving C2D messages via MQTT, ensure messages are acknowledged at QoS 1 level. Otherwise, the device may receive duplicate messages after reconnection.
