Skip to content

Onboarding MindConnect MQTT Agent

Overview

MindConnect MQTT agents can be onboarded to MindSphere using agent certificates that are issued by the owner tenant's CA certificate.

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

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

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

Where <tenant> is the tenant name and <AgentCertificate.Subject.CommonName> is Common Name attribute of agent certificate subject. A single client id represents a single agent, and multiple connections using a single client id are not allowed.

Prerequisites

Agent Onboarding

EU1

  1. Create an agent private key

    Following commands creates an agent private key (line 1); creates a CSR using the agent name as certificate subject's Common Name, that is valid for 1 year (line 2). Next, the tenant's private key is used to issue the agent certificate using created CSR (line 3). Finally, the agent certificate and CA certificate are concatenated to use in later steps.

    LINUX:

    export TENANT=<yourtenant>
    export DEVICE_NAME=<yourdevicename>
    export COUNTRY_CODE =<COUNTRY_CODE>
    export CITY =<CITY>
    export ORGANIZATION =<ORGANIZATION>
    
    1. openssl genrsa -out $DEVICE_NAME.key 2048

    2. openssl req -new -key $DEVICE_NAME.key -out $DEVICE_NAME.csr -subj "/C=$COUNTRY_CODE/ST=$CITY/O=$ORGANIZATION/OU=IT/CN=$DEVICE_NAME"

    3. openssl x509 -req -in $DEVICE_NAME.csr -CA "$TENANT.pem" -CAkey "$TENANT.key" -CAcreateserial -out $DEVICE_NAME.pem -days 365 -sha256

    4. cat $DEVICE_NAME.pem "$TENANT.pem" > "$DEVICE_NAME"_chain.pem

    You can view the created certificate with the following command:

    openssl x509 -in "$DEVICE_NAME"_chain.pem -text -noout

    WINDOWS:

    set TENANT=<yourtenant>
    set DEVICE_NAME=<yourdevicename>
    set COUNTRY_CODE =<COUNTRY_CODE>
    set CITY =<CITY>
    set ORGANIZATION =<ORGANIZATION>
    
    1. openssl genrsa -out %DEVICE_NAME%.key 2048

    2. openssl req -new -key %DEVICE_NAME%.key -out %DEVICE_NAME%.csr -subj "/C=%COUNTRY_CODE%/ST=%CITY%/O=%ORGANIZATION%/OU=IT/CN=%DEVICE_NAME%"

    3. openssl x509 -req -in %DEVICE_NAME%.csr -CA "%TENANT%.pem" -CAkey "%TENANT%.key" -CAcreateserial -out %DEVICE_NAME%.pem -days 365 -sha256

    4. type %DEVICE_NAME%.pem "%TENANT%.pem" > "%DEVICE_NAME%"_chain.pem

    You can view the created certificate with the following command:

    openssl x509 -in "%DEVICE_NAME%"_chain.pem -text -noout

  2. Connecting to MindSphere MindConnect MQTT broker

    Login to your MindSphere tenant and go to the "Asset Manager" application, in "Connectivity" section, select "Manage MQTT Certificates" and click "Broker Information". Under this, MindSphere "MindConnect MQTT Broker Url" and "MindConnect MQTT Broker Certificate" can be found.

    image1

    Connection parameters are as follows:

    ClientId: <tenant>_<AgentCertificate.Subject.CommonName>

    Username: <empty>

    Password: <empty>

    Client Certificate: <DEVICE_NAME>_chain.pem

    Client Key: <DEVICE_NAME>.key

    At the first connection attempt, the broker will close the connection and start provisioning of the agent in the MindSphere backend. Once completed, you can see your newly created agent asset in the Asset Manager application in the Launchpad.

    After a couple of seconds, retry the connection attempt. This time connection will remain intact since provisioning is complete.

    • Mosquitto Connection Example

    For example, the following mosquitto_sub command will connect and subscribe to a topic (You need AmazonRootCA1.pem to contain broker certificate, see above for how to find it):

    mosquitto_sub --cafile AmazonRootCA1.pem --key "$DEVICE_NAME".key \ --cert "$DEVICE_NAME".pem -h "$MqttBrokerHost" \ -p 8883 -t tc/"$TENANT"/"$CLIENT_ID"/i/amo_v3/ms -i $CLIENT_ID -v -d
    
    • MQTTX Connection Example

    image2

    Once connected, clients can utilize the topics defined by applications available on MDSP AWS MindConnect Connectivity. Inspect async API specs of related services to learn about available topics and payload schemas.

