| title | description | author | manager | ms.author | ms.date | ms.topic | ms.service | services |
|---|---|---|---|---|---|---|---|---|
Develop modules for Azure IoT Edge | Microsoft Docs |
Develop custom modules for Azure IoT Edge that can communicate with the runtime and IoT Hub |
kgremban |
philmea |
kgremban |
07/22/2019 |
conceptual |
iot-edge |
iot-edge |
Azure IoT Edge modules can connect with other Azure services and contribute to your larger cloud data pipeline. This article describes how you can develop modules to communicate with the IoT Edge runtime and IoT Hub, and therefore the rest of the Azure cloud.
The IoT Edge runtime provides the infrastructure to integrate the functionality of multiple IoT Edge modules and to deploy them onto IoT Edge devices. Any program can be packaged as an IoT Edge module. To take full advantage of IoT Edge communication and management functionalities, a program running in a module can use the Azure IoT Device SDK to connect to the local IoT Edge hub.
The IoT Edge hub provides two main functionalities: proxy to IoT Hub, and local communications.
IoT Hub sees a module instance analogously to a device, in the sense that:
- it has a module twin that is distinct and isolated from the device twin and the other module twins of that device;
- it can send device-to-cloud messages;
- it can receive direct methods targeted specifically at its identity.
Currently, modules can't receive cloud-to-device messages or use the file upload feature.
When writing a module, you can use the Azure IoT Device SDK to connect to the IoT Edge hub and use the above functionality as you would when using IoT Hub with a device application. The only difference between IoT Edge modules and IoT device applications is that you have to refer to the module identity instead of the device identity.
To enable complex processing of device-to-cloud messages, IoT Edge hub provides declarative routing of messages between modules, and between modules and IoT Hub. Declarative routing allows modules to intercept and process messages sent by other modules and propagate them into complex pipelines. For more information, see deploy modules and establish routes in IoT Edge.
An IoT Edge module, as opposed to a normal IoT Hub device application, can receive device-to-cloud messages that are being proxied by its local IoT Edge hub to process them.
IoT Edge hub propagates the messages to your module based on declarative routes described in the deployment manifest. When developing an IoT Edge module, you can receive these messages by setting message handlers.
To simplify the creation of routes, IoT Edge adds the concept of module input and output endpoints. A module can receive all device-to-cloud messages routed to it without specifying any input, and can send device-to-cloud messages without specifying any output. Using explicit inputs and outputs, though, makes routing rules simpler to understand.
Finally, device-to-cloud messages handled by the Edge hub are stamped with the following system properties:
| Property | Description |
|---|---|
| $connectionDeviceId | The device ID of the client that sent the message |
| $connectionModuleId | The module ID of the module that sent the message |
| $inputName | The input that received this message. Can be empty. |
| $outputName | The output used to send the message. Can be empty. |
Connecting to the local IoT Edge hub from a module involves two steps:
- Create a ModuleClient instance in your application.
- Make sure your application accepts the certificate presented by the IoT Edge hub on that device.
Create a ModuleClient instance to connect your module to the IoT Edge hub running on the device, similar to how DeviceClient instances connect IoT devices to IoT Hub. For more information about the ModuleClient class and its communication methods, see the API reference for your preferred SDK language: C#, C, Python, Java, or Node.js.
IoT Edge supports multiple operating systems, device architectures, and development languages so that you can build the scenario that matches your needs. Use this section to understand your options for developing custom IoT Edge modules. You can learn more about tooling support and requirements for each language in Prepare your development and test environment for IoT Edge.
For all languages in the following table, IoT Edge supports development for AMD64 and ARM32 Linux devices.
| Development language | Development tools |
|---|---|
| C | Visual Studio Code Visual Studio 2017/2019 |
| C# | Visual Studio Code Visual Studio 2017/2019 |
| Java | Visual Studio Code |
| Node.js | Visual Studio Code |
| Python | Visual Studio Code |
Note
Develop and debugging support for ARM64 Linux devices is in public preview. For more information, see Develop and debug ARM64 IoT Edge modules in Visual Studio Code (preview).
For all languages in the following table, IoT Edge supports development for AMD64 Windows devices.
| Development language | Development tools |
|---|---|
| C | Visual Studio 2017/2019 |
| C# | Visual Studio Code (no debugging capabilities) Visual Studio 2017/2019 |
Prepare your development and test environment for IoT Edge
Use Visual Studio to develop C# modules for IoT Edge