Integrating MQTT via MindConnect IoT Extension - Developer Documentation
Skip to content

Integrating MQTT - via MindConnect IoT Extension

The MindConnect IoT Extension supports many protocols and interfaces, e.g. MQTT, REST, OPC-UA. MQTT is a messaging transport protocol, which uses the brokered publish or subscribe pattern. This pattern separates the publisher client who sends a particular message from other the subscriber clients who receives it.

For more information on migrating from MindConnect IoT extension to MindConnect MQTT, refer to How to migrate from MindConnect IoT Extension to MindConnect MQTT.

This guide demonstrates how to use MQTT via MindConnect IoT Extension and shows an extract of its basic functionalities.

General Information

Execution Duration: 30 minutes
Tested with Insights Hub version: Release 19th December 2020

Network

The MQTTBox integration does not work inside company networks behind a proxy.

Prerequisites

  • MQTTBox is installed on your computer, e.g., the Google Chrome Plugin.
  • A Insights Hub account
  • The MindConnect IoT Extension Upgrade - this allows to use the MindConnect IoT Extension. To get the upgrade, your tenant admin needs to contact their assigned Account Executive or Customer Success Manager.
  • In order to establish a successful MQTT client connection, create a new MindConnect IoT Extension user account with related roles. Use the new account exclusively for the MQTT connection. For MindConnect IoT Extension UI login, use the regular Insights Hub user account.
  • The following roles must be assigned to your user:
    • For regular Insights Hub user
      • mdsp:core:TenantAdmin, assigned in user management
      • mdsp:core:mcie.user, assigned in user management
    • For MindConnect IoT Extension user
      • Devicemanagement User, assigned in MindConnect IoT Extension

Connect MQTTBox to Insights Hub

The MQTTBox can post and subscribe to messages. It uses special topics and templates for sending messages to MindConnect IoT Extension, where they are displayed in real time.

  1. Open MQTTBox.
  2. Click "Create MQTT Client"
  3. Fill the information listed below into the form for "MQTT CLIENT SETTINGS". Fields that are not listed can be left as default.

    Field Configuration
    MQTT Client Name {uniqueName}
    MQTT Client ID {arbitraryUniqueID}
    Protocol mqtt/tcp
    Host {TenantName}.mciotextension.{YourRegion}.{mindsphere-domain}
    e.g.: dade1.mciotextension.eu1.mindsphere.io
    Username {tenantName}/{mciotExtensionUsername}
    (user alias is not supported)
    Password {password}
    Append timestamp to MQTT client ID? uncheck
    Broker is MQTT v3.1.1 compliant check
    Clean Session check
    Queue outgoing QoS zero messages check
    Keep alive check

    MqttBoxSettings

  4. Click "Save".

A connection to MindConnect IoT Extension is established.

Create a Device via MQTT

In order to send data to Insights Hub it is necessary to create a device in MindConnect IoT Extension.

  1. Open the new MQTT Client in MQTTBox.
  2. Enter the configuration parameters listed below in the publishing form. This tells MQTTBox to use the template 100 for creating a new device in MindConnect IoT Extension.

    Field Configuration
    Topic to publish s/us
    QoS 0 - Almost Once
    Retain uncheck
    Payload Type strings / JSON / XML / Characters
    Payload 100,My first MQTT device,MCIoT_MQTTdevice
  3. Click "Publish".

Verify the Device in MindConnect IoT Extension

  1. Open the MindConnect IoT Extension from the Launchpad.
  2. Log in with valid credentials.
  3. Navigate to "Device Management" → "All devices".
  4. Select the new device from the list to see more information. MCIOT verify device
  5. Inspect the general information in the "Info" tab.
    MCIOT device info
  6. Select the "Identity" tab and review the External ID. This ID is created automatically in order to link the device to the MQTT Client(ID is same as "MQTT Client ID" of MQTTBox).
    MCIOT device identity

Send Data via MQTT

Manage Device Information

The general information of the device only hold the owner, name, type and some other meta data so far. This section illustrates how to manage device information in MindConnect IoT Extension by setting the hardware parameters and interval from the MQTT Client.

  1. Open the MQTT Client in MQTTBox.
  2. Enter the configuration parameters listed below in the publishing form. This tells MQTTBox to use the templates 110 and 117 for setting the hardware parameters (serial number, model, revision) and the required interval for monitoring the device availability, respectively.

    Field Configuration
    Topic to publish s/us
    QoS 0 - Almost Once
    Retain uncheck
    Payload Type strings / JSON / XML / Characters
    Payload 110,MQTT test model,1.2.3
    117,10
  3. Click "Publish".

  4. Reload the "Info" tab of the MQTT device in MindConnect IoT Extension to verify that the "Device Status" and the "Hardware" sections have been updated. MCIOT Device manage info

Send Measurements

TimeStamp

Passing timestamps in the connection between MQTT Client and MindConnect IoT Extension is optional. If you do not pass them along, the server automatically creates a timestamp with the current server time.

MQTTBox provides templates for common measurements, like signal strength, temperature and battery. This section shows how to send these template measurements and how to send custom measurements.

Template Measurements

  1. Open the MQTT Client in MQTTBox.
  2. Enter the configuration parameters listed below in the publishing form. This tells MQTTBox to use the templates 210, 211 and 212 for sending signal strength, temperature and battery measurements, respectively.

    Field Configuration
    Topic to publish s/us
    QoS 0 - Almost Once
    Retain uncheck
    Payload Type strings / JSON / XML / Characters
    Payload 210,-87
    211,24
    212,95
  3. Click "Publish".

  4. Change the values in the payload slightly and publish again several times, e.g. use:

    Field Configuration 1 Configuration 2 Configuration 3
    Payload 210,-85
    211,20
    212,90
    210,-80
    211,22
    212,92
    210,-50
    211,28
    212,85
  5. Open the "Measurements" tab of your device in MindConnect IoT Extension and verify that three graphs display the published values. If the values are not displayed, enable "Realtime" in the settings. MCIOT Device measurements

