Partilhar via

Tutorial: Use o Eclipse ThreadX para conectar um devkit MXCHIP AZ3166 ao Hub IoT

  • Artigo

Procurar código

Neste tutorial, você usa o Eclipse ThreadX para conectar um MXCHIP AZ3166 IoT DevKit (doravante, MXCHIP DevKit) ao Azure IoT.

Conclua as seguintes tarefas:

  • Instale um conjunto de ferramentas de desenvolvimento incorporadas para programar o MXChip DevKit em C
  • Crie uma imagem e visualize-a no MXCHIP DevKit
  • Use a CLI do Azure para criar e gerenciar um hub IoT do Azure ao qual o MXCHIP DevKit se conecta com segurança
  • Use o Azure IoT Explorer para registrar um dispositivo com seu hub IoT, exibir propriedades do dispositivo, exibir telemetria do dispositivo e chamar comandos diretos no dispositivo

Pré-requisitos

  • Um PC com Windows 10 ou Windows 11

  • Uma subscrição ativa do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

  • Git para clonar o repositório

  • CLI do Azure. Você tem duas opções para executar comandos da CLI do Azure neste tutorial:

    • Use o Azure Cloud Shell, um shell interativo que executa comandos da CLI em seu navegador. Essa opção é recomendada porque você não precisa instalar nada. Se você estiver usando o Cloud Shell pela primeira vez, entre no portal do Azure. Siga as etapas no início rápido do Cloud Shell para iniciar o Cloud Shell e selecionar o ambiente Bash.
    • Opcionalmente, execute a CLI do Azure em sua máquina local. Se a CLI do Azure já estiver instalada, execute az upgrade para atualizar a CLI e as extensões para a versão atual. Para instalar a CLI do Azure, consulte Instalar a CLI do Azure.

  • Hardware

Preparar o ambiente de desenvolvimento

Para configurar seu ambiente de desenvolvimento, primeiro clone um repositório GitHub que contém todos os ativos necessários para o tutorial. Em seguida, você instala um conjunto de ferramentas de programação.

Clonar o repositório

Clone o repositório a seguir para baixar todo o código de dispositivo de exemplo, scripts de configuração e versões offline da documentação. Se você clonou anteriormente este repositório em outro tutorial, não precisará fazê-lo novamente.

Para clonar o repositório, execute o seguinte comando:

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

Instale as ferramentas

O repositório clonado contém um script de instalação que instala e configura as ferramentas necessárias. Se você instalou essas ferramentas em outro tutorial de dispositivo incorporado, não precisará fazê-lo novamente.

Nota

O script de instalação instala as seguintes ferramentas:

  • CMake: Construir
  • ARM GCC: Compilar
  • Cupim: monitore a saída da porta serial para recursos de dispositivos conectados

Para instalar as ferramentas:

  1. Navegue até o seguinte caminho no repositório e execute o script de instalação chamado get-toolchain.bat:

    getting-started\tools\get-toolchain.bat

  2. Abra uma nova janela do console para reconhecer as alterações de configuração feitas pelo script de instalação. Use este console para concluir as tarefas de programação restantes no tutorial. Você pode usar o Windows CMD, PowerShell ou Git Bash para Windows.

  3. Execute o código a seguir para confirmar que o CMake versão 3.14 ou posterior está instalado.

    cmake --version

Criar os componentes da nuvem

Criar um hub IoT

Você pode usar a CLI do Azure para criar um hub IoT que manipula eventos e mensagens para seu dispositivo.

