Skip to main content
Version: 1.7.0

Azure IoT Hub

The Microsoft Azure IoT Hub is an IoT Platform to manage Edge devices and process data streams. The hopit Edge Azure Target features Data streaming, Namespace discovery, Device Twin synchronization and remote Tasks execution.

For further information visit the IoT Hub documentation.

info

With the hopit Provisioning service, an automatic device provisioning of Azure devices is possible.

tip

To connect an Edge device to the hopit Portal, use the CONNECT TO HOPIT PORTAL button on the Targets page instead of configuring this Target by hand. It sets up the Target, the license and an optional monitoring Route from a single connection string. See the Connect to hopit Portal how-to guide.

Configuration​

Azure IoT Hub​

The Target connects in one of two ways, selected with the Connection Type field:

  • Connection String: a new device must be created on the IoT Hub and either the Primary Connection String, the Secondary Connection String or a generated SAS Token Connection String must be known.
  • DPS: the device registers itself through the Device Provisioning Service, which assigns it to an IoT Hub. Only the ID scope and the symmetric key of the enrollment are needed; the hub is discovered automatically. This is how a device connects to the hopit Portal.
info

To generate SAS Token Connection Strings, the Azure-IoT-Explorer can be used.

hopit Edge​

The Azure Target has the following parameters:

  • DeviceConnectionString: Either the Primary Connection String, the Secondary Connection String or a generated SAS Token Connection String.
  • DeviceConnectionStringRotate: Can be used to renew the SAS Token. See the SAS Token Update section for details.
  • DpsIdScope: The ID scope of the Device Provisioning Service. Used instead of a DeviceConnectionString.
  • DpsSymmetricKey: The symmetric key of the device's DPS enrollment. The device registers under its own Device ID.
  • ModelId: Optional IoT Plug and Play model ID announced during registration.
  • SanitizeReportedSecrets: Removes settings marked as secret before reporting the Device Twin. Defaults to true. See Device Twin secret sanitization.
  • MessageSizeLimitBytes: The maximum message size in bytes. Bigger messages will be split automatically.
  • Properties: Properties added to each message to this Target.
  • QoS: Delivery guarantee for the Mqtt transport types: AtMostOnce or AtLeastOnce.
  • EnableChunking: Collects signals into a single larger message instead of sending one message per scrape. Only available for the Amqp transport types. See Chunking.
  • ChunkSize: The size in kB a chunk is filled up to before it is sent.
  • ChunkTimeout: The maximum time a chunk is collected before it is sent even though it is not full. Format hh:mm:ss.
  • TransportType: The transport protocol.
    • Amqp
    • Mqtt
    • Http1: Direct methods are not supported with this transport type.
    • Amqp_WebSocket_Only
    • Amqp_Tcp_Only
    • Mqtt_WebSocket_Only
    • Mqtt_Tcp_Only
  • TargetType: The type is always Azure for this Target.

For the common parameters, see the Introduction.

Corresponding Edge configuration and Device Twin definition to activate the Azure Target service:
https://localhost:5050/Targets
Azure Target Settings

Data Streaming​

Signals and properties will be sent to the IoT Hub as a JSON message:

A sample message could be

{
  "body": {
    "signal-1": "value-1",
    "signal-2": "value-2"
  },
  "properties": {
    "property-1": "property-value-1",
    "property-2": "property-value-2"
  }
}

Big messages will be split into two or more messages if the MessageSizeLimitBytes parameter is exceeded.

Signals can be also read with Regex matcher. See the Router documentation for details.

Signal discovery is available for this Target. See the Introduction for more details.

For information how signals are named and labeled in Data Lakes, please read the Data Lake documentation.

Chunking​

The Azure IoT Hub does not bill the number of bytes sent, but the number of message blocks: every message counts as at least one block, and a large message counts as several. Sending many small messages is therefore far more expensive than sending the same data in fewer, larger ones.

With EnableChunking, the Target collects the messages of all its Routes into one chunk instead of sending each scrape on its own. The chunk is sent when either

  • it has been filled up to ChunkSize kilobytes, or
  • the oldest message in it reaches ChunkTimeout.

A single message larger than ChunkSize is sent on its own. Setting ChunkTimeout to 00:00:00 disables the timeout, so chunks are only sent once they are full.

Chunking trades latency for cost: a signal may sit in the chunk for up to ChunkTimeout before it leaves the device. Choose the timeout to match how fresh the data has to be at the other end. Each message keeps its own timestamp, so no measurement time is lost by chunking.

Chunking is only available for the Amqp transport types, because the AMQP frame size allows for much larger messages than MQTT.

info

An individual Route can be excluded from chunking with the SkipChunking parameter of its Destination. Its messages are then sent immediately while every other Route of the Target is still chunked. Use this for signals that trigger an action on the other side and cannot wait.

Device Twin​

The Azure Device Twin is split into two sections: desired and reported. All changes made on the Edge device, will be send to the reported section of the Device Twin. To change a settings on the Edge device from the IoT Hub, edit the desired section.

To enable Device Twin synchronization, the Target must be enabled in the Device Twin settings. The Device Twin documentation also contains more information how to use it.

info

Since the Azure IoT Hub does not support some special characters in the property names, they are replaced by the Device Twin service on the Edge:

  • . -> >
  • $ -> §
  • # -> |
  • (white space) -> ~

To remove properties from the desired section, set it to null.

Target or Route deletion​

To delete a Target or a Route via the Device Twin, it has to be set to null.

caution

To delete a Target or a Route via the Azure IoT Hub Device Twin, it must be available in the desired section before setting it to null. Otherwise this null property will not be sent to the Edge device. This is the standard behaviour of the Azure IoT Hub.

SAS Token Update​

SAS Tokens are always generated for a period of time and must be replaced before expiring. To automate this task, the DeviceConnectionStringRotate parameter can be used.

If this is set to a new SAS Token Connection String, the Target will try to connect with the new SAS Token. If it connects successfully to the IoT Hub, it copies the new Token to the DeviceConnectionString property and sets the DeviceConnectionStringRotate property to null. If the connection fails with the new Token, it rotates back to the old SAS Token.

Tasks​

To remotely execute Tasks on the Edge device, the Direct Method feature is used. To trigger a Task execution, invoke a method with the Task name as Method name and add the Arguments as Payload.

Please read the Tasks documentation for more information about Tasks.

Start Discovery Task​

The StartDiscovery Task can only be executed from a remote target. See the Tasks documentation for details.

The namespace is sent back as telemetry messages with the discovered signals in the body and with the Properties "type": "configuration" and "target": "[Target Name]".