MindConnect MQTT Broker¶

Overview¶

MindConnect MQTT broker authenticates MQTT agents over TLS to publish and subscribe to messages based on the MQTT protocol. It serves as an alternative to the HTTP-based MindConnect Service.

The MindConnect MQTT broker supports the following port-protocol-authentication combination:

Broker URLs¶

MindConnect MQTT broker URL for EU1: mindconnectmqtt.eu1.mindsphere.io

Architecture¶

A secure connection between the MQTT broker and the agent is established using trusted certificates issued by a Certification Authority (CA). Insights Hub tenant administrators upload the public certificate (typically with a .pem extension) from the chosen Certificate Authority, which can also be self-signed. The native broker can access this certificate to authenticate MindConnect MQTT agents. Insights Hub accepts the certificate through a multi-step process. Tenant administrators can upload or delete CA certificates, with a maximum of two certificates allowed. The asset manager application provides a user interface to support these operations. Before accepting the certificate, Insights Hub verifies it. These certificates are used to authenticate the agents. The agent certificate (X.509) can only be created using one of the two validated certificates; otherwise, the agents will not be authenticated. When an agent is authenticated for the first time, it is provisioned by Insights Hub and its instance can then be found in the Asset Manager.

After successful onboarding, agents can publish and subscribe to topics. Insights Hub provides predefined topics that agents can use for publishing and subscribing. These topics are detailed in the API documentation.

Security¶

MQTT broker uses Transport Layer Security (TLS) to secure connections from IoT agents. Currently, the supported versions are 1.0, 1.1, and 1.2 of TLS. To avoid future connection issues, ensure that you use only TLS 1.2 when connecting to the MQTT broker.

MQTT Broker's Server Certificates¶

MindConnect MQTT broker uses different server certificates for eu1 and eu2. Agents require these certificates to securely communicate with the Broker. Downloaded the appropriate certificate from your respective tenant.

For more information, refer to the Managing CA Certificates documentation.

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 the agent name (e.g. MQTTAgent01)

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

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

MQTT broker provides zero-touch onboarding. Once the agent makes a connect request to the MQTT broker with valid certificates, an agent-related resource will be created on Insights Hub.

Prerequisites¶

• A valid CA certificate should be present in Insights Hub. Replace <tenantId> with the actual tenant name in the following URLs.
• To upload the CA Certificate for EU1, use the following URL: https://<tenantId>-assetmanager.eu1.mindsphere.io/connectivity/mqtt-certificates/upload-certificate
• During onboarding, agents need a ScopeId. After successfully uploading a CA Certificate, customers can obtain the ScopeId from the MindConnect MQTT UI.
• An agent certificate should be created.
  • To create an agent certificate, refer to the instructions here for EU1.

Onboarding Flow¶

MQTT broker expects agents to provide a root certificate for the TLS connection and an agent certificate, agent key file and client Id as the MQTT client Id for the MQTT connection. Once agents make a connection request with a valid configuration, agent resources on Insights Hub will be created and the MQTT broker will disconnect the agent from the broker. Agents should then send another connection request after approximately one minute. Following this second connection request, agents can connect to the broker successfully.

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 on 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 to in the first step. It looks like this:

{
  "operationId": "<operationId>",
  "status": "assigning"
}

• To get the status of a 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 the MindConnect MQTT broker. MindConnect MQTT broker URL can be found in the response of the registration message. The value of assignedHub is the URL of the MindConnect MQTT broker.

Topic Structure¶

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

MindConnect Async API¶

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

All Async API specifications 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.

All Async API specifications can be found here: Asset Modeler Async API Service.

Topic structure for Asset Modeler is as follows:

<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 an application

<app_topic>: App specific sub topics.

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

• Models are templates describing asset or 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.

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.

All Async API specifications can be found here: OPC UA PubSub Async API.

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