Tutorial: Receive device messages through Azure IoT Hub

For enhanced workflows and ease of use, you can use the MedTech service in Azure Health Data Services to receive messages from devices you create and manage through an IoT hub in Azure IoT Hub. This tutorial uses an Azure Resource Manager template (ARM template) and a Deploy to Azure button to deploy a MedTech service. The template creates an IoT hub to create and manage devices, and then routes device messages to an event hub in Azure Event Hubs for the MedTech service to pick up.

In this tutorial, you learn how to:

  • Open an ARM template in the Azure portal.
  • Configure the template for your deployment.
  • Create a device.
  • Send a test message.
  • Review metrics for the test message.

The ARM template that you use to deploy your solution in this tutorial is available at Azure Quickstart Templates by using the azuredeploy.json file on GitHub.

Device message flow

The following diagram demonstrates the IoT device message flow when you use an IoT hub in Azure IoT Hub with the MedTech service in Azure Health Data Services. Devices send messages to your IoT hub. Your IoT hub routes the device messages to the device message event hub in Azure Event Hubs for the MedTech service to pick up. The MedTech service transforms the device messages and persists them in the Fast Healthcare Interoperability Resources (FHIR®) service as FHIR observations. For more information, see MedTech service data flow.

Diagram of the IoT message data flow through an IoT hub and event hub, and then into the MedTech service.

Prerequisites

To begin your deployment and complete the tutorial, you must have the following prerequisites:

  • An active Azure subscription account. If you don't have an Azure subscription, see the subscription decision guide.

  • Owner or Contributor and User Access Administrator role assignments in the Azure subscription. For more information, see What is Azure role-based access control?.

  • The Microsoft.HealthcareApis, Microsoft.EventHub, and Microsoft.Devices resource providers registered with your Azure subscription. To learn more, see Azure resource providers and types.

  • Visual Studio Code installed locally.

  • Azure IoT Tools installed in Visual Studio Code. Azure IoT Tools is a collection of extensions that makes it easy to connect to IoT hubs, create devices, and send messages. In this tutorial, you use the Azure IoT Hub extension in Visual Studio Code to connect to your deployed IoT hub, create a device, and send a test message from the device to your IoT hub.

When you have these prerequisites, you're ready to configure the tutorial template by using the Deploy to Azure button.

Use the Deploy to Azure button

To begin deployment in the Azure portal, select the Deploy to Azure button:

Deploy to Azure

The button calls an ARM template from Azure Quickstart Templates to get information from your Azure subscription environment and begin deploying the MedTech service and Azure IoT Hub by using the Azure portal.

Configure the deployment

  1. In the Azure portal, on the Basics tab of the Azure quickstart template, select or enter the following information for your deployment:

    • Subscription: The Azure subscription to use for the deployment.

    • Resource group: An existing resource group, or you can create a new resource group.

    • Region: The Azure region of the resource group that's used for the deployment. Region auto-fills by using the resource group region.

    • Basename: A value that's appended to the name of the Azure resources and services that are deployed. The examples in this tutorial use the basename azuredocsdemo. You can choose your own basename value.

    • Location: A supported Azure region for Azure Health Data Services (the value can be the same as or different from the region your resource group is in). For a list of Azure regions where Health Data Services is available, see Products available by regions.

    • Fhir Contributor Principle Id (optional): An Azure Active Directory (Azure AD) user object ID to provide read/write permissions in the FHIR service.

      You can use this account to give access to the FHIR service to view the device messages that are generated in this tutorial. We recommend that you use your own Azure AD user object ID, so you can access the messages in the FHIR service. If you choose not to use the Fhir Contributor Principle Id option, clear the text box.

      To learn how to get an Azure AD user object ID, see Find the user object ID. The user object ID that's used in this tutorial is only an example. If you use this option, use your own user object ID or the object ID of another person who you want to be able to access the FHIR service.

    Screenshot that shows deployment options for the MedTech service for Health Data Services in the Azure portal.

    Don't change the default values for Device Mapping and Destination Mapping in this tutorial. The mappings are set in the template to send a device message to your IoT hub later in the tutorial.

    Important

    In this tutorial, the ARM template configures the MedTech service to operate in Create mode. A patient resource and a device resource are created for each device that sends data to your FHIR service.

    To learn more about the MedTech service resolution types Create and Lookup, see Destination properties.

  2. To validate your configuration, select Review + create.

    Screenshot that shows the Review + create button selected in the Azure portal.

  3. In Review + create, check the template validation status. If validation is successful, the template displays Validation Passed. If validation fails, fix the detail that's indicated in the error message, and then select Review + create again.

    Screenshot that shows the Review + create pane displaying the Validation Passed message.

  4. After a successful validation, to begin the deployment, select Create.

    Screenshot that shows the highlighted Create button.

  5. In a few minutes, the Azure portal displays the message that your deployment is completed.

    Screenshot that shows a green checkmark and the message Your deployment is complete.

Review deployed resources and access permissions

