Share via

Tutorial: Conexión de un kit de IoT de ESPRESSIF ESP32-Azure a IoT Hub

  • Artículo

En este tutorial, usará el middleware de IoT de Azure para FreeRTOS para conectar el kit de IoT ESP32-Azure ESPRESSIF (de ahora en adelante, el Kit de desarrollo ESP32) a Azure IoT.

Debe realizar las siguientes tareas:

  • Instalar un conjunto de herramientas de desarrollo insertado para programar un ESP32 DevKit
  • Compilar una imagen e instalarla en ESP32 DevKit
  • Uso de la CLI de Azure para crear y administrar una instancia de Azure IoT Hub a la que el dispositivo ESP32 DevKit se conecta de forma segura
  • Usar Azure IoT Explorer para registrar un dispositivo con su centro de IoT, ver las propiedades del dispositivo, ver la telemetría del dispositivo y llamar a comandos directos en el dispositivo

Requisitos previos

  • Un equipo con Windows 10 o Windows 11
  • Git para clonar el repositorio
  • Hardware
    • ESPRESSIF ESP32-Azure IoT Kit
    • Conector USB 2.0 A macho a cable macho micro USB
    • Conexión Wi-Fi a 2,4 GHz
  • Una suscripción de Azure activa. Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

Preparación del entorno de desarrollo

Instalar las herramientas

Para configurar el entorno de desarrollo, primero debe instalar el entorno de compilación ESPRESSIF ESP-IDF. El instalador incluye todas las herramientas necesarias para clonar, compilar, instalar y supervisar el dispositivo.

Para instalar las herramientas de ESP-IDF:

  1. Descargue e inicie ESP-IDF v5.0 Offline-installer.
  2. Cuando el instalador muestre los componentes que se van a instalar, seleccione todos los componentes y complete la instalación.

Clonación del repositorio

Clone el siguiente repositorio para descargar todo el código de dispositivo de muestra, los scripts de instalación y la documentación del SDK. Si ya ha clonado anteriormente este repositorio, no es necesario que lo haga de nuevo.

Para clonar el repositorio, ejecute el siguiente comando:

git clone --recursive  https://github.com/Azure-Samples/iot-middleware-freertos-samples.git

Para Windows 10 y 11, asegúrese de que las rutas de acceso largas estén habilitadas.

  1. Para habilitar rutas de acceso largas, consulte Habilitación de rutas largas en Windows 10.

  2. En Git, ejecute el siguiente comando en un terminal con permisos de administrador:

    git config --system core.longpaths true

Creación de los componentes de nube

Crear un centro de IoT

Puede usar la CLI de Azure para crear un centro de IoT que controle los eventos y la mensajería del dispositivo.

Para crear un centro de IoT:

  1. Inicie la aplicación de la CLI. Para ejecutar los comandos de la CLI en el resto de este inicio rápido, copie la sintaxis del comando, péguela en la aplicación de la CLI, edite los valores de las variables y presione Entrar.

    • Si usa Cloud Shell, haga clic con el botón derecho en el vínculo de Cloud Shell y seleccione la opción para abrirlo en una nueva pestaña.
    • Si usa la CLI de Azure localmente, inicie la aplicación de consola de la CLI e inicie sesión en la CLI de Azure.

  2. Ejecute az extension add para instalar o actualizar la extensión azure-iot a la versión actual.

    az extension add --upgrade --name azure-iot

  3. Ejecute el comando az group create para crear un grupo de recursos. Con el comando siguiente se crea un grupo de recursos denominado MyResourceGroup en la ubicación centralus.

    Nota

    También puede establecer un parámetro location alternativo. Para ver las ubicaciones disponibles, ejecute az account list-locations.

    az group create --name MyResourceGroup --location centralus

  4. Ejecute el comando az iot hub create para crear una instancia de IoT Hub. La creación de una instancia de IoT Hub puede tardar unos minutos.

    YourIotHubName. Reemplace este marcador de posición en el código por el nombre elegido para el centro de IoT. Un nombre de centro de IoT debe ser único globalmente en Azure. Este marcador de posición se usa en el resto de esta guía de inicio rápido para representar el nombre único del centro de IoT.

    El parámetro --sku F1 crea el centro de IoT en el nivel Gratis. Los centros del nivel Gratis tienen un conjunto de características limitado y se usan para las aplicaciones de prueba de concepto. Para obtener más información sobre los niveles, las características y los precios de IoT Hub, consulte Precios de Azure IoT Hub.

    az iot hub create --resource-group MyResourceGroup --name {YourIoTHubName} --sku F1 --partition-count 2

  5. Una vez creado el centro de IoT, vea la salida JSON en la consola y copie el valor hostName para usarlo en un paso posterior. El valor hostName se parece al del ejemplo siguiente:

    {Your IoT hub name}.azure-devices.net

