Skip to main content

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.

Configuration​

Azure IoT Hub​

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.

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.
  • MessageSizeLimitBytes: The maximum message size in bytes. Bigger messages will be split automatically.
  • Properties: Properties added to each message to this Target.
  • 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.

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]".