When deployment is completed, the following resources and access roles are created in the template deployment:

  • An Azure Event Hubs namespace and a device message event hub. In this deployment, the event hub is named devicedata.

  • An event hub consumer group. In this deployment, the consumer group is named $Default.

  • The Azure Event Hubs Data Sender role. In this deployment, the role is named devicedatasender. The Azure Event Hubs Data Sender role isn't used in this tutorial. To learn more about the role, see Review of deployed resources and access permissions.

  • An instance of Azure IoT Hub with message routing configured to send device messages to the device message event hub.

  • A user-assigned managed identity that provides send access from the IoT hub to the device message event hub. The managed identity has the Azure Event Hubs Data Sender role in the Access control section (IAM) of the device message event hub.

  • A Health Data Services workspace.

  • A Health Data Services FHIR service.

  • An instance of the MedTech service for Health Data Services, with the required system-assigned managed identity roles:

Create a device and send a test message

With your resources successfully deployed, next, you connect to your IoT hub, create a device, and send a test message to the IoT hub. After you complete these steps, your MedTech service can:

  • Pick up the IoT hub-routed test message from the device message event hub.
  • Transform the test message into five FHIR observations.
  • Persist the FHIR observations to your FHIR service.

You complete the steps by using Visual Studio Code with the Azure IoT Hub extension:

  1. Open Visual Studio Code with Azure IoT Tools installed.

  2. In Explorer, in Azure IoT Hub, select and choose Select IoT Hub.

    Screenshot of Visual Studio Code with the Azure IoT Hub extension with the deployed IoT hub selected.

  3. Select the Azure subscription where your IoT hub was provisioned.

  4. Select your IoT hub. The name of your IoT hub is the basename you provided when you provisioned the resources prefixed with ih-. An example hub name is ih-azuredocsdemo.

  5. In Explorer, in Azure IoT Hub, select and choose Create Device. An example device name is iot-001.

    Screenshot that shows Visual Studio Code with the Azure IoT Hub extension with Create device selected.

  6. To send a test message from the device to your IoT hub, right-click the device and select Send D2C Message to IoT Hub.

    Note

    In this device-to-cloud (D2C) example, cloud is the IoT hub in Azure IoT Hub that receives the device message. Azure IoT Hub supports two-way communications. To set up a cloud-to-device (C2D) scenario, select Send C2D Message to Device Cloud.

    Screenshot that shows Visual Studio Code with the Azure IoT Hub extension and the Send D2C Message to IoT Hub option selected.

  7. In Send D2C Messages, select or enter the following values:

    • Device(s) to send messages from: The name of the device you created.

    • Message(s) per device: 1.

    • Interval between two messages: 1 second(s).

    • Message: Plain Text.

    • Edit: Clear any existing text, and then paste the following JSON.

      Tip

      You can use the Copy option in in the right corner of the test message, and then paste it in Edit.

      {
        "HeartRate": 78,
        "RespiratoryRate": 12,
        "HeartRateVariability": 30,
        "BodyTemperature": 98.6,
        "BloodPressure": {
          "Systolic": 120,
          "Diastolic": 80
        }
      }
      
  8. To begin the process of sending a test message to your IoT hub, select Send.

    Screenshot that shows Visual Studio code with the Azure IoT Hub extension with the device message options selected.

    After you select Send, it might take up to five minutes for the FHIR resources to be available in the FHIR service.

    Important

    To avoid device spoofing in D2C messages, Azure IoT Hub enriches all messages with additional properties. For more information, see Anti-spoofing properties and How to use IotJsonPathContentTemplate mappings.

Review metrics from the test message

Now that you've successfully sent a test message to your IoT hub, review your MedTech service metrics. You review metrics to verify that your MedTech service received, transformed, and persisted the test message to your FHIR service. To learn more, see How to display the MedTech service monitoring tab metrics.

For your MedTech service metrics, you can see that your MedTech service completed the following steps for the test message:

  • Number of Incoming Messages: Received the incoming test message from the device message event hub.
  • Number of Normalized Messages: Created five normalized messages.
  • Number of Measurements: Created five measurements.
  • Number of FHIR resources: Created five FHIR resources that are persisted in your FHIR service.

Screenshot that shows a MedTech service metrics tile and test data metrics.

Screenshot that shows a second MedTech service metrics tile and test data metrics.

View test data in the FHIR service

If you provided your own Azure AD user object ID as the optional value for Fhir Contributor Principal ID in the deployment template, you can query FHIR resources in your FHIR service.

To learn how to get an Azure AD access token and view FHIR resources in your FHIR service, see Access by using Postman.

Next steps

In this tutorial, you deployed an ARM template in the Azure portal, connected to your IoT hub in Azure IoT Hub, created a device, and sent a test message to your MedTech service.

To learn how to use device mappings:

To learn more about FHIR destination mappings:

FHIR® is a registered trademark of Health Level Seven International, registered in the U.S. Trademark Office and is used with their permission.