Tutorial: Uso de Eclipse ThreadX para conectar un kit de desarrollo de MXCHIP AZ3166 a IoT Hub

  • Artículo

Examinar el código

En este tutorial va a usar Eclipse ThreadX para conectar un kit de desarrollo de IoT para MXCHIP AZ3166 (en lo sucesivo, MXCHIP DevKit) a Azure IoT.

Debe realizar las siguientes tareas:

  • Instalar un conjunto de herramientas de desarrollo insertado para programar el dispositivo MXCHIP DevKit en C
  • Compilar una imagen y guardarla en la memoria flash en MXCHIP DevKit
  • Uso de la CLI de Azure para crear y administrar una instancia de Azure IoT Hub a la que el dispositivo MXCHIP DevKit se conectará 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

  • Una suscripción de Azure activa. Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.

  • Git para clonar el repositorio

  • Azure CLI. Tiene dos opciones para ejecutar comandos de la CLI de Azure en este tutorial:

    • Use Azure Cloud Shell, un shell interactivo que ejecuta comandos de la CLI en el explorador. Esta opción se recomienda porque no es necesario instalar nada. Si usa Cloud Shell por primera vez, inicie sesión en Azure Portal. Siga los pasos descritos en el inicio rápido de Cloud Shell para iniciar Cloud Shell y seleccionar el entorno Bash.
    • Opcionalmente, ejecute la CLI de Azure en su equipo local. Si la CLI de Azure ya está instalada, ejecute az upgrade para actualizar la CLI y las extensiones a la versión actual. Para instalar la CLI de Azure, consulte Instalación de la CLI de Azure.

  • Hardware

Preparación del entorno de desarrollo

Para configurar el entorno de desarrollo, primero debe clonar un repositorio de GitHub que contenga todos los recursos que necesita para el tutorial. Luego, instalará un conjunto de herramientas de programación.

Clonación del repositorio

Clone el siguiente repositorio para descargar todo el código de dispositivo de ejemplo, los scripts de instalación y las versiones sin conexión de la documentación. Si ya ha clonado anteriormente este repositorio en otro tutorial, no es necesario que lo haga de nuevo.

Para clonar el repositorio, ejecute el siguiente comando:

git clone --recursive https://github.com/eclipse-threadx/getting-started.git

Instalar las herramientas

El repositorio clonado contiene un script de instalación que instala y configura las herramientas necesarias. Si ha instalado estas herramientas en otro tutorial de dispositivo insertado, no es necesario volver a hacerlo.

Nota:

El script de instalación instala las siguientes herramientas:

  • CMake: compilación
  • ARM GCC: compilación
  • Termite: supervisión de la salida del puerto serie de los recursos de dispositivos conectados

Para instalar las herramientas:

  1. En el Explorador de archivos, vaya a la siguiente ruta de acceso en el repositorio y ejecute el script de instalación denominado get-toolchain.bat:

    getting-started\tools\get-toolchain.bat

  2. Después de la instalación, abra una nueva ventana de consola para reconocer los cambios de configuración realizados con el script de instalación. Use esta consola para realizar el resto de tareas de programación del tutorial. Puede usar la línea de comandos de Windows, PowerShell o Git Bash para Windows.

  3. Ejecute el código siguiente para confirmar la instalación de CMake versión 3.14 o posterior.

    cmake --version

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 MXCHIP DevKit a Azure, modificará un archivo de configuración de las opciones de Wi-Fi y Azure IoT, recompilará la imagen y la guardará en la memoria flash en el dispositivo.

Adición de configuración

  1. Abra el siguiente archivo en un editor de texto:

    getting-started\MXChip\AZ3166\app\azure_config.h

  2. Comente la siguiente línea cerca de la parte superior del archivo como se muestra:

    // #define ENABLE_DPS

  3. Establezca las constantes Wi-Fi en los siguientes valores del entorno local.

    Nombre invariable Value
    WIFI_SSID {el SSID de Wi-Fi}
    WIFI_PASSWORD {la contraseña de Wi-Fi}
    WIFI_MODE {uno de los valores de modo Wi-Fi enumerados en el archivo}

  4. Establezca las constantes de información del dispositivo de Azure IoT en los valores que guardó después de crear los recursos de Azure.

    Nombre invariable Value
    IOT_HUB_HOSTNAME {Su valor de nombre de host}
    IOT_HUB_DEVICE_ID {el valor de identificador de dispositivo}
    IOT_DEVICE_SAS_KEY {el valor de la clave principal}

  5. Guarde y cierre el archivo.

