Desarrollar sus propios módulos de IoT Edge

Afecta a: icono Sí IoT Edge 1.1 Otras versiones: IoT Edge 1.2

Afecta a: icono Sí IoT Edge 1.2 Otras versiones: IoT Edge 1.1

Los módulos de Azure IoT Edge pueden conectarse con otros servicios de Azure y contribuir a la mayor canalización de datos en la nube. En este artículo se describe cómo puede desarrollar módulos para comunicarse con el entorno de ejecución de IoT Edge e IoT Hub y, por lo tanto, el resto de la nube de Azure.

Entorno de tiempo de ejecución de IoT Edge

El entorno de tiempo de ejecución de IoT Edge proporciona la infraestructura para integrar la funcionalidad de varios módulos de IoT Edge e implementarlos en dispositivos IoT Edge. Todos los programas se pueden empaquetar como un módulo de IoT Edge. Para aprovechar al máximo las funcionalidades de comunicación y administración de IoT Edge, un programa que se ejecute en un módulo puede usar el SDK de dispositivos IoT de Azure para conectarse al centro de IoT Edge local.

Los módulos también pueden usar cualquier cliente MQTT para conectarse al agente MQTT del centro de IoT Edge local.

Empaquetado del programa como módulo de IoT Edge

Para implementar el programa en un dispositivo IoT Edge, primero debe incluirse en contenedores y ejecutarse con un motor compatible con Docker. IoT Edge usa Moby, el proyecto de código abierto que subyace a Docker, como motor compatible con Docker. Los mismos parámetros que se usan con Docker se pueden pasar a los módulos de IoT Edge. Para más información, consulte Configuración de las opciones de creación de contenedores para módulos de IoT Edge.

Uso del centro de IoT Edge

El centro de IoT Edge proporciona dos funcionalidades principales: proxy a IoT Hub y comunicaciones locales.

Conexión al centro de IoT Edge desde un módulo

La conexión al centro de IoT Edge local desde un módulo implica los mismos pasos de conexión que para los clientes. Para obtener más información, consulte Conexión al centro de IoT Edge.

Para usar el enrutamiento de IoT Edge a través de AMQP o MQTT, puede usar ModuleClient desde el SDK de Azure IoT. Crear una instancia de ModuleClient para conectar el módulo al centro de IoT Edge que se ejecuta en el dispositivo, de forma similar a cómo las instancias de DeviceClient conectan dispositivos IoT a IoT Hub. Para más información sobre la clase ModuleClient y sus métodos de comunicación, consulte la referencia de API de su lenguaje preferido para el SDK: C#, C, Python, Java o Node.js.

Para usar el agente MQTT de IoT Edge, debe traer su propio cliente MQTT e iniciar la conexión usted mismo con la información que recupere de la API de carga de trabajo del demonio de IoT Edge.

Para obtener más información sobre cómo elegir entre el enrutamiento o la publicación/suscripción con el agente MQTT, consulte Comunicación local.

Primitivos del agente MQTT

Envío de un mensaje en un tema definido por el usuario

Con el agente MQTT de IoT Edge, puede publicar mensajes en cualquier tema definido por el usuario. Para ello, autorice el módulo para que publique en temas concretos y, a continuación, obtenga un token de la API de carga de trabajo para usarlo como contraseña al conectarse al agente MQTT y, por último, publique mensajes en los temas autorizados con el cliente MQTT de su elección.

Recepción de mensajes en un tema definido por el usuario

Con el agente MQTT de IoT Edge, la recepción de mensajes es similar. En primer lugar, asegúrese de que el módulo esté autorizado a suscribirse a temas específicos, a continuación, obtenga un token de la API de cargas de trabajo para usarlo como contraseña al conectarse al agente MQTT y, por último, suscríbase a los mensajes de los temas autorizados con el cliente MQTT de su elección.

Primitivos de IoT Hub

IoT Hub considera una instancia de módulo de forma análoga a un dispositivo, en el sentido de que:

Actualmente, los módulos no pueden recibir mensajes de nube a dispositivo ni usar la característica de carga de archivos.

Al escribir un módulo, puede conectarse al centro de IoT Edge y usar los primitivos de IoT Hub como lo haría al usar IoT Hub con una aplicación de dispositivo. La única diferencia entre los módulos de IoT Edge y las aplicaciones de dispositivos IoT es que tiene que hacer referencia a la identidad de módulo en lugar de a la identidad del dispositivo.

