Azure IoT hub

Description

ezvpn-mqtt-azureiothub listens on an MQTT broker and writes data to Azure IoT hub Service.

In IOhubTM architecture, ezvpn-mqtt-azureiothub will subscribe fld/+/r/# topic to the ezvpn-mqtt broker and send data read to Azure IoT hub .

Azure IoT hub schema

How to use it

ezvpn-mqtt-azureiothub is a Docker container image pre-configured for communication with ezvpn-mqtt and Azure IoT hub. In order to use it, you first need an Azure account with IoT hub Service enabled. Then you need to install ezvpn-mqtt with a Field container and configure ezvpn-mqtt-azureiothub with Azure IoT hub primary connection string for authentication and required data. All data read from the field will be sent in Azure IoT hub service automatically.

To create a primary connection string, you need to have an account on Azure and create an IoT device. Click this link to create an account if you don't have it already or to sign in.

Create an IoT hub, you can follow the official Microsoft documentation here.

Now simply add an IoT device from the Azure web interface or by using the Azure CLI.

Using the Azure web interface, click to copy the Primary Connection String to use in the IOT_CONNECTION_STRING environment variable.

Primary Connection String

To retrieve the Primary Connection String by Azure CLI you can use this command az iot hub device-identity connection-string show --hub-name {YourIoTHubName} --device-id {MyNodeDevice} --output table.

Metadata

You can send metadata embedded either in the message body or in the Azure message properties (or both).

Embedded Metadata

Using the METADATA variable, its value (as a string) is sent to the Azure IoT service embedded in the JSON payload:

In the example below, METADATA value is

{
    "company": "ACME",
    "machine_name": "cutter 23",
    "serial_number": "1234567890"
}

and the metadata company, machine_name, and serial_number will be sent to Azure, this is the final result:

{
    "protocol": "modbus",
    "measurement": "temp1",
    "value": 1240,
    "ts": 1602887221913,
    "metadata": {
        "company": "ACME",
        "machine_name": "cutter 23",
        "serial_number": "1234567890"
    }
}

Metadata in Message Header

If SEND_METADATA_IN_PROPS is true, it is possible to add some metadata to the message header properties. The message properties are a set of key/value pairs. You can add your custom metadata information in a specific property using METADATA_KEY and METADATA_VALUE.

Buffer and Batch mode

You can enable buffer using MQTT_WANT_QOS2 and RETRY_ON_ERROR environment variables.

The messages are sent to Azure server individually. If you have a lot of messages to send or you need to optimize traffic and costs you can group them using BATCH_SIZE functionality. If the value is > 1 then messages are sent as an array of messages.

Environment variables

When you start the Azure IoT container, you can adjust the instance's configuration by passing one or more environment variables to the docker run command.

MQTT connection

  • MQTT_HOST: MQTT host. Defaults to 127.0.0.1
  • MQTT_PORT: MQTT port. Defaults to 1883
  • MQTT_IN_TOPIC: IOhubTM MQTT topic to subscribe (e.g. fld/modbus/r/#). Defaults to fld/+/r/#. Subscribe to multiple topics can be obtained defining each topic on a separated line.
  • MQTT_WANT_QOS2: ask MQTT to upgrade each incoming message on MQTT_IN_TOPIC to QoS 2 (delivery guaranteed). MQTT will honor the request only if persistence is enabled.

IoT hub Connection

  • IOT_CONNECTION_STRING: IoT hub Connection string. Must be provided.

Retry on error

  • RETRY_ON_ERROR: if true, on Azure communication failure, IoT hub write is retried every RETRY_INTERVAL milliseconds, forever. Otherwise the message is discarded. Defaults to false.
  • RETRY_INTERVAL: interval in milliseconds between each write retry to Azure IoT hub. Defaults to 5000. Used only if RETRY_ON_ERROR is true.

Batch Send

  • BATCH_SIZE: If set to a value > 1, messages are sent as an array of messages. Defaults to 0.

Embedded Metadata

  • METADATA: JSON payload. if present, it is added to the standard payload sent to MQTT under the field metadata. Can be any valid JSON type (number, string, boolean, object, array, ...)
  • SEND_METADATA_IN_PROPS: If true, additional metadata in key/value pair is added to IoT hub Message properties using METADATA_KEY and METADATA_VALUE. Default to false.
  • METADATA_KEY: Additional metadata for Message.
  • METADATA_VALUE: Additional metadata value for Message.

Other variables

  • SKIP_RETAIN: if true, discard all MQTT messages with retain flag set to true. Defaults to false.

With SKIP_RETAIN set to false, each client that subscribes to a topic pattern receives the retained message immediately after they subscribe.

The broker stores only one retained message per topic.

Docker container details

Image: us-central1-docker.pkg.dev/ez-shared/iohub/iohub-mqtt-azureiothub

Supported architecture: amd64

Changelog

v1.0.0
  • First Release