Para criar um hub IoT:

  1. Inicie seu aplicativo CLI. Para executar os comandos da CLI no restante deste início rápido, copie a sintaxe do comando, cole-a no aplicativo da CLI, edite valores de variáveis e pressione Enter.

    • Se você estiver usando o Cloud Shell, clique com o botão direito do mouse no link do Cloud Shell e selecione a opção para abrir em uma nova guia.
    • Se você estiver usando a CLI do Azure localmente, inicie seu aplicativo de console da CLI e entre na CLI do Azure.

  2. Execute az extension add para instalar ou atualizar a extensão azure-iot para a versão atual.

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

  3. Execute o comando az group create para criar um grupo de recursos. O comando a seguir cria um grupo de recursos chamado MyResourceGroup na região centralus .

    Nota

    Opcionalmente, você pode definir um arquivo location. Para ver os locais disponíveis, execute az account list-locations.

    az group create --name MyResourceGroup --location centralus

  4. Execute o comando az iot hub create para criar um hub IoT. Pode levar alguns minutos para criar um hub IoT.

    YourIotHubName. Substitua esse espaço reservado no código pelo nome escolhido para seu hub IoT. Um nome de hub IoT deve ser globalmente exclusivo no Azure. Esse espaço reservado é usado no restante deste início rápido para representar seu nome exclusivo do hub IoT.

    O --sku F1 parâmetro cria o hub IoT na camada Livre. Os hubs de nível gratuito têm um conjunto de recursos limitado e são usados para aplicações de prova de conceito. Para obter mais informações sobre camadas, recursos e preços do Hub IoT, consulte Preços do Hub IoT do Azure.

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

  5. Depois que o hub IoT for criado, exiba a saída JSON no console e copie o hostName valor a ser usado em uma etapa posterior. O hostName valor se parece com o exemplo a seguir:

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

Configurar o IoT Explorer

No restante deste início rápido, você usa o IoT Explorer para registrar um dispositivo em seu hub IoT, para exibir as propriedades e a telemetria do dispositivo e para enviar comandos para seu dispositivo. Nesta seção, você configura o IoT Explorer para se conectar ao hub IoT criado e para ler modelos plug and play do repositório de modelos públicos.

Para adicionar uma conexão ao seu hub IoT:

  1. Instale o Azure IoT Explorer. Esta ferramenta é um utilitário multiplataforma para monitorar e gerenciar recursos do Azure IoT.

  2. Em seu aplicativo CLI, execute o comando az iot hub connection-string show para obter a cadeia de conexão para seu hub IoT.

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

  3. Copie a cadeia de conexão sem os caracteres de cotação ao redor.

  4. No Azure IoT Explorer, selecione Hubs IoT no menu à esquerda.

  5. Selecione + Adicionar ligação.

  6. Cole a cadeia de conexão na caixa Cadeia de conexão .

  7. Selecione Guardar.

    Captura de ecrã a mostrar a adição de uma ligação no Explorador do IoT.

Se a conexão for bem-sucedida, o IoT Explorer alternará para o modo de exibição Dispositivos .

Para adicionar o repositório de modelo público:

  1. No IoT Explorer, selecione Página Inicial para retornar ao modo de exibição inicial.

  2. No menu à esquerda, selecione Configurações Plug and Play da IoT.

  3. Confirme se existe uma entrada de Repositório Público existente com um ponto de extremidade de https://devicemodels.azure.com.

    Nota

    Se não houver uma entrada no repositório público, selecione +Adicionar, selecione Repositório público no menu suspenso, especifique o valor do https://devicemodels.azure.com ponto de extremidade e selecione Salvar.

    A entrada concluída para o repositório público se parece com a seguinte captura de tela:

    Captura de ecrã a mostrar a adição do repositório de modelos públicos no Explorador do IoT.

Registar um dispositivo

Nesta seção, você cria uma nova instância de dispositivo e a registra no hub IoT criado. Você usa as informações de conexão do dispositivo recém-registrado para conectar seu dispositivo físico com segurança em uma seção posterior.

Para registar um dispositivo:

  1. Na visualização inicial no IoT Explorer, selecione Hubs IoT.

  2. A conexão que você adicionou anteriormente deve aparecer. Selecione Exibir dispositivos neste hub abaixo das propriedades de conexão.

  3. Selecione + Novo e insira um ID de dispositivo para o seu dispositivo, por exemplo, mydevice. Deixe todas as outras propriedades iguais.

  4. Selecione Criar.

    Captura de ecrã da identidade do dispositivo do Azure IoT Explorer.

  5. Use os botões de cópia para copiar os campos ID do dispositivo e Chave primária.

