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 managementmdsp:core:mcie.user
, assigned in user management
- For MindConnect IoT Extension user
Devicemanagement User
, assigned in MindConnect IoT Extension
- For regular Insights Hub user
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.
- Open MQTTBox.
- Click "Create MQTT Client"
-
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 -
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.
- Open the new MQTT Client in MQTTBox.
-
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
-
Click "Publish".
Verify the Device in MindConnect IoT Extension¶
- Open the MindConnect IoT Extension from the Launchpad.
- Log in with valid credentials.
- Navigate to "Device Management" → "All devices".
- Select the new device from the list to see more information.
- Inspect the general information in the "Info" tab.
- 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.
- Open the MQTT Client in MQTTBox.
-
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
-
Click "Publish".
- 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¶
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¶
- Open the MQTT Client in MQTTBox.
-
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
-
Click "Publish".
-
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
-
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¶
- Open the MQTT Client in MQTTBox.
-
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
-
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
-
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¶
- Open the MQTT Client in MQTTBox.
-
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
-
Click "Subscribe".
-
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
-
Click "Publish".
- An error message appears in the subscribe section.
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¶
- Open the MQTT Client in MQTTBox.
-
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
-
Click "Publish"
- 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.
- Open the MQTT Client in MQTTBox.
-
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
-
Click "Publish".
- 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¶
- Open the MQTT Client in MQTTBox.
-
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
-
Click "Publish"
- Open the "Events" tab of your device in MindConnect IoT Extension and verify that the location event is listed.
- Open the MQTT Client in MQTTBox again.
-
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
-
Click "Publish".
- Navigate to MindConnect IoT Extension.
- 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 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> |
Related Links¶
- General Information(Why Insights Hub, Demo, Request Access...)
- MindConnect Products
- MindConnect IoT Extension
- MindConnect IoT Extension Getting Started
- HelloMQTT using Python
Except where otherwise noted, content on this site is licensed under the Development License Agreement.