Monitoring Remotely with MQTT

MQTT is one of the most common messaging protocols used in the IoT world. Its lightweight structure and topic-based architecture enable fast and efficient message transmission, even over very low bandwidth. Watch the video above for an overview of the following exercise and to see how the MQTT protocol is used.

In this exercise, you will use the interoperability tools built into InterSystems IRIS for Health™ to construct a basic user portal that monitors live EKG readings from a set of remote patients. See how you can use a minimal amount of code to quickly take real-time data coming from an MQTT broker, then save and display it on a dashboard.

Tip

If you would like to skip the exercise and view the completed application on your instance, navigate to Interoperability > List > Productions in the Management Portal, select Solution.MQTT, and click Open. In the Production Configuration window, click Start.

Set up

Make sure you have an instance of InterSystems IRIS ready to go. If you see your sandbox settings below, you are ready. Otherwise, login or register.

Need InterSystems IRIS?

Get a free, online development sandbox here. Log in with your InterSystems login account, or register for one below.

Login Register

Installation

InterSystems IRIS for Health Sandbox

1. Open the (setting requires sandbox - click here) (or use the Cloud IDE link above) in the InterSystems IRIS for Health sandbox, and change to the shared directory: cd /home/project/shared.
2. Type git clone https://github.com/intersystems/Samples-MQTT-EKG-Devices.
3. Open the web terminal by navigating to InterSystems > Web Terminal and enter the login credentials provided with your sandbox.
4. At the next three command prompts, type:
   1. set $Namespace = "INTEROP"
   2. do $system.OBJ.Load("/home/project/shared/Samples-MQTT-EKG-Devices/Installer.cls","ck")
   3. do ##class(App.Installer).InitializeLearningLab()
5. Take note of your top-level topic string for later use.
6. Click the Management Portal link in your sandbox.
7. Change the namespace to INTEROP.

Docker

1. In your terminal, type git clone https://github.com/intersystems/Samples-MQTT-EKG-Devices.
2. In the cloud IDE provided with your InterSystems IRIS for Health sandbox, change the directory: cd Samples-MQTT-EKG-Devices.
3. In the command line, type docker-compose up -d.
4. Once complete, type docker-compose exec iris iris session iris -U %SYS "##class(App.Installer).InitializeDocker()".
5. Take note of your top-level topic string for later use.
6. Throughout the exercise, use the following connection settings:
   • Username: SuperUser
   • Password: SYS
   • Host: localhost
   • Port: 52773
   • Management Portal URL: http://localhost:52773/csp/sys/UtilHome.csp

Create a Production

1. In the INTEROP namespace, navigate to Interoperability > List > Productions. Click New and complete the following fields:
   • Package: Demo
   • Production Name: MQTTProduction

   Click OK.
   

2. You will now be in the production configuration interface, which allows you to add business services, processes, and operations to your production to handle incoming messages.
   This production will:
   1. Subscribe to an MQTT topic and pass messages into the interface.
   2. Transform those messages into a patient record.
   3. Regularly update the user portal utility as data changes.
3. You can either code a business process or generate one using a graphical process designer called the Business Process Designer (BPL). To add a new business process, navigate to Home > Interoperability > List > Business Processes, then click New and add:
   • Package: Demo
   • Name: ProcessMQTTMessage
4. Click the Context tab on the right. Here you can see that the business process always initiates by receiving a request of a certain class.
   1. Set the class to Enslib.MQTT.Message. This is the message type that will be sent from our MQTT service as it receives heart rate data.
   2. Set the value of the Response class to Demo.HeartRate. This is a simple table class to which our MQTT message will be transformed. The code for this has already been written and is shown below.

      /// Production response class. Target of data transformation
      /// that converts from MQTT topic and payload into a persistent object.
      Class Demo.HeartRate Extends (Ens.Response)
      {
      
      Property PatientID As %String;
      
      Property BPM As %Integer;
      
      // Initialize all HeartRate objects with a timestamp.
      Property TimeStamp As %DateTime [ InitialExpression = {$ZDATETIME($ZTIMESTAMP)} ];
      
      }
      

5. Click the start activity, then open the Add Activity drop-down menu and add a transform activity. The new activity displays in the business process with an arrow connecting it to start. Complete the fields as follows:
   • Name: Transform Message
   • Data Transformation Class: Demo.MQTTMessageToReading
   • Source: request
   • Target: response

   