Configuración de IoT Explorer

En el resto de este inicio rápido, usará IoT Explorer para registrar un dispositivo en un centro de IoT, ver las propiedades y la telemetría de dicho dispositivo, y enviarle comandos. En esta sección, configurará IoT Explorer para conectarse al centro de IoT que ha creado y leer los modelos Plug and Play desde el repositorio de modelos público.

Para agregar una conexión al centro de IoT:

  1. Instalar Azure IoT Explorer. Esta herramienta es una utilidad multiplataforma para supervisar y administrar recursos de Azure IoT.

  2. En la aplicación de la CLI, ejecute el comando az iot hub connection-string show para obtener la cadena de conexión para el centro de IoT.

    az iot hub connection-string  show --hub-name {YourIoTHubName}

  3. Copie la cadena de conexión sin los caracteres de comillas circundantes.

  4. En Azure IoT Explorer, seleccione Centros de IoT en el menú izquierdo.

  5. Seleccione + Agregar conexión.

  6. Pegue la cadena de conexión en el cuadro Cadena de conexión.

  7. Seleccione Guardar.

    Captura de pantalla de la incorporación de una conexión en IoT Explorer.

Si la conexión se realiza correctamente, IoT Explorer cambia a la vista Dispositivos.

Para agregar el repositorio de modelos público:

  1. En IoT Explorer, seleccione Inicio para volver a la vista principal.

  2. En el menú de la izquierda, seleccione Configuración de IoT Plug and Play y, a continuación, seleccione +Agregar y elija Repositorio público en el menú desplegable.

  3. Aparece una entrada para el repositorio de modelos público en https://devicemodels.azure.com.

    Captura de pantalla de la incorporación del repositorio de modelos público en IoT Explorer.

  4. Seleccione Guardar.

Registrar un dispositivo

En esta sección, creará una nueva instancia de dispositivo y la registrará en el centro de IoT que creó. En una sección posterior, usará la información de conexión del dispositivo recién registrado para conectar de forma segura el dispositivo físico.

Para registrar un dispositivo:

  1. En la vista principal de IoT Explorer, seleccione Centros de IoT.

  2. Debería aparecer la conexión que agregó anteriormente. Seleccione View devices in this hub (Ver dispositivos en este centro) debajo de las propiedades de conexión.

  3. Seleccione + Nuevo y escriba un identificador de dispositivo para el dispositivo. Por ejemplo, mydevice. Deje todas las demás propiedades tal cual.

  4. Seleccione Crear.

    Captura de pantalla de una identidad de dispositivo de Azure IoT Explorer.

  5. Use los botones de copia para copiar los campos Id. de dispositivo y Clave principal.

Antes de continuar con la sección siguiente, guarde todos los valores siguientes, recuperados de los pasos anteriores, en lugar seguro. Estos valores se usan en la sección siguiente para configurar el dispositivo.

  • hostName
  • deviceId
  • primaryKey

Preparar el dispositivo

Para conectar ESP32 DevKit a Azure, modifique los valores de configuración, compile la imagen e instálela en el dispositivo.

Configuración del entorno

Para iniciar el entorno de ESP-IDF:

  1. Seleccione Inicio de Windows, busque ESP-IDF 5.0 CMD y ejecútelo.

  2. En ESP-IDF 5.0 CMD, vaya al directorio iot-middleware-freertos-samples que clonó anteriormente.

  3. Vaya al directorio del proyecto de ESP32-Azure IoT Kit demos\projects\ESPRESSIF\aziotkit.

  4. Ejecute el siguiente comando para iniciar el menú de configuración:

    idf.py menuconfig

Adición de configuración

Para agregar la configuración de red inalámbrica:

  1. En ESP-IDF 5.0 CMD, seleccione Azure IoT middleware for FreeRTOS Sample Configuration ---> y presione Entrar.

  2. Establezca las siguientes opciones de configuración con sus credenciales de red inalámbrica local.

    Configuración Valor
    SSID de Wi-Fi {el SSID de Wi-Fi}
    Contraseña de WiFi {la contraseña de Wi-Fi}

  3. Presione Esc para volver al menú anterior.