Custom Measurements

  1. Open the MQTT Client in MQTTBox.
  2. Enter the configuration parameters listed below in the publishing form. This tells MQTTBox to use the template 200 for sending custom measurements.

    Field Configuration
    Payload 200,myCustomTemperatureMeasurement,fahrenheit,75.5,F
  3. Change the values in the payload slightly and publish again several times, e.g. use:

    Field Configuration
    Payload 200,myCustomTemperatureMeasurement,fahrenheit,85.5,F
    200,myCustomTemperatureMeasurement,fahrenheit,60.5,F
    200,myCustomTemperatureMeasurement,fahrenheit,55.8,F
    200,myCustomTemperatureMeasurement,fahrenheit,70.2,F
    200,myCustomTemperatureMeasurement,fahrenheit,91.5,F
  4. Open the "Measurements" tab of your device in MindConnect IoT Extension and verify that the custom measurements graph has been added.

Receive Messages via MQTT

Receive Events and Errors via MQTT

  1. Open the MQTT Client in MQTTBox.
  2. Enter the configuration parameters listed below in the subscribing form. This tells MQTTBox to subscribe to the error queue, where notifications are published in case of errors.

    Field Configuration
    Topic to subscribe s/e
    QoS 0 - Almost Once
  3. Click "Subscribe". MQTT Device subscribe

  4. In order to trigger an error notification, enter the configuration parameters listed below in the publishing form. The listed payload does intentionally not correspond with the used template to cause an error.

    Field Configuration
    Topic to publish s/us
    QoS 0 - Almost Once
    Retain uncheck
    Payload Type strings / JSON / XML / Characters
    Payload 211,cold
  5. Click "Publish".

  6. An error message appears in the subscribe section. MQTT Device subscribe error

Info

Refer to MQTT Cheat Sheet to discover more topics to subscribe to.

Receive Standard Messages

To send messages to your MindConnect IoT Extension devices, it is required to have your own custom Insights Hub application which uses APIs from MindConnect IoT Extension directly. Refer to Subscribe templates to discover the templates the client can receive.

Custom Templates

Custom templates are used to convert MindConnect IoT Extension data and Rest API calls. For more information, see Custom template documentation SmartREST topics and SmartREST UI setup .

Create a Child Device

  1. Open the MQTT Client in MQTTBox.
  2. Enter the configuration parameters listed below in the publishing form. This tells MQTTBox to use the template 101 for creating a new child device.

    Field Configuration
    Topic to publish s/us
    QoS 0 - Almost Once
    Retain uncheck
    Payload Type strings / JSON / XML / Characters
    Payload 101,API_MQTT_Child,API MQTT Child,c8y_MQTTChildType
  3. Click "Publish" Create Child Device via MQTT

  4. Open the new "Child devices" tab of your device in MindConnect IoT Extension and verify that the child device has been created. Child Device created via MQTT

Create Alarms

This section shows how to create alarms for the device in MQTTBox. Four templates are available to create alarms for different severities:

  • Template 301 creates a critical alarm.
  • Template 302 creates a major alarm.
  • Template 303 creates a minor alarm.
  • Template 304 creates a warning alarm.

The following steps show how to define a major and a warning alarm for your device.

  1. Open the MQTT Client in MQTTBox.
  2. Enter the configuration parameters listed below in the publishing form. This tells MQTTBox to use the templates 302 and 304 for creating a major and a warning error, respectively.

    Field Configuration
    Topic to publish s/us
    QoS 0 - Almost Once
    Retain uncheck
    Payload Type strings / JSON / XML / Characters
    Payload 302,My_MQTT_FirstDevice_Major,No data received from device
    304,simple warning
  3. Click "Publish".

  4. Open the new "Alarms" tab of your device in MindConnect IoT Extension and verify that the alarms are now listed in the respective alarm types. MQTT Create alarm for device

Create Events

  1. Open the MQTT Client in MQTTBox.
  2. Enter the configuration parameters listed below in the publishing form. This tells MQTTBox to use the template 401 for creating a location event. You can get the latitude and longitude of a place from https://www.latlong.net/.

    Field Configuration
    Topic to publish s/us
    QoS 0 - Almost Once
    Retain uncheck
    Payload Type strings / JSON / XML / Characters
    Payload 401,49.872825,8.651193
  3. Click "Publish"

  4. Open the "Events" tab of your device in MindConnect IoT Extension and verify that the location event is listed. Create Event MCIoT
  5. Open the MQTT Client in MQTTBox again.
  6. Enter the configuration parameters listed below in the publishing form. This tells MQTTBox to use the template 402 for creating a location event and updating the device location.

    Field Configuration
    Payload 402,49.872825,8.651193
  7. Click "Publish".

  8. Navigate to MindConnect IoT Extension.
  9. Open the "Location" tab and the "Tracking" tab of your device in MindConnect IoT Extension and verify that the location of the device has been updated. MCIOT Location event

MQTT Client examples

There are many different ways to connect MQTT Client to Insights Hub. For information on how to connect to Insights Hub using MQTT in Python, Java, Node.js,C or C#, refer the tutorial.

The following is a configuration example to connect to Insights Hub using python:

Field Configuration
serverUrl <tenant>.mciotextension.eu1.mindsphere.io
port 1883
clientId My_mqtt_python_client
device_name My Python MQTT device
tenant <tenant>
username JaneDoe@siemens.com
password <password>

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


Last update: July 3, 2023