Mensajes de dispositivo a nube

Un módulo de IoT Edge puede enviar mensajes a la nube a través del centro de IoT Edge que actúa como agente local y propaga los mensajes a la nube. Para habilitar el procesamiento complejo de mensajes del dispositivo a la nube, un módulo de IoT Edge también puede interceptar y procesar los mensajes enviados por otros módulos o dispositivos a su centro de IoT Edge local y enviar mensajes nuevos con datos procesados. Por tanto, se pueden crear cadenas de módulos de IoT Edge para compilar canalizaciones de procesamiento local.

Para enviar mensajes de telemetría del dispositivo a la nube mediante el enrutamiento, use ModuleClient del SDK de Azure IoT. Con el SDK de Azure IoT, cada módulo tiene el concepto de puntos de conexión de entrada y salida del módulo, que se asignan a temas de MQTT especiales. Use el método ModuleClient.sendMessageAsync, y este enviará mensajes en el punto de conexión de salida del módulo. A continuación, configure una ruta en edgeHub para enviar este punto de conexión de salida a IoT Hub.

El envío de mensajes de telemetría del dispositivo a la nube con el agente MQTT es similar a la publicación de mensajes en temas definidos por el usuario, pero con el siguiente tema especial de IoT Hub para el módulo: devices/<device_name>/modules/<module_name>/messages/events. Las autorizaciones deben estar configuradas correctamente. El puente MQTT también debe estar configurado para reenviar los mensajes de este tema a la nube.

Para procesar mensajes mediante el enrutamiento, configure primero una ruta para enviar mensajes procedentes de otro punto de conexión (módulo o dispositivo) al punto de conexión de entrada del módulo y, a continuación, escuche los mensajes en el punto de conexión de entrada del módulo. Cada vez que vuelve un mensaje nuevo, el SDK de Azure IoT desencadena una función de devolución de llamada. Procese el mensaje con esta función de devolución de llamada y, opcionalmente, envíe mensajes nuevos en la cola de puntos de conexión del módulo.

El procesamiento de mensajes con el agente MQTT es similar a suscribirse a mensajes en temas definidos por el usuario, pero mediante los temas especiales de IoT Edge de la cola de salida del módulo: devices/<device_name>/modules/<module_name>/messages/events. Las autorizaciones deben estar configuradas correctamente. De manera opcional, puede enviar mensajes nuevos en los temas de su elección.

Gemelos

Los gemelos son uno de los primitivos proporcionados por IoT Hub. Hay documentos JSON que almacenan información acerca del estado, incluidos metadatos, configuraciones y condiciones. Cada módulo o dispositivo tiene su propio gemelo.

Para obtener un módulo gemelo con el SDK de Azure IoT, llame al método ModuleClient.getTwin.

Para obtener un módulo gemelo con cualquier cliente MQTT, se necesita algo más de trabajo, ya que obtener un gemelo no es un patrón MQTT típico. El módulo primero debe suscribirse al tema especial de IoT Hub $iothub/twin/res/#. El nombre de este tema se hereda de IoT Hub, y todos los dispositivos o módulos deben suscribirse al mismo tema. No significa que los dispositivos reciban los gemelos unos de otros. IoT Hub y edgeHub saben qué gemelo se debe entregar y dónde, incluso si todos los dispositivos escuchan el mismo nombre de tema. Una vez que se realice la suscripción, el módulo debe solicitar el gemelo mediante la publicación de un mensaje en el siguiente tema especial de IoT Hub con un identificador de solicitud $iothub/twin/GET/?$rid=1234. Este identificador de solicitud es un identificador arbitrario (es decir, un GUID), que IoT Hub devolverá junto con los datos solicitados. Así es como un cliente puede emparejar sus solicitudes con las respuestas. El código de resultado es un código de estado de tipo HTTP, donde se codifica correctamente como 200.

Para recibir una revisión de módulo gemelo con el SDK de Azure IoT, implemente una función de devolución de llamada y regístrela con el método ModuleClient.moduleTwinCallback desde el SDK de Azure IoT para que la función de devolución de llamada se desencadene cada vez que ingrese la revisión de un gemelo.

