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:

Broker URLs¶

MindConnect MQTT Broker URL for EU1:

• mindconnectmqtt.eu1.mindsphere.io

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

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.

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

• 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.

Onboarding flow¶

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.

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:

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

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

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