Antes de continuar para a próxima seção, salve cada um dos seguintes valores recuperados de etapas anteriores em um local seguro. Use esses valores na próxima seção para configurar seu dispositivo.

  • hostName
  • deviceId
  • primaryKey

Preparar o dispositivo

Para conectar o MXCHIP DevKit ao Azure, modifique um arquivo de configuração para as configurações de Wi-Fi e Azure IoT, recrie a imagem e pisce a imagem para o dispositivo.

Adicionar configuração

  1. Abra o seguinte arquivo em um editor de texto:

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

  2. Comente a seguinte linha perto da parte superior do arquivo, conforme mostrado:

    // #define ENABLE_DPS

  3. Defina as constantes Wi-Fi para os seguintes valores do seu ambiente local.

    Nome constante Value
    WIFI_SSID {O seu SSID Wi-Fi}
    WIFI_PASSWORD {A sua palavra-passe Wi-Fi}
    WIFI_MODE {Um dos valores enumerados do modo Wi-Fi no ficheiro}

  4. Defina as constantes de informações do dispositivo IoT do Azure para os valores que você salvou depois de criar os recursos do Azure.

    Nome constante Value
    IOT_HUB_HOSTNAME {Seu valor de nome de host}
    IOT_HUB_DEVICE_ID {O valor do ID do dispositivo}
    IOT_DEVICE_SAS_KEY {Seu valor de chave primária}

  5. Guarde e feche o ficheiro.

Criar a imagem

  1. No console ou no Explorador de Arquivos, execute o script rebuild.bat no seguinte caminho para criar a imagem:

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

  2. Após a conclusão da compilação, confirme se o arquivo binário foi criado no seguinte caminho:

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

Piscar a imagem

  1. No MXCHIP DevKit, localize o botão Reset e a porta Micro USB. Use esses componentes nas etapas a seguir. Ambos são destacados na imagem a seguir:

    Localize os principais componentes na placa de desenvolvimento MXChip

  2. Ligue o cabo Micro USB à porta Micro USB no MXCHIP DevKit e, em seguida, ligue-o ao computador.

  3. No Explorador de Ficheiros, localize o ficheiro binário que criou na secção anterior.

  4. Copie o arquivo binário mxchip_azure_iot.bin.

  5. No Explorador de Ficheiros, localize o dispositivo MXCHIP DevKit ligado ao computador. O dispositivo aparece como uma unidade no seu sistema com a etiqueta da unidade AZ3166.

  6. Cole o arquivo binário na pasta raiz do MXCHIP Devkit. O piscamento começa automaticamente e termina em poucos segundos.

    Nota

    Durante o processo de piscamento, um LED verde alterna no MXCHIP DevKit.

Confirmar detalhes da conexão do dispositivo

Você pode usar o aplicativo Cupim para monitorar a comunicação e confirmar se seu dispositivo está configurado corretamente.

  1. Inicie o cupim.

    Gorjeta

    Se você não conseguir conectar o Termite ao seu devkit, instale o driver ST-LINK e tente novamente. Consulte Solução de problemas para obter etapas adicionais.

  2. Selecione Definições.

  3. Na caixa de diálogo Configurações da porta serial, verifique as seguintes configurações e atualize, se necessário:

    • Taxa de transmissão: 115.200
    • Porta: A porta à qual o MXCHIP DevKit está conectado. Se houver várias opções de porta na lista suspensa, você poderá encontrar a porta correta a ser usada. Abra o Gerenciador de Dispositivos do Windows e exiba Portas para identificar qual porta usar.

    Captura de tela das configurações de porta serial no aplicativo Cupim

  4. Selecione OK.

  5. Pressione o botão Reset (Reset ) no dispositivo. O botão está rotulado no dispositivo e localizado perto do conector Micro USB.

  6. No aplicativo Cupim, verifique os seguintes valores de ponto de verificação para confirmar se o dispositivo foi inicializado e está conectado ao 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}.