Para recibir una revisión de módulo gemelo con cualquier cliente MQTT, el proceso es muy similar al de recibir gemelos completo: un cliente tiene que suscribirse a un tema especial de IoT Hub $iothub/twin/PATCH/properties/desired/#. Una vez realizada la suscripción, cuando IoT Hub envía un cambio de la sección deseada del gemelo, el cliente la recibe.

Recepción de métodos directos

Para recibir un método directo con el SDK de Azure IoT, implemente una función de devolución de llamada y regístrela con el método ModuleClient.methodCallback desde el SDK de Azure IoT para que la función de devolución de llamada se desencadene cada vez que ingrese un método directo.

Para recibir un método directo con cualquier cliente MQTT, el proceso es muy similar a recibir revisiones de gemelos. El cliente debe confirmar que ha recibido la llamada y puede devolver cierta información al mismo tiempo. El tema especial de IoT Hub al que hay que suscribirse es $iothub/methods/POST/#.

Compatibilidad de idiomas y arquitecturas

IoT Edge admite varios sistemas operativos, arquitecturas de dispositivos y lenguajes de desarrollo para que pueda crear el escenario que más se ajuste a sus necesidades. Use esta sección para conocer las distintas opciones para desarrollar módulos de IoT Edge personalizados. Puede obtener más información acerca la compatibilidad de las herramientas y de los requisitos de cada lenguaje en Preparación del entorno de desarrollo y prueba para IoT Edge.

Linux

En todos los idiomas de la tabla siguiente, IoT Edge admite el desarrollo para contenedores de Linux AMD64 y ARM32.

Lenguaje de desarrollo Herramientas de desarrollo
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

Nota

El soporte técnico del desarrollo y depuración para contenedores de Linux ARM64 está en versión preliminar pública. Para más información, consulte Desarrollo y depuración de módulos ARM64 IoT Edge en Visual Studio Code (versión preliminar).

Windows

En todos los idiomas de la tabla siguiente, IoT Edge admite el desarrollo para contenedores de Windows AMD64.

Lenguaje de desarrollo Herramientas de desarrollo
C Visual Studio 2017/2019
C# Visual Studio Code (sin funcionalidades de depuración)
Visual Studio 2017/2019

IoT Edge 1.1 LTS es el último canal de versión compatible con los contenedores de Windows. A partir de la versión 1.2, no se admiten los contenedores de Windows.

Para obtener información sobre el desarrollo con contenedores de Windows, consulte la versión 1.1 de IoT Edge de este artículo.

Seguridad del módulo

Debe desarrollar los módulos pensando en la seguridad. Para más información sobre cómo proteger los módulos, consulte Seguridad de Docker.

Para ayudar a mejorar la seguridad de los módulos, IoT Edge deshabilita algunas características de contenedor de forma predeterminada. Puede invalidar los valores predeterminados para proporcionar funcionalidades con privilegios a los módulos si es necesario.

Permitir permisos elevados de Docker

En el archivo config.toml de un dispositivo IoT Edge, hay un parámetro denominado allow_elevated_docker_permissions. Cuando se establece en true, esta marca permite la marca --privileged, así como funcionalidades adicionales que se definen en el campo CapAdd de Docker HostConfig en las opciones de creación de contenedores.

Nota

Actualmente, esta marca es true forma predeterminada, lo que permite a las implementaciones conceder permisos con privilegios a los módulos. Se recomienda establecer esta marca en false para mejorar la seguridad del dispositivo. En el futuro, esta marca se establecerá en false de forma predeterminada.

Habilitación de CAP_CHOWN y CAP_SETUID

Las funcionalidades CAP_CHOWN y CAP_SETUID de Docker están deshabilitadas de forma predeterminada. Estas funcionalidades se pueden usar para escribir en archivos seguros en el dispositivo host y obtener acceso raíz.

Si necesita estas funcionalidades, puede volver a habilitarlas manualmente mediante CapADD en las opciones de creación del contenedor.

Pasos siguientes

Preparación del entorno de desarrollo y prueba para IoT Edge

Uso de Visual Studio para desarrollar módulos de C# para IoT Edge

Uso de Visual Studio Code para desarrollar módulos para IoT Edge

Información y uso de los SDK de Azure IoT Hub