Skip to content

Connecting to popular MQTT-brokers

In this section, the steps taken to establish a connection and publish data to Azure and AWS are portrayed. These steps and hints presented here would be analogous with brokers from other vendors but these were taken as illustration due to their extensive use in the industry.

Connecting to Azure Event Grid

To connect with Azure, add the broker as described in Setting up a generic MQTT broker as a synchronization destination.

Note the following hints when configuring the authentication to an Azure Event Grid broker:

  • Authentication using Thumbprint Match (Client certificate and thumbprint)
    To use this authentication method, proceed as follows:

    1. To create the thumbprint and create an Event Grid Namespace, proceed as follows:
      More information is available under Publish and subscribe to MQTT messages on Event Grid Namespace with Azure portal.

      1. Generate thumbprint.
      2. Create a namespace.
      3. Create clients.
      4. Create topic spaces.
      5. Configuring access control using permission bindings.

    2. In IIH Essentials, choose "SSL/TLS/MQTTS" as the MQTT protocol and "User credentials with client certificate" as the authentication method.

    3. Fill in the username with the username chosen when you created the client above.This value must match the value of Client Authentication Name that was specified in the authentication settings when creating the client in the Azure portal. The string to be used has been highlighted in the picture below:
      alt text
    4. Fill in the password with a dummy value, e.g., dummypassword.
    5. Upload the client certificate and client key created when generating the thumbprint above, as well as the CA certificate.
      alt text
    6. Save the data destination.

  • Authentication using Client Certificate signed by CA (Client certificate using CA certificate chain)
    For this authentication, client certificates and the parent certificate (CA Certificate) are needed. To use this authentication method, proceed as follows:

    1. To set up the Event Grid, proceed as follows:

      1. Create a namespace in "Event Grid".
      2. Enable alternative client authentication name sources and choose "Certificate Subject Name, Certificate DNS" in the "X.509" certificate section in the Event Grid's configuration.
        alt text
      3. Upload the CA certificate to the Event Grid's namespace.
        alt text

      4. Add a client (or use existing one) and configure its authentication settings in the Event Grid as follows:
        alt text alt text
      5. Create topic spaces.
      6. Configure access control using permission bindings.

    2. In IIH Essentials, choose "SSL/TLS/MQTTS" as the MQTT protocol and "Client certificate" as the authentication method.

    3. Upload the client certificate, client key and CA certificate.
      alt text
    4. Add the data destination.

Connecting to Azure IoT Hub

To communicate with Azure IoT Hub using the MQTT protocol in IIH Essentials, the method used is called "Use the MQTT protocol directly from a device". The steps portrayed in this documentation were extracted from Use the MQTT protocol directly from a device in Azure's "Communicate with an IoT hub using the MQTT protocol" article. Additional context can be found in the article.

It is possible to connect to a device in Azure IoT Hub either using a shared access signature, i.e. username and password authentication, or using X.509 certificates, i.e. client certificates. For this documentation, a shared access signature will be used. The MQTT communication will be established using MQTT via WebSockets over port 443. Other protocols can be used as well, but please note that all device communication with IoT Hub must be secured using TLS. IoT Hub doesn't support insecure MQTT connections over port 1883.

Information on how to use X.509 certificates to authenticate devices to IoT Hub can be found here: Tutorial: Create and upload certificates for testing.

Proceed as follows:

  1. Choose WebSocket Secure as the "MQTT Protocol"

  2. Fill out the "MQTT host" with the IoT Hub host name, the port number and the MQTT path.

    MQTT path for WebSockets

    The MQTT path is only needed if WebSockets based protocols are used.

  3. Use the deviceId in Azure IoT Hub for the "Client ID".
    In this example, the deviceId in Azure IoT hub is sample-device.

  4. Create and upload a configuration file for the data destination as described in Creating a configuration file. The topic to send data should be specified with the following format:

    devices/{device-id}/messages/events/

    For instance, if the deviceId in Azure IoT Hub is device-1, the topic should be specified as follows:

    devices/device-1/messages/events/

    alt text

  5. Choose "User Credentials" as the authentication method.

    1. For the "Username" field, use {iotHub-hostname}/{device-id}/?api-version=2021-04-12, where {iotHub-hostname} is the full CName of the IoT hub.

      For example, if the name of your IoT hub is contoso.azure-devices.net and if the name of your device is MyDevice01, the Username field contains:

      contoso.azure-devices.net/MyDevice01/?api-version=2021-04-12

      To avoid unexpected behavior, include api-version in the field.

    2. For the "Password field", use a SAS token. The following snippet shows the format of the SAS token:

      SharedAccessSignature sig={signature-string}&se={expiry}&sr={URL-encoded-resourceURI}

      More information

      For more information about how to generate SAS tokens, see the Use SAS tokens as a device section of Control access to IoT Hub using Shared Access Signatures.

      It is also possible to use the Azure IoT Hub extension for Visual Studio Code or the CLI extension command az iot hub generate-sas-token to generate a SAS token. The following would be an example of the SAS token that would need to be copied as "MQTT password" in IIH Essentials:

      SharedAccessSignature sr={iotHub-hostname}%2Fdevices%2FMyDevice01%2Fapi-version%3D2016-11-14&sig=vSgHBMUG.....Ntg%3d&se=1456481802

  6. Choose the options under "Advanced Settings" according to your Azure IoT Hub setting.

    alt text

  7. Add the data destination.

Connecting to AWS IoT Core