Mantenha o Cupim aberto para monitorar a saída do dispositivo nas etapas a seguir.

Ver propriedades do dispositivo

Você pode usar o Azure IoT Explorer para exibir e gerenciar as propriedades de seus dispositivos. Nesta seção e nas seções a seguir, você usa os recursos Plug and Play que surgiram no IoT Explorer para gerenciar e interagir com o MXCHIP DevKit. Esses recursos dependem do modelo de dispositivo publicado para o MXCHIP DevKit no repositório de modelos públicos. Você configurou o IoT Explorer para pesquisar modelos de dispositivo neste repositório anteriormente neste tutorial. Você pode executar muitas ações sem usar plug and play selecionando a ação no menu do lado esquerdo do painel do dispositivo no IoT Explorer. No entanto, o uso de plug and play geralmente fornece uma experiência aprimorada. O IoT Explorer pode ler o modelo de dispositivo especificado por um dispositivo plug and play e apresentar informações específicas para esse dispositivo.

Para acessar os componentes IoT Plug and Play para o dispositivo no IoT Explorer:

  1. Na vista inicial no Explorador do IoT, selecione Hubs IoT e, em seguida, selecione Ver dispositivos neste hub.

  2. Selecione o seu dispositivo.

  3. Selecione Componentes IoT Plug and Play.

  4. Selecione Componente padrão. O IoT Explorer exibe os componentes IoT Plug and Play implementados no seu dispositivo.

    Captura de tela do componente padrão MXCHIP DevKit no IoT Explorer

  5. Na guia Interface, exiba o conteúdo JSON na Descrição do modelo de dispositivo. O JSON contém detalhes de configuração para cada um dos componentes IoT Plug and Play no modelo de dispositivo.

    Cada guia no IoT Explorer corresponde a um dos componentes IoT Plug and Play no modelo de dispositivo.

    Separador Type Name Descrição
    Interface Interface MXCHIP Getting Started Guide Modelo de exemplo para o MXCHIP DevKit
    Propriedades (somente leitura) Property ledState O estado atual do LED
    Propriedades (graváveis) Property telemetryInterval O intervalo que o dispositivo envia telemetria
    Comandos Comando setLedState Ligue ou desligue o LED

Para exibir as propriedades do dispositivo usando o Azure IoT Explorer:

  1. Selecione a guia Propriedades (gravável). Ele exibe o intervalo em que a telemetria é enviada.

  2. Altere para telemetryInterval 5 e selecione Atualizar valor desejado. Seu dispositivo agora usa esse intervalo para enviar telemetria.

    Captura de tela da configuração do intervalo de telemetria no MXCHIP DevKit no IoT Explorer

  3. O IoT Explorer responde com uma notificação. Você também pode observar a atualização no Cupim.

  4. Defina o intervalo de telemetria de volta para 10.

Para usar a CLI do Azure para exibir as propriedades do dispositivo:

  1. Execute o comando az iot hub device-twin show .

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

  2. Inspecione as propriedades do dispositivo na saída do console.

Ver telemetria

Com o Azure IoT Explorer, você pode exibir o fluxo de telemetria do seu dispositivo para a nuvem. Opcionalmente, você pode fazer a mesma tarefa usando a CLI do Azure.

Para exibir a telemetria no Azure IoT Explorer:

  1. No painel Componentes Plug and Play da IoT (Componente Padrão) do seu dispositivo no IoT Explorer, selecione a guia Telemetria. Confirme se Usar hub de eventos interno está definido como Sim.

  2. Selecione Iniciar.

  3. Visualize a telemetria enquanto o dispositivo envia mensagens para a nuvem.

    Captura de ecrã da telemetria do dispositivo no IoT Explorer

    Nota

    Você também pode monitorar a telemetria do dispositivo usando o aplicativo Cupim.

  4. Marque a caixa de seleção Mostrar eventos modelados para exibir os eventos no formato de dados especificado pelo modelo de dispositivo.

    Captura de tela de eventos de telemetria modelada no IoT Explorer

  5. Selecione Parar para terminar o recebimento de eventos.

