MindConnect MQTT Broker - Developer Documentation
Skip to content

MindConnect MQTT Broker

Overview

MindConnect MQTT Broker authenticates the MQTT agents over TLS to publish and subscribe messages adhering to MQTT protocol. It is an alternative to the HTTP-based MindConnect Service.

The following port-protocol-authentication combination is supported by MindConnect MQTT Broker:

EU1

Protocol Authentication TCP Port ALPN protocol
MQTT Client Certificate 8883 N/A
MQTT Client Certificate 4431 x-amzn-mqtt-ca

EU2

Protocol Authentication TCP Port
MQTT Client Certificate 8883

Broker URLs

MindConnect MQTT Broker URL for eu1 platform:

  • mindconnectmqtt.eu1.mindsphere.io

MindConnect MQTT Broker URL for eu2 platform:

  • <dynamic>.azure-devices.net

Note

For EU2 platform, the broker URL is known only while onboarding the agent. The steps for handling the broker URL are detailed later.

Architecture

A secure connection between MQTT Broker and the agent is achieved using trusted certificates issued by Certification Authority (CA). Insights Hub tenant administrator uploads the public certificate (usually with extension .pem) from the chosen Certificate Authority. It can also be a self-signed certificate. The native broker can access this certificate and it uses the certificate to authenticate the MindConnect MQTT agents. Insights Hub accepts the certificate in multiple steps. The approach is governed by the underneath platform services and it influences slight variation in the approach for EU1 and EU2.

EU1

CA certificates can be uploaded or deleted by tenant administrators. The asset manager application provides the user interface supporting these operations. There can be a maximum of two such certificates. Before accepting the certificate, Insights Hub verifies the certificate. These certificates are used for the authentication of the agents. Agent certificate (X.509) can only be created using one of the two validated certificates. Otherwise, the agents will not be authenticated. The first time the agent is authenticated, it is provisioned by Insights Hub. Its instance can be then found in Asset Manager.

image info

EU2

The same CA certificate management and agent certificate issuing apply to eu2 as well. Differently from eu1, agents of eu2 first need to connect to Azure DPS service with global DPS URL. After completing the DPS communication steps, DPS provides the broker URL to which agents can connect to.

image info

After successful onboarding, agents can publish and subscribe to topics. Insights Hub has already defined topics that the agents can use to publish and subscribe. They can be found in the API documentation.

Security

MQTT Broker uses Transport Layer Security (TLS) to secure connections from IoT agents. Currently supported versions are 1.0, 1.1 and 1.2 TLS. To prevent any connection problem in the future, use TLS 1.2 as the only TLS version when connecting to MQTT Broker.

MQTT Broker's Server Certificates

MindConnect MQTT Broker uses different server certificates for eu1 and eu2. These certificates are required by the agents to securely communicate with the Broker. This should be downloaded from your respective tenant.

For more information, see Managing CA Certificates documentation.

Note

Due to a security report, Microsoft will start using DigiCert Global G2 Root instead of the currently using Baltimore CyberTrust Root as Certificate Authority (CA). The transition will start on June 2022 and end on October 2022. It is recommended to install both certificates as trusted CAs to avoid related connectivity issues. More details regarding this topic can be found here.

Server Name Indication

MQTT Broker uses the server name indication (SNI) TLS extension for eu1. Agents must use this extension when they connect.

Onboarding

Agents can get onboarded to Insights Hub using agent certificates that are issued by the owner tenant's CA certificate.

Definition of ClientId

To successfully connect, onboard, and communicate with the MQTT broker, each client needs to use a client id in the following format:

For eu1: <clientId> = <tenant>_<AgentCertificate.Subject.CommonName>

AgentCertificate.Subject.CommonName should only contain agent name (e.g. MQTTAgent01)

For eu2: <clientId> = <AgentCertificate.Subject.CommonName>

AgentCertificate.Subject.CommonName should be combination of tenant id and agent name (e.g. Siemens_MQTTAgent01)

MQTT Broker provides Zero Touch Onboarding. Once the agent made a connect request to MQTT Broker with valid certificates, Agent related resource will be created on Insights Hub.

Prerequisites

  • Valid CA certificate should be present in Insights Hub. Replace <tenantId> with actual tenant name in the following URLs.
  • In order to upload CA Certificate for EU1 from the following URL:

https://<tenantId>-assetmanager.eu1.mindsphere.io/connectivity/mqtt-certificates/upload-certificate

  • In order to upload CA Certificate for EU2 from the following URL:

https://<tenantId>-assetmanager.eu2.mindsphere.io/connectivity/mqtt-certificates/upload-certificate

  • During onboarding, agents should have ScopeId. After a successful CA Certificate upload operation, the customer can have ScopeId from MindConnect MQTT UI.
  • Agent certificate should be created.
    • In order to create agent certificate, see here for EU1.
    • In order to create agent certificate, see here for EU2.

Onboarding flow for EU1

MQTT Broker expects agents to provide root certificate for TLS connection and agent certificate, agent key file and client id as MQTT Client Id for MQTT connection. Once agents made a connection request with a valid configuration, Agent resources on Insights Hub will be created and MQTT Broker will disconnect the agent from the broker. Agents should send another connect request after approximately 1 minute, after the next connect request, agents will be able to connect to the broker successfully.

Onboarding flow for EU2

