Migrate to MindConnect MQTT from MindConnect IoT Extension¶

This guide provides you with necessary steps to migrate from MindConnect IoT Extension to MindConnect MQTT without any data loss.

Prerequisite¶

• Ensure your device has internet connection.

• Offboard the device from MindConnect IoT Extension to ensure the stop of data ingestion from the device to MindConnect IoT Extension and also the background running processes. This avoids the asset from receiving and also to stop from sending the data after transitioning to MindConnect MQTT.

Steps to migrate from IoT extension to MQTT¶

The below image shows the overview of migration flow,

Follow these steps to migrate from IoT extension to MQTT,

1. Change the broker URL to MindConnect MQTT broker:
   Change the broker URL in the software stack to "mqtts://mindconnectmqtt.eu1.mindsphere.io".

   

2. Encrypt the connection between the device and MindConnect MQTT Broker to secure the data:
   To encrypt the connection, download and install the broker certificate from Asset Manager. The broker certificate is same across all Insights Hub account. To download and install the certificate, follow these steps
   

   • Login to Insights Hub environment and go to the "Asset Manager" application.
     
   • In "Connectivity" section, Select "Manage MQTT Certificates" and click "Broker Information".
     
   • Select "Download broker certificate" as shown below.
     

   

   • To Install the broker certificate, install the downloaded broker certificate depending on the software stack. MindConnect MQTT broker supports Port 443 and 8883 for the connectivity requirements.

3. Generate Agent certificate:
   Every agent is identified with an unique Agent certificate and an Associated key, ensure to secure the private key. Both can be downloaded from Insights Hub or generated outside of Insights Hub, this avoids the requirement for username & password. To generate the certificates through Insights Hub UI in order to upload the data to Insights Hub follow these steps. To generate and download a new certificate, follow these steps
   

   • Login to your Insights Hub environment.
     
   • Navigate to "Asset Manager" application and In "Connectivity" section, Select "Manage MQTT Certificates".
     
   • Click "Get a new certificate" and proceed to authentication step to generate Agent certificate.

   
   

   • To generate an agent certificate, there are two options available as shown in the below image.
     

   

   1."Generate certificate" - Download Agent Certificates using built-in CA certificate. For more information, refer to Obtain Auto-generated agent certificates documentation. The below image shows the example of an agent certificate from Insights Hub UI.

   

   2."Upload CA certificate" - To derive an own agent certificate, refer to Manage CA Certificates.

4. Re-use the mapped asset:
   Extract the asset mapping model of a MindConnect IoT Extension device by following steps,
   

   • Login to Insights Hub and launch MindConnect IoT Extension application from your launchpad.
   • Click the following API "https://{tenant}-mciotextension.{region}.mindsphere.io/service/oc2-map-config/api/v1/mcmqtt/{deviceId}/assetmodeller+timeseries" from the browser by providing a valid MindConnect IoT Extension device ID. The API provides Asset, Aspect and Variable mapping information in MindConnect MQTT Asset model format as shown in below image and the Asset model information is noted.

   

   Note

   • If the device has already stored data in an asset through MindConnect IoT Extension, the same asset is used without losing the data. Use the built-in services provided by Siemens to download the model file and time series template.
   • In order to find the device ID, click "All device" and select the device to check the info page as shown in the below image.
     

   

5. Connect to MQTT broker and instantiate the data model:
   Follow these steps to connect to MQTT broker and instantiate the data model,
   In order to Create and Instantiate MQTT data model in Insights Hub, refer to How to create data model for MindConnect MQTT agent. In the document link provided, use asset modeller API response as a request message body in the step "Publish Your Model". The above documentation steps are summarized below.
   

   • Publishing the model file to MindConnect MQTT broker - a successful model file published from the agent (device) describes to the services in Insights Hub to handle the data precisely. This is a necessary step before sending any data from an agent.
     To publish the model file, the agent should send the file on a predefined topic for publishing the Model File tc/{tenantId}/{client_id}/o/amo_v3/m. The client_id for the topic is created when creating the certificate. It changes with each agent.
     

   
   

   • Instantiating the data model - The model file should be converted to real assets to store the incoming data. For more information, refer to Asset Modeler Async API Service.
     To publish the model file, the agent should send the file on a predefined topic for publishing the Model File tc/{tenantId}/{client_id}/o/amo_v3/i. The client_id for the topic is created when creating the certificate. Each agent will have its own Client ID.
     

   

6. Send data over MindConnect MQTT:
   

   • Send Time series data - Refer to How to send time series data from MindConnect MQTT agent to Insights Hub asset. Use the template from IoT Extension API "https://{tenant}-mciotextension.{region}.mindsphere.io/service/oc2-map-config/api/v1/mcmqtt/{deviceId}/assetmodeller+timeseries" for a quick start.

   

   Note

   Ensure to stop sending the data over MindConnect IoT Extension before sending the data over MindConnect MQTT. This will ensure the data in not duplicated in your asset.

   • Send Event data - refer to How to send event data from MindConnect MQTT agent to Insights Hub asset.

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