6. Still in the tab for the transform activity, click DTL Editor to open the Data Transformation Builder, a tool that allows you to quickly transform between different object or message types.
   
   As you can see, this data transformation has already been built. The incoming message has two properties — StringValue and Topic — from which the data transformation populates the PatientID field and the beats per minute, or BPM, field. The Topic field from an MQTT message resembles a directory path such as /acmeHospital/EKG/Patient-1. In this case, the final level of the path is the patient identifier. The data transformation can populate the appropriate field in the HeartRate message by parsing the Topic string and using the final value, delimited by a forward slash (/).
   Other things to note about this data transformation:
   • The data transformation parses the Topic string using the Piece function with a forward slash (/) as the delimiter, and it navigates to the final value.
   • The data transformation connects the StringValue field of the MQTT message to the BPM field with a line. The StringValue field always represents the payload of an MQTT message.
   • There is no need to assign the TimeStamp field, as the ObjectScript class automatically populates this when a record is saved.
     
7. In the Business Process Designer, drag a line from the small dot at the bottom of the transform activity to the end activity, then click Compile.
8. Add this business process to the production by returning to Home > Interoperability > Configure > Production and clicking the plus sign (+) next to Business Processes. Then enter:
   • Business Process Class: Demo.ProcessMQTTMessage
   • Business Process Name: Process_MQTT_Request
   • Enable Now: selected

   

9. Now that your production is ready to receive and persist incoming EKG readings, you can create a business service to subscribe to the MQTT topic to which the readings publish. Click the plus sign (+) next to Services and enter:
   • Service Class: EnsLib.MQTT.Service.Passthrough
   • Service Name: From_EKG_MQTT

   Click OK. Then click the newly created From_EKG_MQTT service. In the Settings tab on the right, enter the following information:

   • Enabled: selected
   • Target Config Names: Process_MQTT_Request
   • Topic: the topic string you stored at the beginning of the exercise
   • URL: tcp://mqtt.eclipseprojects.io/mqtt

   If you did not store your topic string, you can locate it by opening the shared/Samples-MQTT-EKG-Devices/App/app.html file using Open With > Preview. Your topic string will be provided at the top of this page.
   
   Click Apply.

10. Your production will now be able to receive incoming publications from the MQTT broker. As a final step, configure the production to send that information to a live dashboard for near real-time monitoring. To do this, click the plus sign (+) next to Business Services to add another business service with the following specifications:
    • Enabled: selected
    • Service Class: Demo.MetricMQTT
    • Service Name: To_Metric_Dashboard

    Click OK.

11. Under the Basic Settings section for the service, change Call Interval to 1 and click Apply. Next to Production Configuration, click Start.
    Demo.MetricMQTT is a simple business service that runs on a specific interval (in this case, 1) to compile readings and send them on to the built-in analytics dashboard utilities that come with InterSystems IRIS for Health. The business service is a custom-built class that inherits from the BusinessMetric superclass, meaning that it takes all the functionality already built into that superclass and allows you to quickly configure it for your needs.
    You can view the class by looking at Samples-MQTT-EKG-Devices/src/Demo/MetricMQTT.cls in your online sandbox IDE.

View the Data on a Dashboard

Your production now subscribes to MQTT messages on a specific topic, converts them to a full Demo.HeartRate record, and then sends a regular update into the dashboard. Next, you will create a dashboard to view this data.

1. In the Management Portal, navigate to Home > Analytics > User Portal. Click the plus sign (+) at the top, then Add Dashboard. Name the dashboard Patient_EKG_Readings and click OK.
2. Click the arrow on the left to expand the side tab, then click Widgets and the plus sign (+) to create a new widget.
   
3. In the Widget Wizard, click Pivots and Charts > Column Chart. To add the data source, click the magnifying glass to enter the Data Source Selection Wizard.
4. In this wizard, navigate to Business Metrics > Demo.MQTTProduction > To_Metric_Dashboard. Name the widget HeartRate_Chart and click OK.
   
5. This dashboard will now display heart rate data, but the data will remain static if the dashboard does not refresh. To enable auto-refresh, expand the panel on the left by clicking the arrow, then Widgets > HeartRate_Chart > Controls and the plus sign (+). Complete the following fields:
   • Target: *
   • Action: Refresh
   • Type: timer
   • Time: 1

   Click OK.
   
   Click Save at the top of the page.

Test Your Dashboard

You can now test your dashboard by opening the /shared/Samples-MQTT-EKG-Devices/App/app.html file included in this GitHub repository in a browser. If you are using the IDE included with your learning lab, right-click this file, then select Open With > Preview.

Three simulated patients appear with flashing heart rates to indicate their beats per minute (BPM). You can adjust the BPM, and the changes will quickly show on the dashboard you created.

You can also click Add to add a new patient, and your dashboard will update within seconds to include the additional patient.

You have now successfully built a dashboard that monitors remote patient heart rates. For more information on using the MQTT utilities included with InterSystems IRIS for Health, visit InterSystems documentation.