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/subscribe pattern. This pattern separates the publisher client, who sends a particular message, from other the subscriber clients, who receive it.

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

Prerequisites¶

• MQTTBox is installed on your computer, e.g., the Google Chrome Plugin.
• A MindSphere 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 MindSphere user account.
• The following roles must be assigned to your user:
  • For regular MindSphere 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 MindSphere¶

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

   

4. Click "Save".

A connection to MindConnect IoT Extension is established.

Create a Device via MQTT¶

In order to send data to MindSphere 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.
5. Inspect the general information in the "Info" tab.
   
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).
   

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.

Send Measurements¶

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.

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

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.

Receive Standard Messages¶

To send messages to your MindConnect IoT Extension devices, it is required to have your own custom MindSphere 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"

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

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.

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

MQTT Client examples¶

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

The following is a configuration example to connect to MindSphere using python:

Related Links¶

• MindSphere General Information(Why MindSphere, Demo, Request Access...)
• MindConnect Products
• MindConnect IoT Extension
• MindConnect IoT Extension Getting Started
• HelloMQTT using Python

Any questions left?

Ask the community

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