Create and read IoT Hub messages

To support seamless interoperability across protocols, IoT Hub defines a common message format for all device-facing protocols. This message format is used for both device-to-cloud routing and cloud-to-device messages.

Note

Some of the features mentioned in this article, like cloud-to-device messaging, device twins, and device management, are only available in the standard tier of IoT Hub. For more information about the basic and standard IoT Hub tiers, see How to choose the right IoT Hub tier.

IoT Hub implements device-to-cloud messaging using a streaming messaging pattern. IoT Hub's device-to-cloud messages are more like Event Hubs events than Service Bus messages in that there is a high volume of events passing through the service that can be read by multiple readers.

An IoT Hub message consists of:

  • A predetermined set of system properties as listed below.

  • A set of application properties. A dictionary of string properties that the application can define and access, without needing to deserialize the message body. IoT Hub never modifies these properties.

  • An opaque binary body.

Property names and values can only contain ASCII alphanumeric characters, plus {'!', '#', '$', '%, '&', ''', '*', '+', '-', '.', '^', '_', '`', '|', '~'} when you send device-to-cloud messages using the HTTPS protocol or send cloud-to-device messages.

Device-to-cloud messaging with IoT Hub has the following characteristics:

  • Device-to-cloud messages are durable and retained in an IoT hub's default messages/events endpoint for up to seven days.

  • Device-to-cloud messages can be at most 256 KB, and can be grouped in batches to optimize sends. Batches can be at most 256 KB.

  • IoT Hub does not allow arbitrary partitioning. Device-to-cloud messages are partitioned based on their originating deviceId.

  • As explained in Control access to IoT Hub, IoT Hub enables per-device authentication and access control.

  • You can stamp messages with information that goes into the application properties. For more information, please see message enrichments.

For more information about how to encode and decode messages sent using different protocols, see Azure IoT SDKs.

System Properties of D2C IoT Hub messages

Property Description User Settable? Keyword for
routing query
message-id A user-settable identifier for the message used for request-reply patterns. Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. Yes messageId
iothub-enqueuedtime Date and time the Device-to-Cloud message was received by IoT Hub. No enqueuedTime
user-id An ID used to specify the origin of messages. When messages are generated by IoT Hub, it is set to {iot hub name}. Yes userId
iothub-connection-device-id An ID set by IoT Hub on device-to-cloud messages. It contains the deviceId of the device that sent the message. No connectionDeviceId
iothub-connection-module-id An ID set by IoT Hub on device-to-cloud messages. It contains the moduleId of the device that sent the message. No connectionModuleId
iothub-connection-auth-generation-id An ID set by IoT Hub on device-to-cloud messages. It contains the connectionDeviceGenerationId (as per Device identity properties) of the device that sent the message. No connectionDeviceGenerationId
iothub-connection-auth-method An authentication method set by IoT Hub on device-to-cloud messages. This property contains information about the authentication method used to authenticate the device sending the message. No connectionAuthMethod

System Properties of C2D IoT Hub messages

Property Description User Settable?
message-id A user-settable identifier for the message used for request-reply patterns. Format: A case-sensitive string (up to 128 characters long) of ASCII 7-bit alphanumeric characters + {'-', ':', '.', '+', '%', '_', '#', '*', '?', '!', '(', ')', ',', '=', '@', ';', '$', '''}. Yes
sequence-number A number (unique per device-queue) assigned by IoT Hub to each cloud-to-device message. No
to A destination specified in Cloud-to-Device messages. No
absolute-expiry-time Date and time of message expiration. No
correlation-id A string property in a response message that typically contains the MessageId of the request, in request-reply patterns. Yes
user-id An ID used to specify the origin of messages. When messages are generated by IoT Hub, it is set to {iot hub name}. Yes
iothub-ack A feedback message generator. This property is used in cloud-to-device messages to request IoT Hub to generate feedback messages as a result of the consumption of the message by the device. Possible values: none (default): no feedback message is generated, positive: receive a feedback message if the message was completed, negative: receive a feedback message if the message expired (or maximum delivery count was reached) without being completed by the device, or full: both positive and negative. Yes

Message size

IoT Hub measures message size in a protocol-agnostic way, considering only the actual payload. The size in bytes is calculated as the sum of the following values:

  • The body size in bytes.
  • The size in bytes of all the values of the message system properties.
  • The size in bytes of all user property names and values.

Property names and values are limited to ASCII characters, so the length of the strings equals the size in bytes.

Anti-spoofing properties

To avoid device spoofing in device-to-cloud messages, IoT Hub stamps all messages with the following properties:

  • iothub-connection-device-id
  • iothub-connection-auth-generation-id
  • iothub-connection-auth-method

The first two contain the deviceId and generationId of the originating device, as per Device identity properties.

The iothub-connection-auth-method property contains a JSON serialized object, with the following properties:

{
  "scope": "{ hub | device }",
  "type": "{ symkey | sas | x509 }",
  "issuer": "iothub"
}

Next steps