To connect to AWS IoT Core using MQTT, add the broker as described in Setting up a generic MQTT broker as a synchronization destination.

The hints listed here refer to a sample data synchronization using the "Authentication with Client Certificates" in AWS IoT Core.

  1. To set up AWS IoT Core for MQTT, proceed as follows:

    1. Create a Thing (device) under "AWS IoT -> Manage -> Things -> Create Things"

      1. Provide a name for the device.
        alt text
      2. If no client certificates have been created, configure the certificate using "Auto-generate a new certificate".
        alt text
      3. Use default policies.
        alt text
      4. Download the client certificate, private key file and CA certificate 1 (RSA 2048 bit).
        alt text alt text

    2. Get the device endpoint under "IoT Core -> Settings". The "Domain Name" is needed for adding the broker in IIH Essentials.
      alt text

  2. In IIH Essentials, write a name for the broker.

  3. Choose "SSL/TLS/MQTTS" as the MQTT protocol.
  4. Copy the "Domain Name" from above as the MQTT host and enter 8883 as the MQTT port.
    alt text
  5. Choose "Client certificate" as the authentication method.
  6. Upload the client certificate, client key and CA certificate. Rename the format of the files if needed.
    alt text
  7. Fill in the other required fields.
  8. Add the data destination.

Troubleshooting

Info

The circumstances described here may also apply to brokers from other vendors.

  • Issue: After configuring the broker, the status message "No connection to the Generic MQTT Broker" is shown.
    alt text
    Solution: To remove sources of uncertainty, delete, if possible, all attributes, assets or aspects from the hierarchy. If the connection fails only after an element has been added to the hierarchy, check the next question in this section. If the connection cannot be established to the broker even if no element has been added to the hierarchy, the issue might be related to the configuration of the broker parameters or authentication. A wrong configuration of the following parameters will not allow a successful connection to the broker:

    • MQTT Protocol
      This defines the protocol to be used when establishing the broker connection. Check that the right protocol is chosen for establishing the connection. More information can be found in Setting up a generic MQTT broker as a synchronization destination.

    • MQTT Host
      Write the host name without any protocol, colon or port number. The protocol, colon and port number will be added internally. For instance, to synchronize data to: ssl://b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com:61617, the following values should be chosen:

      • MQTT Protocol: SSL/TLS/MQTTS
      • MQTT Host: b-1234a5b6-78cd-901e-2fgh-3i45j6k178l9-1.mq.us-east-2.amazonaws.com
      • MQTT Port: 61617

    • MQTT Port
      Make sure to only write the port number here, without any colon or slash. Open this port in the proxy settings of the Industrial Edge Device or firewall to allow communication to the MQTT broker.

    • MQTT Authentication Method
      If the wrong credentials or certificates are uploaded to IIH Essentials a connection will not be established to the broker. Please make sure that the correct credentials and/or certificates are used, in case they are needed.

  • Issue: The connection to the broker was successfully established but it disconnected as soon as an attribute, asset or aspect has been added to the hierarchy.
    alt text Solution: If the connection fails after an element has been added to the hierarchy, it means that the issue is related to the outgoing data rather than to the authentication or MQTT protocol. In this case it, double-check if the broker has any specific requirements or limitations for receiving payloads. The following parameters could terminate the connection, if not configured as allowed by the broker:

    • Retained flag
      Some brokers might not allow sent messages to be retained. Make sure that the broker allows for receiving messages with a retained flag before activating it.
    • Maximum MQTT packages per second
      The broker might limit the amount of packages that can be received within a second to avoid a system overload. Check this value before configuring the synchronization.
    • Maximum MQTT package size
      If not correctly configured, IIH Essentials might create MQTT packages larger than those allowed by the broker. If a smaller package size is chosen, data is not thrown away but split into smaller packages.
    • QoS (Quality of service)
      Check if the chosen QoS when configuring the data destination is allowed in the MQTT broker.
    • Message publishing interval
      The broker might limit the frequency at which packages can be published to avoid a system overload. Check this value before configuring the synchronization.

  • Issue: The connection to the broker was successfully established, it remains connected when an attribute, asset or aspect has been added to the hierarchy but cannot see any incoming data in the MQTT broker.
    alt text Solution: If no error is being shown but still no data is being received in the broker, check the following:

    • Hierarchy has at least one attribute
      To start receiving data, at least one attribute must be included as part of the hierarchy to be synchronized. Assets and aspects cannot hold data on their own, they can hold attributes where the data can be stored.

    • Attribute has data
      After making sure that the hierarchy contains at least one attribute, check if the attribute has already been mapped to receive and store data.

      • If the aim is synchronizing new incoming data, make sure that the attribute is receiving data, this can be for instance checked in the IIH Essentials UI with the value tab:
        alt text

        Live value of an attribute

      • If the aim is synchronizing historic data only, also make sure that the data of the attribute has a time stamp later than the start time of the synchronization. As an illustration, if an attribute has data from 2025-01-01 at 13:52:20.000 until 2025-01-22 at 01:01:30.000, and the start date for the synchronization is 2025-01-22 at 11:03:34.000 or any time in the future, no data will be sent out to the broker because the start date of the synchronization is outside of the range where the attribute has data.

    • Topic in configuration file is correct
      Make sure that the topic is configured as expected. If the path or attribute name has spaces, these will be removed from the topic. See Creating a configuration file for more details on how to define the topic in the configuration file. For troubleshooting, a simple topic can be configured in the configuration file to remove sources of uncertainty and check if data arrives to the test topic, for instance: "topic": "testTopic".