Tutorial: Forward events to IoTHub

This article walks through all the steps needed to forward Event Grid events to other IoT Edge modules, IoTHub using routes. You might want to do it for the following reasons:

  • Continue to use any existing investments already in place with edgeHub's routing
  • Prefer to route all events from a device only via IoT Hub

To complete this tutorial, you need to understand the following concepts:

Prerequisites

In order to complete this tutorial, you will need:

  • Azure subscription - Create a free account if you don't already have one.
  • Azure IoT Hub and IoT Edge device - Follow the steps in the quick start for Linux or Windows devices if you don't already have one.

Deploy Event Grid IoT Edge module

There are several ways to deploy modules to an IoT Edge device and all of them work for Azure Event Grid on IoT Edge. This article describes the steps to deploy Event Grid on IoT Edge from the Azure portal.

Note

In this tutorial, you will deploy the Event Grid module without persistence. It means that any topics and subscriptions you create in this tutorial will be deleted when you redeploy the module. For more information on how to setup persistence, see the following articles: Persist state in Linux or Persist state in Windows. For production workloads, we recommend that you install the Event Grid module with persistence.

Important

In this tutorial, Event Grid module will be deployed with client authentication turned-off, and allow HTTP subscribers. For production workloads, we recommend that you enable only HTTPS requests and subscribers with client authentication enabled. For more information on how to configure Event Grid module securely, see Security and authentication.

Select your IoT Edge device

  1. Sign in to the Azure portal
  2. Navigate to your IoT Hub.
  3. Select IoT Edge from the menu in the Automatic Device Management section.
  4. Click on the ID of the target device from the list of devices
  5. Select Set Modules. Keep the page open. You will continue with the steps in the next section.

Configure a deployment manifest

A deployment manifest is a JSON document that describes which modules to deploy, how data flows between the modules, and desired properties of the module twins. The Azure portal has a wizard that walks you through creating a deployment manifest, instead of building the JSON document manually. It has three steps: Add modules, Specify routes, and Review deployment.

Add modules

  1. In the Deployment Modules section, select Add

  2. From the types of modules in the drop-down list, select IoT Edge Module

  3. Provide the name, image, container create options of the container:

    • Name: eventgridmodule
    • Image URI: mcr.microsoft.com/azure-event-grid/iotedge:latest
    • Container Create Options:
        {
          "Env": [
            "inbound:clientAuth:clientCert:enabled=false",
            "outbound:webhook:httpsOnly=false"
          ],
          "HostConfig": {
            "PortBindings": {
              "4438/tcp": [
                {
                  "HostPort": "4438"
                }
              ]
            }
          }
        }
    
  4. Click Save

  5. Click Next to continue to the routes section

    Note

    If you are using an Azure VM as an edge device, add an inbound port rule to allow inbound traffic on the port 4438. For instructions on adding the rule, see How to open ports to a VM.

Setup routes

Keep the default routes, and select Next to continue to the review section

Review deployment

  1. The review section shows you the JSON deployment manifest that was created based on your selections in the previous two sections. Confirm that you see the two modules in the list: $edgeAgent and $edgeHub. These two modules make up the IoT Edge runtime and are required defaults in every deployment.
  2. Review your deployment information, then select Submit.

Verify your deployment

  1. After you submit the deployment, you return to the IoT Edge page of your IoT hub.
  2. Select the IoT Edge device that you targeted with the deployment to open its details.
  3. In the device details, verify that the Event Grid module is listed as both Specified in deployment and Reported by device.

It may take a few moments for the module to be started on the device and then reported back to IoT Hub. Refresh the page to see an updated status.

Create topic

As a publisher of an event, you need to create an event grid topic. The topic refers to an end point where publishers can then send events to.

  1. Create topic4.json with the following content. See our API documentation for details about the payload.

     {
           "name": "sampleTopic4",
           "properties": {
             "inputschema": "eventGridSchema"
           }
     }
    
  2. Run the following command to create the topic. HTTP Status Code of 200 OK should be returned.

    curl -k -H "Content-Type: application/json" -X PUT -g -d @topic4.json https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic4?api-version=2019-01-01-preview
    
  3. Run the following command to verify topic was created successfully. HTTP Status Code of 200 OK should be returned.

    curl -k -H "Content-Type: application/json" -X GET -g https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic4?api-version=2019-01-01-preview
    

    Sample output:

         [
           {
             "id": "/iotHubs/eg-iot-edge-hub/devices/eg-edge-device/modules/eventgridmodule/topics/sampleTopic4",
             "name": "sampleTopic4",
             "type": "Microsoft.EventGrid/topics",
             "properties": {
               "endpoint": "https://<edge-vm-ip>:4438/topics/sampleTopic4/events?api-version=2019-01-01-preview",
               "inputSchema": "EventGridSchema"
             }
           }
         ]
    