Compilación de la imagen

  1. En la consola o en el Explorador de archivos, ejecute el script rebuild.bat en la siguiente ruta de acceso para compilar la imagen:

    getting-started\MXChip\AZ3166\tools\rebuild.bat

  2. Una vez finalizada la compilación, confirme que el archivo binario se ha creado en la siguiente ruta de acceso:

    getting-started\MXChip\AZ3166\build\app\mxchip_azure_iot.bin

Guardar la imagen en la memoria flash

  1. En MXCHIP DevKit, busque el botón Reset (Restablecer) y el puerto micro USB. Usará estos componentes en los pasos siguientes. Ambos se resaltan en la siguiente imagen:

    Búsqueda de componentes clave en la placa del kit de desarrollo de MXChip

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

  3. En el Explorador de archivos, busque el archivo binario que creó en la sección anterior.

  4. Copie el archivo binario mxchip_azure_iot.bin.

  5. En el Explorador de archivos, busque el dispositivo MXCHIP DevKit conectado al equipo. El dispositivo aparece como una unidad en el sistema con la etiqueta AZ3166.

  6. Pegue el archivo binario en la carpeta raíz de MXCHIP DevKit. El almacenamiento en la memoria flash comienza inmediatamente y termina al cabo de unos segundos.

    Nota

    Durante este proceso, una luz LED verde se enciende y se apaga en MXCHIP DevKit.

Confirmación de los detalles de conexión del dispositivo

Puede usar la aplicación Termite para supervisar la comunicación y confirmar que el dispositivo está configurado correctamente.

  1. Inicie Termite.

    Sugerencia

    Si no puede conectar Termite al kit de desarrollo, instale el controlador ST-LINK e inténtelo de nuevo. Consulte la solución de problemas para ver otros pasos.

  2. Haga clic en Configuración.

  3. En el cuadro de diálogo Serial port settings (Configuración de puerto serie), compruebe los siguientes valores y actualícelos si es necesario:

    • Baud rate (Velocidad en baudios): 115.200
    • Port (Puerto): el puerto al que está conectado MXCHIP DevKit. Si hay varias opciones de puerto en la lista desplegable, busque ahí el puerto correcto que debe usar. Abra el Administrador de dispositivos de Windows y, en Puertos, identifique qué puerto debe usar.

    Captura de pantalla de la configuración del puerto serie en la aplicación Termite

  4. Seleccione Aceptar.

  5. Presione el botón Reset (Restablecer) en el dispositivo. El botón está rotulado en el dispositivo y se encuentra cerca del conector micro USB.

  6. En la aplicación Termite, compruebe los siguientes valores de punto de control para confirmar que el dispositivo se ha inicializado y está conectado a Azure IoT.

     Starting Azure thread


 Initializing WiFi
     MAC address: ******************
 SUCCESS: WiFi initialized

 Connecting WiFi
     Connecting to SSID 'iot'
     Attempt 1...
 SUCCESS: WiFi connected

 Initializing DHCP
     IP address: 192.168.0.49
     Mask: 255.255.255.0
     Gateway: 192.168.0.1
 SUCCESS: DHCP initialized

 Initializing DNS client
     DNS address: 192.168.0.1
 SUCCESS: DNS client initialized

 Initializing SNTP time sync
     SNTP server 0.pool.ntp.org
     SNTP time update: Jan 4, 2023 22:57:32.658 UTC
 SUCCESS: SNTP initialized

 Initializing Azure IoT Hub client
     Hub hostname: ***.azure-devices.net
     Device id: mydevice
     Model id: dtmi:eclipsethreadx:devkit:gsgmxchip;2
 SUCCESS: Connected to IoT Hub

 Receive properties: {"desired":{"$version":1},"reported":{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128},"ledState":false,"telemetryInterval":{"ac":200,"av":1,"value":10},"$version":4}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=3{"deviceInformation":{"__t":"c","manufacturer":"MXCHIP","model":"AZ3166","swVersion":"1.0.0","osName":"Eclipse ThreadX","processorArchitecture":"Arm Cortex M4","processorManufacturer":"STMicroelectronics","totalStorage":1024,"totalMemory":128}}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=5{"ledState":false}
 Sending property: $iothub/twin/PATCH/properties/reported/?$rid=7{"telemetryInterval":{"ac":200,"av":1,"value":10}}

 Starting Main loop
 Telemetry message sent: {"humidity":31.01,"temperature":25.62,"pressure":927.3}.
 Telemetry message sent: {"magnetometerX":177,"magnetometerY":-36,"magnetometerZ":-346.5}.
 Telemetry message sent: {"accelerometerX":-22.5,"accelerometerY":0.54,"accelerometerZ":1049.01}.
 Telemetry message sent: {"gyroscopeX":0,"gyroscopeY":0,"gyroscopeZ":0}.