Para agregar la configuración para conectarse a Azure IoT Hub:

  1. Seleccione Azure IoT middleware for FreeRTOS Main Task Configuration ---> y presione Entrar.

  2. Establezca las siguientes opciones de configuración de Azure IoT en los valores que guardó después de crear los recursos de Azure.

    Configuración Value
    Azure IoT Hub FQDN {el nombre del host}
    Azure IoT Device ID {el identificador del dispositivo}
    Clave de contenido del dispositivo de Azure IoT {la clave principal}

    Nota

    En la opción Azure IoT Authentication Method, confirme que el valor predeterminado de Symmetric Key está seleccionado.

  3. Presione Esc para volver al menú anterior.

Para guardar la configuración:

  1. Presione Mayús+S para abrir las opciones de guardado. Este menú le permite guardar la configuración en un archivo llamado skconfig en el directorio .\aziotkit actual.
  2. Presione Entrar para guardar la configuración.
  3. Presione Entrar para descartar el mensaje de confirmación.
  4. Presione Q para salir del menú de configuración.

Compilación e instalación de la imagen

En esta sección, usará las herramientas de ESP-IDF para compilar, instalar y supervisar eESP32 DevKit a medida que se conecta a Azure IoT.

Nota

En los siguientes comandos de esta sección, use una ruta de acceso de salida de compilación corta cerca del directorio raíz. Especifique la ruta de acceso de compilación después del parámetro -B en cada comando que lo requiera. La ruta de acceso corta ayuda a evitar un problema actual en las herramientas de ESPRESSIF ESP-IDF que pueden provocar errores con nombres de ruta de acceso de compilación largos. Los comandos siguientes usan una ruta de acceso local C:\espbuild como ejemplo.

Para compilar la imagen:

  1. En ESP-IDF 5.0 CMD, en el directorio iot-middleware-freertos-samples\demos\projects\ESPRESSIF\aziotkit, ejecute el siguiente comando para crear la imagen.

    idf.py --no-ccache -B "C:\espbuild" build

  2. Una vez completada la compilación, confirme que el archivo de imagen binaria se creó en la ruta de acceso de compilación que especificó anteriormente.

    C:\espbuild\azure_iot_freertos_esp32.bin

Para instalar la imagen:

  1. En ESP32 DevKit, busque el puerto micro USB, que se resalta en la siguiente imagen:

    Foto de la placa del kit de ESP32-Azure IoT.

  2. Conecte el cable micro USB al puerto micro USB de ESP32 DevKit y, luego, conéctelo al equipo.

  3. Abra el administrador de dispositivos de Windows y vea los Puertos para saber a qué puerto COM está conectado ESP32 DevKit.

    Captura de pantalla del Administrador de dispositivos de Windows en la que se muestra el puerto COM para un dispositivo conectado.

  4. En ESP-IDF 5.0 CMD, ejecute el siguiente comando y reemplace el marcador de posición <Your-COM-port> y los corchetes por el puerto COM correcto del paso anterior. Por ejemplo, reemplace el marcador de posición por COM3.

    idf.py --no-ccache -B "C:\espbuild" -p <Your-COM-port> flash

  5. Confirme que la salida se completa con el texto siguiente para una instalación correcta:

    Hash of data verified

Leaving...
Hard resetting via RTS pin...
Done

Para confirmar que el dispositivo se conecta a Azure IoT Central:

  1. En ESP-IDF 5.0 CMD, ejecute el siguiente comando para iniciar la herramienta de supervisión. Como hizo en un comando anterior, reemplace el marcador de posición <Your-COM-port> y los corchetes por el puerto COM al que está conectado el dispositivo.

    idf.py -B "C:\espbuild" -p <Your-COM-port> monitor

  2. Compruebe si hay bloques de salida repetidos similares al ejemplo siguiente. Esta salida confirma que el dispositivo se conecta a Azure IoT y envía telemetría.

    I (50807) AZ IOT: Successfully sent telemetry message
I (50807) AZ IOT: Attempt to receive publish message from IoT Hub.