Create event subscription

Subscribers can register for events published to a topic. To receive any event, they'll need to create an Event grid subscription on a topic of interest.

  1. Create subscription4.json with the below content. Refer to our API documentation for details about the payload.

     {
           "properties": {
                 "destination": {
                       "endpointType": "edgeHub",
                       "properties": {
                             "outputName": "sampleSub4"
                       }
                 }
           }
     }
    

    Note

    The endpointType specifies that the subscriber is edgeHub. The outputName specifies the output on which the Event Grid module will route events that match this subscription to edgeHub. For example, events that match the above subscription will be written to /messages/modules/eventgridmodule/outputs/sampleSub4.

  2. Run the following command to create the subscription. HTTP Status Code of 200 OK should be returned.

    curl -k -H "Content-Type: application/json" -X PUT -g -d @subscription4.json https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic4/eventSubscriptions/sampleSubscription4?api-version=2019-01-01-preview
    
  3. Run the following command to verify subscription was created successfully. HTTP Status Code of 200 OK should be returned.

    curl -k -H "Content-Type: application/json" -X GET -g https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic4/eventSubscriptions/sampleSubscription4?api-version=2019-01-01-preview
    

    Sample output:

         {
           "id": "/iotHubs/eg-iot-edge-hub/devices/eg-edge-device/modules/eventgridmodule/topics/sampleTopic4/eventSubscriptions/sampleSubscription4",
           "type": "Microsoft.EventGrid/eventSubscriptions",
           "name": "sampleSubscription4",
           "properties": {
             "Topic": "sampleTopic4",
             "destination": {
                       "endpointType": "edgeHub",
                       "properties": {
                             "outputName": "sampleSub4"
                       }
                 }
           }
         }
    

Set up an edge hub route

Update the edge hub's route to forward event subscription's events to be forwarded to IoTHub as follows:

  1. Sign in to the Azure portal
  2. Navigate to the IoT Hub.
  3. Select IoT Edge from the menu
  4. Select the ID of the target device from the list of devices.
  5. Select Set Modules.
  6. Select Next and to the routes section.
  7. In the routes, add a new route
"fromEventGridToIoTHub":"FROM /messages/modules/eventgridmodule/outputs/sampleSub4 INTO $upstream"

For example,

{
    "routes": {
      "fromEventGridToIoTHub": "FROM /messages/modules/eventgridmodule/outputs/sampleSub4 INTO $upstream"
    }
}

Note

The above route will forward any events matched for this subscription to be forwarded to the IoT hub. You can use the Edge hub routing features to further filter, and route the Event Grid events to other IoT Edge modules.

Setup IoT Hub route

See the IoT Hub routing tutorial to set up a route from the IoT hub so that you can view events forwarded from the Event Grid module. Use true for the query to keep the tutorial simple.

Publish an event

  1. Create event4.json with the following content. See our API documentation for details about the payload.

        [
          {
            "id": "eventId-iothub-1",
            "eventType": "recordInserted",
            "subject": "myapp/vehicles/motorcycles",
            "eventTime": "2019-07-28T21:03:07+00:00",
            "dataVersion": "1.0",
            "data": {
              "make": "Ducati",
              "model": "Monster"
            }
          }
        ]
    
  2. Run the following command to publish event:

    curl -k -H "Content-Type: application/json" -X POST -g -d @event4.json https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic4/events?api-version=2019-01-01-preview
    

Verify event delivery

See the IoT Hub routing tutorial for the steps to view the events.

Cleanup resources

  • Run the following command to delete the topic and all its subscriptions at the edge:

    curl -k -H "Content-Type: application/json" -X DELETE https://<your-edge-device-public-ip-here>:4438/topics/sampleTopic4?api-version=2019-01-01-preview
    
  • Delete any resources created while setting up IoTHub routing in the cloud as well.

Next steps

In this tutorial, you created an event grid topic, edge hub subscription, and published events. Now that you know the basic steps to forward to an edge hub, see the following articles:

  • To troubleshoot issues with using Azure Event Grid on IoT Edge, see Troubleshooting guide.
  • Use edge hub route filters to partition events
  • Set up persistence of Event Grid module on linux or Windows
  • Follow documentation to configure client authentication
  • Forward events to Azure Event Grid in the cloud by following this tutorial