Azure IoT Edge Hierarchy Module

The Azure IoT Edge Hierarchy Module is an example module that can be deployed to Azure IoT Edge to create a hierarchy of edges. This module uses the transparent gateway pattern.

Prerequisite

A good understanding of how Azure IoT Edge and IoT Hub work and some experience with deploying and developing custom Edge Modules.

How to build the module

Clone this repo and and open the folder in Visual Studio Code (with Azure IoT Tools extension installed).

1. Once opened in VS Code rename the file "module.template.json" to "module.json" and replace <your container registry> with the name of your container registry.
2. Right-click the "module.json" file and select "Build and Push IoT Edge Image".

How to deploy

A hierarchy of IoT Edges can be setup using the transparant gateway approach. For more detailed information, see How an IoT Edge device can be used as a gateway, which gives a conceptual overview: [https://docs.microsoft.com/en-us/azure/iot-edge/iot-edge-as-gateway].

Follow the steps below to create a hierarchy of two IoT Edge's:

1. Deploy two IoT Edge's (See [https://docs.microsoft.com/en-us/azure/iot-edge/how-to-install-iot-edge-linux] for a Linux setup). One will act an upstream edge and one will act as a downstream edge. The downstream edge will send its messages to the upstream edge. The upstream edge will then send the message to $upstream.
2. Follow the walk-through to use the upstream edge as a transparent gateway: [https://docs.microsoft.com/en-us/azure/iot-edge/how-to-create-transparent-gateway]
3. Follow the steps as described in the "Connect a downstream device to an Azure IoT Edge gateway" tutorial on the downstream edge: [https://docs.microsoft.com/en-us/azure/iot-edge/how-to-connect-downstream-device#install-certificates-using-the-os], but make sure you copy the certificate file to the directory "/edge-ca-cert".
4. Deploy your EdgeHierarchyModule to the downstream edge using the steps as described in: [https://docs.microsoft.com/en-us/azure/iot-edge/how-to-deploy-modules-portal].

5. Set the Container Create Options to:

   {
     "HostConfig": {
       "Binds": [
         "/edge-ca-cert:/edge-ca-cert"
       ],
       "ExtraHosts": [
         "<name of your upstream edge>:<ip address upstream edge>"
       ]
     }
   }
   

   ExtraHosts is used to ensure the downstream edge can do the name resolution, as Moby doesn't support local dns. This only works if you use fixed IP addresses for the edges. You can also setup Moby to include the local dns [See Docker Container Networking for more info: https://docs.docker.com/config/containers/container-networking/].

6. And set the environment variables:

   DOWNSTREAM_CONNECTIONSTRING = "<Your IoT downstream edge connection string>;GatewayHostName=<name of your upstream edge>"
   CERTIFICATE_FILENAME="<name of your certificate file>"
   

7. Deploy the "Simulated Temperature Sensor" on the downstream edge using the approach as describe here: [https://docs.microsoft.com/en-us/azure/iot-edge/quickstart-linux#deploy-a-module]
8. Setup the route on the downstream edge to the EdgeHierarchyModule to ensure all data goes to the upstream IoT Edge:

   {
     "routes": {
       "upstream": "FROM /messages/modules/SimulatedTemperatureSensor/* INTO BrokeredEndpoint(\"/modules/EdgeHierarchyModule/inputs/upstream\")"
     }
   }
   

9. And submit all the changes.

You can now start monitoren your messages coming into the IoT Hub.

Gotchas

There are some gotchas:

1. If you use the EdgeHierarchyModule to send messages to an upstream edge, the store and forward isn't active for these messages on the downstream edge.
2. The downstream edge can still use the $upstream route to send messages directly to the IoT Hub.
3. The messages sent through the upstream edge won't have a module associated. So if you want to route messages from a downstream edge you can follow this instruction: [https://docs.microsoft.com/en-us/azure/iot-edge/how-to-create-transparent-gateway#route-messages-from-downstream-devices]. You need to also take this into account when processing messages in the cloud.

Contributing

This project welcomes contributions and suggestions. This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [[email protected]](mailto:[email protected]) with any additional questions or comments.