MQTT Broker expects agents to provide root certificate for TLS connection and agent certificate, agent key file and client id as MQTT Client Id for MQTT connection. Before connecting to the actual MQTT broker, each agent needs to connect to a global DPS (Device Provisioning Service) to register itself and get further MQTT broker parameters. Clients need to connect to the DPS MQTT broker using TLS with mutual authentication. To accomplish this, the client needs:

Registering Agent

Once connected to the DPS MQTT broker, the agent needs to be registered as follows:

  • SUBSCRIBE to the status topic $dps/registrations/res/#. The responses to requests made in the next steps will be received from this topic.
  • PUBLISH an empty message to $dps/registrations/PUT/iotdps-register/?$rid=1. This registers the agent and it will now be visible on Insights Hub. A response object will be published by the DPS to the topic subscribed in the first step. It looks like this:
{
  "operationId": "<operationId>",
  "status": "assigning"
}
  • To get the status of registration, PUBLISH an empty message to $dps/registrations/GET/iotdps-get-operationstatus/?$rid=2&operationId=<operationId>. A response is published to the topic in the first step.
{
"operationId": "<operationId>",
  "status": "assigned",
  "registrationState": {
    "x509": {
      "enrollmentGroupId": "TenantEnrollmentGroup-TenantCACertificate-<tenant>"
    },
    "registrationId": "<clientId>",
    "createdDateTimeUtc": "2021-06-03T08:37:58.8521797Z",
    "assignedHub": "<Address of MindSphere MQTT Broker>",
    "deviceId": "<clientId>",
    "status": "assigned",
    "substatus": "initialAssignment",
    "lastUpdatedDateTimeUtc": "2021-06-03T08:37:59.1384561Z",
    "etag": "..."
  }
}

Connect to MQTT Broker

After successful registration, the agent can connect to MindConnect MQTT Broker. MindConnect MQTT Broker URL can be found in the response of the registration message. Value of assignedHub is URL of MindConnect MQTT Broker.

Topic Structure

MindConnect MQTT Broker can be used to access topics defined in several APIs.

MindConnect Async API

MindConnect MQTT Async API defines topics and message structures to ingest timeseries, events and files.

Complete Async API specification can be found here: MindConnect Async API

Asset Modeler Async API

Asset Modeler Async API defines topics and message structures to create models and instantiations and to receive status updates for model creation and instantiation processes.

Models are templates describing asset/aspect types, asset instances, asset hierarchy and mappings from data point ids to variables in aspects.

Instantiations are the realization of models. An instantiation job takes a model and creates the items described in the model by creating types, instances and mappings. A model can be instantiated many times.

Complete Async API specification can be found here: Asset Modeler Async API Service

Topic structure for Asset Modeler is as follows:

EU1

<designator>/<tenantId>/<clientId>/<direction>/<app>_<version>/<app_topic>

<designator>: [tc]

  • tc: tenant-client topic structure

<tenantId>: tenant id

<clientId>: Unique client id.

<direction>: [i|o]

  • i: inbound. Clients can subscribe.
  • o: outbound. Clients can publish

<app>: Registered application topic name.

<version>: Version of application

<app_topic>: App specific sub topics.

PUBLISH : tc/<tenantId>/<clientId>/o/amo_v3/m

  • Models are templates describing asset/aspect types, asset instances, asset hierarchy and mappings from data point ids to variables in aspects.

SUBSCRIBE : tc/<tenantId>/<clientId>/i/amo_v3/ms

  • Receive model creation results for a previous model request.

PUBLISH : tc/<tenantId>/<clientId>/o/amo_v3/i

  • Instantiations are the realization of models. An instantiation job takes a model and creates the items described in the model by creating types, instances and mappings. A model can be instantiated many times.

SUBSCRIBE : tc/<tenantId>/<clientId>/o/amo_v3/ip

  • Receive instantiation job results for a previous instantiation request.

EU2

Topic Structure for PUBLISH

devices/<clientId>/messages/events/<propertyBag>

<clientId>: Unique client id.

<propertyBag>: Property bag should contain application topic name, version and application specific sub topic.

Topic Structure for SUBSCRIBE

devices/<clientId>/messages/devicebound/#

<clientId>: Unique client id.

PUBLISH : devices/<clientId>/messages/events/amo_v3=m

  • Models are templates describing asset/aspect types, asset instances, asset hierarchy and mappings from data point ids to variables in aspects.

PUBLISH : devices/<clientId>/messages/events/amo_v3=i

  • Instantiations are the realization of models. An instantiation job takes a model and creates the items described in the model by creating types, instances and mappings. A model can be instantiated many times.

SUBSCRIBE : devices/<clientId>/messages/devicebound/#

  • Agents should subscribe to a single wild card topic to receive all messages published to them.

MindConnect OPC UA PubSub Async API

MindConnect OPC UA PubSub Async API defines topics and message structures for devices exchanging data according to the OPC UA PubSub Spec Part 14 Release 1.04.

Complete Async API specification can be found here: OPC UA PubSub Async API


  1. Agents that connect on port 443 with client certificate authentication must have Application Layer Protocol Negotiation (ALPN) TLS extension and use the ALPN protocol name listed in the ALPN protocols. 


Last update: November 27, 2023

Except where otherwise noted, content on this site is licensed under the Development License Agreement.