I (51057) MQTT: Packet received. ReceivedBytes=2.
I (51057) MQTT: Ack packet deserialized with result: MQTTSuccess.
I (51057) MQTT: State record updated. New state=MQTTPublishDone.
I (51067) AZ IOT: Puback received for packet id: 0x00000008
I (53067) AZ IOT: Keeping Connection Idle...

Visualización de las propiedades del dispositivo

Puede usar Azure IoT Explorer para ver y administrar las propiedades de los dispositivos. En las siguientes secciones, usará las funcionalidades Plug and Play que se muestran en IoT Explorer para administrar ESP32 DevKit e interactuar con este. Estas funcionalidades se basan en el modelo de dispositivo publicado para ESP32 DevKit en el repositorio de modelos público. Ha configurado IoT Explorer para buscar este repositorio para los modelos de dispositivo anteriores en este tutorial. En muchos casos se puede realizar la misma acción sin Plug and Play; solo hay que seleccionar las opciones del menú de IoT Explorer. Sin embargo, el uso de Plug and Play suele proporcionar una experiencia mejorada. IoT Explorer puede leer el modelo de dispositivo especificado por un dispositivo Plug and Play y presentar información específica de este.

Para acceder a componentes de IoT Plug and Play del dispositivo en IoT Explorer:

  1. En la vista principal de IoT Explorer, seleccione Centros de IoT y, a continuación, seleccione View devices in this hub (Ver dispositivos en este centro).

  2. Seleccione el dispositivo.

  3. Seleccione Componentes de IoT Plug and Play.

  4. Haga clic en Default component (Componente predeterminado). IoT Explorer muestra los componentes de IoT Plug and Play implementados en el dispositivo.

    Captura de pantalla del componente predeterminado del dispositivo en IoT Explorer.

  5. En la pestaña Interfaz, vea el contenido JSON en el campo Descripción del modelo de dispositivo. El archivo JSON contiene detalles de configuración de cada uno de los componentes de IoT Plug and Play del modelo de dispositivo.

    Cada pestaña de IoT Explorer corresponde a uno de los componentes de IoT Plug and Play del modelo de dispositivo.

    Pestaña Tipo Nombre Descripción
    Interfaz Interfaz Espressif ESP32 Azure IoT Kit Modelo de dispositivo de ejemplo de ESP32 DevKit
    Propiedades (grabable) Propiedad telemetryFrequencySecs Intervalo en que el dispositivo envía telemetría.
    Comandos Comando ToggleLed1 Enciende o apaga la luz LED.
    Comandos Comando ToggleLed2 Enciende o apaga la luz LED.
    Comandos Comando DisplayText Muestra el texto enviado en la pantalla del dispositivo.

Para ver y editar las propiedades del dispositivo mediante Azure IoT Explorer:

  1. Seleccione la pestaña Propiedades (grabable) . Muestra el intervalo en que se envía la telemetría.

  2. Cambie el valor de telemetryFrequencySecs a 5 y, luego, seleccione Update desired value. El dispositivo ahora usa este intervalo para enviar telemetría.

    Captura de pantalla de la configuración del intervalo de telemetría en el dispositivo en IoT Explorer.

  3. IoT Explorer responde con una notificación.

Para usar la CLI de Azure para ver las propiedades del dispositivo:

  1. En la consola de la CLI, ejecute el comando az iot hub device-twin show.

    az iot hub device-twin show --device-id mydevice --hub-name {YourIoTHubName}

  2. Inspeccione las propiedades del dispositivo en la salida de la consola.

Sugerencia

También puede usar Azure IoT Explorer para ver las propiedades del dispositivo. En el menú de navegación de la izquierda, seleccione Device twin.

Ver datos de telemetría

Con Azure IoT Explorer, puede ver el flujo de telemetría del dispositivo a la nube. También realizar la misma tarea mediante la CLI de Azure.

Para ver la telemetría en Azure IoT Explorer:

  1. En el panel Componentes de IoT Plug and Play (componente predeterminado) del dispositivo en IoT Explorer, seleccione la pestaña Telemetría. Confirme que Use built-in event hub (Usar centro de eventos integrado) está establecido en Sí.

  2. Seleccione Inicio.

  3. Vea la telemetría a medida que el dispositivo envía mensajes a la nube.

    Captura de pantalla de la telemetría del dispositivo en IoT Explorer.

  4. Active la casilla Mostrar eventos modelados para ver los eventos en el formato de datos especificado por el modelo de dispositivo.

    Captura de pantalla de eventos de telemetría modelados en IoT Explorer.

  5. Seleccione Detener para dejar de recibir eventos.