Para usar a CLI do Azure para exibir a telemetria do dispositivo:

  1. Execute o comando az iot hub monitor-events . Use os nomes que você criou anteriormente no Azure IoT para seu dispositivo e hub IoT.

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

  2. Exiba a saída JSON no console.

     {
     "event": {
         "origin": "mydevice",
         "module": "",
         "interface": "dtmi:eclipsethreadx:devkit:gsgmxchip;1",
         "component": "",
         "payload": "{\"humidity\":41.21,\"temperature\":31.37,\"pressure\":1005.18}"
     }
 }

  3. Selecione CTRL+C para encerrar o monitoramento.

Chamar um método direto no dispositivo

Você também pode usar o Azure IoT Explorer para chamar um método direto que implementou em seu dispositivo. Os métodos diretos têm um nome e, opcionalmente, podem ter uma carga JSON útil, conexão configurável e tempo limite do método. Nesta seção, você chama um método que liga ou desliga um LED. Opcionalmente, você pode fazer a mesma tarefa usando a CLI do Azure.

Para chamar um método no Azure IoT Explorer:

  1. No painel Componentes Plug and Play da IoT (Componente Padrão) do seu dispositivo no IoT Explorer, selecione a guia Comandos.

  2. Para o comando setLedState , defina o estado como true.

  3. Selecione Enviar comando. Você verá uma notificação no IoT Explorer e a luz LED amarela do usuário no dispositivo deve se acender.

    Captura de tela mostrando a chamada do método setLedState no IoT Explorer

  4. Defina o estado como false e selecione Enviar comando. O LED de utilizador amarelo deve desligar-se.

  5. Opcionalmente, você pode visualizar a saída em Cupim para monitorar o status dos métodos.

Para usar a CLI do Azure para chamar um método:

  1. Execute o comando az iot hub invoke-device-method e especifique o nome do método e a carga útil. Para este método, definir method-payload para true ligar o LED e configurá-lo para false desligá-lo.

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

    O console da CLI mostra o status da chamada de método no dispositivo, onde 204 indica sucesso.

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

  2. Verifique o dispositivo para confirmar o estado do LED.

  3. Veja o terminal de cupins para confirmar as mensagens de saída:

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

Solução de problemas e depuração

Se você tiver problemas para criar o código do dispositivo, piscar o dispositivo ou conectar, consulte Solução de problemas.

Para depurar o aplicativo, consulte Depurando com o Visual Studio Code.

Clean up resources (Limpar recursos)

Se você não precisar mais dos recursos do Azure criados neste início rápido, poderá usar a CLI do Azure para excluir o grupo de recursos e todos os seus recursos.

Importante

A eliminação de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos nele contidos são eliminados permanentemente. Confirme que não elimina acidentalmente o grupo de recursos ou recursos errados.

Para eliminar um grupo de recursos por nome:

  1. Execute o comando az group delete . Este comando remove o grupo de recursos, o Hub IoT e o registro de dispositivo que você criou.

    az group delete --name MyResourceGroup

  2. Execute o comando az group list para confirmar que o grupo de recursos foi excluído.

    az group list

Próximos passos

Neste tutorial, você criou uma imagem personalizada que contém o código de exemplo do Eclipse ThreadX e, em seguida, piscou a imagem para o dispositivo MXCHIP DevKit. Você também usou a CLI do Azure e/ou o IoT Explorer para criar recursos do Azure, conectar o MXCHIP DevKit com segurança ao Azure, exibir telemetria e enviar mensagens.

Como próxima etapa, explore o seguinte artigo para saber mais sobre as opções de desenvolvimento incorporado.

Saiba mais sobre como conectar dispositivos incorporados usando o C SDK e o Embedded C SDK

O Eclipse ThreadX fornece aos OEMs componentes para proteger a comunicação e criar código e isolamento de dados usando mecanismos subjacentes de proteção de hardware MCU/MPU. No entanto, cada OEM é, em última análise, responsável por garantir que seu dispositivo atenda aos requisitos de segurança em evolução.