Mantenga abierto Termite para supervisar la salida del dispositivo en los pasos siguientes.

Visualización de las propiedades del dispositivo

Puede usar Azure IoT Explorer para ver y administrar las propiedades de los dispositivos. En esta sección y en las siguientes usará las funcionalidades de Plug and Play que se muestran en IoT Explorer para administrar MXCHIP DevKit e interactuar con este. Estas funcionalidades se basan en el modelo de dispositivo publicado para MXCHIP DevKit en el repositorio de modelos público. Ha configurado IoT Explorer para buscar este repositorio para los modelos de dispositivo anteriormente en este tutorial. Puede realizar muchas acciones sin usar Plug and Play. Para ello, seleccione la acción en el menú izquierdo del panel del dispositivo en 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 MXCHIP DevKit 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 MXCHIP Getting Started Guide Modelo de ejemplo para MXCHIP DevKit
    Propiedades (solo lectura) Propiedad ledState Estado actual del LED
    Propiedades (grabable) Propiedad telemetryInterval Intervalo en que el dispositivo envía telemetría.
    Comandos Comando setLedState Enciende o apaga la luz LED.

Para ver 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 telemetryInterval a 5 y, a continuación, seleccione Update desired value (Actualizar valor deseado). El dispositivo ahora usa este intervalo para enviar telemetría.

    Captura de pantalla de la configuración del intervalo de telemetría en MXCHIP DevKit en IoT Explorer

  3. IoT Explorer responde con una notificación. También puede observar la actualización en Termite.

  4. Vuelva a establecer el intervalo de telemetría en 10.

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

  1. 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.

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

    Nota

    También puede supervisar la telemetría desde el dispositivo mediante la aplicación Termite.

  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 el explorador de IoT.

  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:eclipsethreadx:devkit:gsgmxchip;1",
         "component": "",
         "payload": "{\"humidity\":41.21,\"temperature\":31.37,\"pressure\":1005.18}"
     }
 }

  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. Para el comando setLedState, establezca el estado en true.

  3. Seleccione Enviar comando. Debería ver una notificación en IoT Explorer y debería activarse la luz LED de usuario amarilla del dispositivo.

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

  4. Establezca el estado en false y, a continuación, seleccione Enviar comando. La luz LED de usuario amarilla debe apagarse.

  5. Opcionalmente, puede ver la salida en Termite para supervisar el estado de los métodos.

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. Para este método, si se establece method-payload en true, se enciende la luz LED y, si se establece en false, dicha luz se apaga.

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

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

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

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

  3. Consulte el terminal de Termite para confirmar los mensajes de salida:

     Receive direct method: setLedState
     Payload: true
 LED is turned ON
 Device twin property sent: {"ledState":true}

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 compilado una imagen personalizada que contiene código de ejemplo de Eclipse ThreadX y, después, la ha guardado en la memoria flash en el dispositivo MXCHIP DevKit. También ha usado la CLI de Azure o IoT Explorer para crear recursos de Azure, conectar el dispositivo MXCHIP DevKit de forma segura a Azure, ver la telemetría y enviar mensajes.

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

Eclipse ThreadX proporciona a los OEM componentes para proteger la comunicación y crear código y aislamiento de datos mediante los mecanismos de protección de hardware MCU/MPU subyacentes. Sin embargo, cada OEM es responsable en última instancia de garantizar que el dispositivo cumpla los requisitos de seguridad en constante evolución.