EU2

  1. Create an agent private key

    Following commands creates an agent private key (line 1); creates a CSR using the clientId as certificate subject's Common Name, that is valid for 1 year (line 2). Next, the tenant's private key is used to issue the agent certificate using created CSR (line 3). Finally, the client certificate and CA certificate are concatenated to use in later steps.

    LINUX:

    export TENANT=<yourtenant>
    export DEVICE_NAME=<yourdevicename>
    export COUNTRY_CODE =<COUNTRY_CODE>
    export CITY =<CITY>
    export ORGANIZATION =<ORGANIZATION>
    export CLIENT_ID="$TENANT"_"$DEVICE_NAME"
    
    1. openssl genrsa -out $DEVICE_NAME.key 2048

    2. openssl req -new -key $DEVICE_NAME.key -out $DEVICE_NAME.csr -subj "/C=$COUNTRY_CODE/ST=$CITY/O=$ORGANIZATION/OU=IT/CN=$CLIENT_ID"

    3. openssl x509 -req -in $DEVICE_NAME.csr -CA "$TENANT.pem" -CAkey "$TENANT.key" -CAcreateserial -out $DEVICE_NAME.pem -days 365 -sha256

    4. cat $DEVICE_NAME.pem "$TENANT.pem" > "$DEVICE_NAME"_chain.pem

    You can view the created certificate with the following command:

    openssl x509 -in "$DEVICE_NAME"_chain.pem -text -noout

    WINDOWS:

    set TENANT=<yourtenant>
    set DEVICE_NAME=<yourdevicename>
    set COUNTRY_CODE =<COUNTRY_CODE>
    set CITY =<CITY>
    set ORGANIZATION =<ORGANIZATION>
    set CLIENT_ID="%TENANT%"_"%DEVICE_NAME%"
    
    1. openssl genrsa -out %DEVICE_NAME%.key 2048

    2. openssl req -new -key %DEVICE_NAME%.key -out %DEVICE_NAME%.csr -subj "/C=%COUNTRY_CODE%/ST=%CITY%/O=%ORGANIZATION%/OU=IT/CN=%CLIENT_ID%"

    3. openssl x509 -req -in %DEVICE_NAME%.csr -CA "%TENANT%.pem" -CAkey "%TENANT%.key" -CAcreateserial -out %DEVICE_NAME%.pem -days 365 -sha256

    4. type %DEVICE_NAME%.pem "%TENANT%.pem" > "%DEVICE_NAME%"_chain.pem

    You can view the created certificate with the following command:

    openssl x509 -in "%DEVICE_NAME%"_chain.pem -text -noout

  2. Connecting to a global DPS (Device Provisioning Service)

    Before connecting to the MQTT broker, each device needs to connect to a global DPS (Device Provisioning Service) provided by Azure to register itself and get further MQTT broker parameters.

    For further information about Device Provisioning Service, refer to IoT Hub Device Provisioning Service

    Agents need to connect to the DPS endpoint using TLS with mutual authentication. To accomplish this, the agent needs to:

    Login to your MindSphere tenant and go to the "Asset Manager" application, in the "Connectivity" section, select "Manage MQTT Certificates" and click "Broker Information". Under this, MindSphere "MindConnect MQTT Broker Url" and "MindConnect MQTT Broker Certificate" can be found.

    image3

    Login to your MindSphere tenant and go to the "Asset Manager" application, in the "Connectivity" section, select "Manage MQTT Certificates" and click "Own Certificates". Under this, ScopeId can be found.

    image4

    Connection parameters are as follows:

    Agent Certificate Chain: "$CLIENT_ID"_chain.pem

    Agent Private Key: "$CLIENT_ID".key

    After a successful TLS connection, the agent must send an MQTT CONNECT message with proper username, empty password, and proper client id described as below:

    Username = <scopeId>/registrations/<clientId>/api-version=2019-03-31

    Password = <empty>

    ClientId = <tenant>_<uniqueId>: must match agent certificate subject's Common Name attribute

  3. 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 MindSphere. A response object will be published by the DPS to the topic subscribed in the first step. It looks like this:

    {
    "operationId": "4.abe16cbf3f71fe17.19a42d8c-76f4-438c-be83-85d01f7bff73",
    "status": "assigning"
    }
    

    Ensure that the status is 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. Example:
    {
    "operationId": "4.abe16cbf3f71fe17.19a42d8c-76f4-438c-be83-85d01f7bff73",
    "status": "assigned",
    "registrationState": {
        "x509": {
        "enrollmentGroupId": "TenantEnrollmentGroup-TenantCACertificate-<tenantId>"
        },
        "registrationId": "<tenantId>_MqttTestAgent",
        "createdDateTimeUtc": "2021-06-03T08:37:58.8521797Z",
        "assignedHub": "conn-prod-ex-iothub.azure-devices.net",
        "deviceId": "<tenantId>_MqttTestAgent",
        "status": "assigned",
        "substatus": "initialAssignment",
        "lastUpdatedDateTimeUtc": "2021-06-03T08:37:59.1384561Z",
        "etag": ""
    }
    }
    

    Now status is assigned. The registarationState.assignedHub attribute indicates the IoT-Hub URI that the registered agent should connect to.

  4. Connecting to MQTT broker

    Mindsphere Services (e.g. MindConnect, AssetModeler, etc.) are accessible to agents on the MQTT broker address given in the registration process by DPS. Agents should connect to that broker to access MDSP services.

    Connection parameters are as follows:

    MQTT broker host (iothubhostname): <Address of assignedHub, as reported by DPS>

    MQTT broker port: 8883

    MQTT broker certificate: Azure IoT Hub uses certificates issued by Baltimore CyberTrust Root. See IoT Hub TLS certificate update for details.

    ClientId: <tenant>_<uniqueId> // Same as DPS registration

    Username: <iothubhostname>/<client_id>/?api-version=2018-06-30

    Password: <empty>// Same as DPS registration

    Once connected, clients can utilize the topics defined by applications available on MDSP Azure MindConnect Connectivity.

  5. MQTTX Agent Onboarding Example

    • Connect to DPS Server

      image5

    • SUBSCRIBE to the status topic $dps/registrations/res/#. The responses to requests made in the next steps will be received from this topic.

      image6

    • PUBLISH an empty message to $dps/registrations/PUT/iotdps-register/?$rid=1. This registers the agent and it will now be visible on MindSphere. A response object will be published by the DPS to the topic subscribed in the first step. It looks like this:

      image7

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

      image8

      MindSphere MindConnect MQTT Broker Url is assignedHub's value in the response message.

    • Connect MQTT Broker

      Azure IoT Hub uses certificates issued by Baltimore CyberTrust Root.

      Login to your MindSphere tenant and go to the "Asset Manager" application, in the "Connectivity section", select "Manage MQTT Certificates" and click "Broker Information". Under this, MindSphere "MindConnect MQTT Broker Url" and "MindConnect MQTT Broker Certificate" can be found.

      image9

      MQTT broker host: <Address of assignedHub, as reported by DPS>

      MQTT broker port: 8883

      ClientId: <tenant>_<uniqueId> // Same as DPS registration

      Username: <assignedHub>/<client_id>/?api-version=2018-06-30

      Password: <empty>// Same as DPS registration

      image10

Any questions left?

Ask the community


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


Last update: August 30, 2022