Para usar la CLI de Azure para ver la telemetría del dispositivo:

  1. Ejecute el comando az iot hub monitor-events. Use los nombres que creó anteriormente en Azure IoT para el dispositivo IoT Hub.

    az iot hub monitor-events --device-id mydevice --hub-name {YourIoTHubName}

  2. Vea la salida JSON en la consola.

    {
    "event": {
        "origin": "mydevice",
        "module": "",
        "interface": "dtmi:azureiot:devkit:freertos:Esp32AzureIotKit;1",
        "component": "",
        "payload": "{\"temperature\":28.6,\"humidity\":25.1,\"light\":116.66,\"pressure\":-33.69,\"altitude\":8764.9,\"magnetometerX\":1627,\"magnetometerY\":28373,\"magnetometerZ\":4232,\"pitch\":6,\"roll\":0,\"accelerometerX\":-1,\"accelerometerY\":0,\"accelerometerZ\":9}"
    }
}

  3. Seleccione CTRL + C para finalizar la supervisión.

Llamar a un método directo en un dispositivo

También puede usar Azure IoT Explorer para llamar a un método directo que haya implementado en el dispositivo. Los métodos directos tienen un nombre y, opcionalmente, pueden tener una carga de JSON, una conexión configurable y un tiempo de espera del método. En esta sección, se llama a un método que le permite apagar o encender una luz LED. También realizar la misma tarea mediante la CLI de Azure.

Para llamar a un método en Azure IoT Explorer:

  1. En el panel Componentes de IoT Plug and Play (componente predeterminado) del dispositivo en IoT Explorer, seleccione la pestaña Comandos.

  2. En el comando ToggleLed1, seleccione Send command. El indicador LED de ESP32 DevKit se enciende o apaga. También debería ver una notificación en IoT Explorer.

    Captura de pantalla de la llamada al método setLedState en IoT Explorer.

  3. En el comando DisplayText, escriba texto en el campo content.

  4. Seleccione Enviar comando. El texto se muestra en la pantalla de ESP32 DevKit.

Para usar la CLI de Azure para llamar a un método:

  1. Ejecute el comando az iot hub invoke-device-method y especifique el nombre y la carga del método. Con este método, al establecer method-payload en true significa que el LED cambia al estado opuesto al actual.

    az iot hub invoke-device-method --device-id mydevice --method-name ToggleLed2 --method-payload true --hub-name {YourIoTHubName}

    La consola de la CLI muestra el estado de la llamada al método en el dispositivo, donde 200 indica que se ha realizado correctamente.

    {
  "payload": {},
  "status": 200
}

  2. Compruebe el dispositivo para confirmar el estado de la luz LED.

Solución de problemas y depuración

Si tiene problemas para compilar el código del dispositivo, guardar la imagen en la memoria flash del dispositivo o conectarse, consulte Solución de problemas.

Para depurar la aplicación, consulte Depuración con Visual Studio Code.

Limpieza de recursos

Si ya no necesita los recursos de Azure creados en esta guía de inicio rápido, puede usar la CLI de Azure para eliminar el grupo de recursos y todos los recursos que contiene.

Importante

La eliminación de un grupo de recursos es irreversible. El grupo de recursos y todos los recursos contenidos en él se eliminan permanentemente. Asegúrese de no eliminar por accidente el grupo de recursos o los recursos equivocados.

Para eliminar un grupo de recursos por el nombre:

  1. Ejecute el comando az group delete. Este comando quita el grupo de recursos, el centro de IoT y el registro del dispositivo que ha creado.

    az group delete --name MyResourceGroup

  2. Ejecute el comando az group list para confirmar que se ha eliminado el grupo de recursos.

    az group list

Pasos siguientes

En este tutorial, ha creado una imagen personalizada que contiene el middleware de Azure IoT para el código de ejemplo FreeRTOS y, a continuación, ha instalado la imagen en el dispositivo ESP32 DevKit. Ha conectado el dispositivo ESP32 DevKit a Azure IoT Hub y ha llevado a cabo tareas como ver la telemetría y llamar a métodos en el dispositivo.

Como paso siguiente, explore el siguiente artículo para obtener más información sobre las opciones de desarrollo insertadas.

Más información sobre cómo conectar dispositivos insertados con el SDK de C y el SDK de C insertado