Tutorial: Usar o Eclipse ThreadX para conectar um kit de desenvolvimento do MXCHIP AZ3166 ao Hub IoT

  • Artigo

Procurar código

Neste tutorial, você usará o Eclipse ThreadX para conectar um kit de desenvolvimento MXCHIP AZ3166 IoT (a partir de agora, MXCHIP DevKit) ao Azure IoT.

Conclua as seguintes tarefas:

  • Instalar um conjunto de ferramentas de desenvolvimento inseridas para programar o MXCHIP DevKit em C
  • Criar e instalar uma imagem no Kit de Desenvolvimento MXCHIP
  • Usar a CLI do Azure para criar e gerenciar um hub IoT do Azure ao qual o MXCHIP DevKit se conectará com segurança
  • Usar o Explorer da Internet das Coisas do Azure para registrar um dispositivo no Hub IoT, exibir as propriedades do dispositivo, exibir a telemetria do dispositivo e chamar comandos diretos no dispositivo

Pré-requisitos

  • Um PC com o Windows 10 ou o Windows 11 em execução

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

  • Obter o Git para executar a clonagem do repositório

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

    • Usar o Azure Cloud Shell, um shell interativo que executa comandos da CLI no navegador. Essa opção é recomendada porque não é preciso instalar nada. Se estiver usando o Cloud Shell pela primeira vez, faça logon no portal do Azure. Siga as etapas do Guia de início rápido do Cloud Shell para Iniciar o Cloud Shell e Selecionar o ambiente Bash.
    • Opcionalmente, execute a CLI do Azure no computador local. Se a CLI do Azure já estiver instalado, 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 contenha todos os ativos necessários para o tutorial. Depois instale um conjunto de ferramentas de programação.

Clonar o repositório

Clone o repositório a seguir para baixar todos os códigos de dispositivos de exemplo, scripts de configuração e versões offline da documentação. Caso tenha clonado este repositório anteriormente em outro tutorial, não será preciso fazer isso novamente.

Execute o seguinte comando para clonar o repositório:

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

Instalar as ferramentas

O repositório clonado contém um script de configuração que vai instalar e configurar as ferramentas necessárias. Caso tenha instalado essas ferramentas em outro tutorial de dispositivo inserido, não é preciso fazer isso novamente.

Observação

O script de configuração instalará as seguintes ferramentas:

  • CMake: criar
  • GCC do ARM: compilar
  • Termite: monitorar a saída da porta serial dos recursos dos dispositivos conectados

Para instalar as ferramentas:

  1. No Explorador de Arquivos, acesse o seguinte caminho no repositório e execute o script de configuração chamado get-toolchain.bat:

    getting-started\tools\get-toolchain.bat

  2. Após a instalação, abra uma janela do console para reconhecer as alterações de configuração executadas pelo script de configuração. Use este console para concluir as tarefas restantes de programação no tutorial. É possível usar o CMD do Windows, o PowerShell ou o Git Bash para Windows.

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

    cmake --version

Criar componentes de nuvem

Crie um hub IoT

Use a CLI do Azure para criar um Hub IoT que trata os eventos e mensagens do seu dispositivo.

Para criar um hub IoT:

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

    • Se 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 estiver usando a CLI do Azure localmente, inicie o aplicativo de console da CLI e faça logon 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.

    Observação

    Opcionalmente, você pode definir um location alternativo. 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 o espaço reservado no código pelo nome escolhido para o hub IoT. Um nome de Hub IoT deve ser exclusivo globalmente no Azure. Esse espaço reservado é usado no restante deste guia de início rápido para representar o nome exclusivo do hub IoT.

    O parâmetro --sku F1 cria o hub IoT na Camada gratuita. Os hubs da Camada gratuita têm um conjunto de recursos limitado e são usados para aplicativos de prova de conceito. Para saber mais 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, veja a saída JSON no console e copie o valor hostName a ser usado em uma etapa posterior. O valor hostName será semelhante ao exemplo a seguir:

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

Configurar o Explorer do IoT

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

Para adicionar uma conexão ao hub IoT:

  1. Instalar o Explorador de IoT do Azure. Esta ferramenta é um utilitário multiplataforma para monitorar e gerenciar os recursos de IoT do Azure.

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

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

  3. Copie a cadeia de conexão sem os caracteres de aspas.

  4. No Explorer da Internet das Coisas do Azure, selecione hubs IoT no menu à esquerda.

  5. Selecione + Adicionar Conexão.

  6. Cole a cadeia de conexão copiada no campo Cadeia de conexão.

  7. Clique em Salvar.

    Captura de tela da adição de uma conexão no Explorer do IoT.

Se a conexão for bem-sucedida, o Explorer do IoT muda para a exibição de Dispositivos.

Para adicionar um repositório de modelos públicos:

  1. No Explorer do IoT, selecione Página Inicial para retornar à exibição da página inicial.

  2. No menu à esquerda, selecione Configurações do IoT Plug and Play, +Adicionar e Repositório público no menu suspenso.

  3. Uma entrada é exibida para o repositório de modelo público em https://devicemodels.azure.com.

    Captura de tela da adição do repositório de modelo público no Explorer do IoT.

  4. Selecione Salvar.

Registrar um dispositivo

Nesta seção, você criará uma nova instância de dispositivo e a registrará no hub IoT criado. Em uma seção posterior, você usará as informações de conexão do dispositivo recém-registrado para conectar o dispositivo físico com segurança.

Para registrar um dispositivo:

  1. Na exibição da página inicial no Explorer do IoT, selecione hubs IoT.

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

  3. Selecione + Novo e insira uma ID de dispositivo para o dispositivo. Por exemplo, mydevice. Não altere as demais propriedades.

  4. Selecione Criar.

    Captura de tela da identidade do dispositivo do Explorer da Internet das Coisas do Azure.

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

Antes de continuar para a próxima seção, salve cada um dos valores a seguir 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 Kit de Desenvolvimento MXCHIP ao Azure, é necessário modificar um arquivo de configuração para executar as configurações de Wi-Fi e IoT do Azure, bem como recompilar e instalar a imagem no 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 próxima à parte superior do arquivo, conforme mostrado:

    // #define ENABLE_DPS

  3. Defina as constantes de Wi-Fi para os valores abaixo de seu ambiente local.

    Nome da constante Valor
    WIFI_SSID {Seu SSID de Wi-Fi}
    WIFI_PASSWORD {Sua senha de Wi-Fi}
    WIFI_MODE {Um dos valores do modo Wi-Fi enumerados no arquivo}

  4. Defina as constantes de informações do dispositivo de IoT do Azure para os valores salvos após a criação de recursos do Azure.

    Nome da constante Valor
    IOT_HUB_HOSTNAME {Valor do nome do host}
    IOT_HUB_DEVICE_ID {Seu valor da ID do dispositivo}
    IOT_DEVICE_SAS_KEY {Seu valor da chave primária}

  5. Salve e feche o arquivo.

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. Depois que a criação for concluída, confirme se o arquivo binário foi criado no seguinte caminho:

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

Instalar a imagem

  1. No Kit de Desenvolvimento MXCHIP, localize o botão Redefinir e a micro porta USB. Use esses componentes nas etapas a seguir. Os dois estarão realçados na seguinte figura:

    Localizar os principais componentes da placa do Kit de Desenvolvimento MXChip

  2. Conecte o micro cabo USB à micro porta USB no Kit de Desenvolvimento MXCHIP, depois conecte-o ao seu computador.

  3. No Explorador de Arquivos, localize o arquivo binário criado na seção anterior.

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

  5. No Explorador de Arquivos, localize o dispositivo do Kit de Desenvolvimento MXCHIP conectado ao seu computador. O dispositivo será exibido como uma unidade no sistema com o rótulo da unidade AZ3166.

  6. Cole o arquivo binário na pasta raiz do Kit de Desenvolvimento MXCHIP. A atualização da imagem será iniciada de modo automático e concluída em alguns segundos.

    Observação

    Durante o processo de atualização de imagem, um LED verde vai ligar/desligar no Kit de Desenvolvimento MXCHIP.

Confirmar detalhes de conexão do dispositivo

É possível usar o aplicativo Termite para monitorar a comunicação e confirmar se o dispositivo foi configurado de modo adequado.

  1. Inicie o Termite.

    Dica

    Caso não seja possível conectar o Termite ao seu Kit de Desenvolvimento, instale o driver ST-LINK e tente novamente. Confira a Solução de problemas para obter etapas adicionais.

  2. Selecione Configurações.

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

    • Taxa de transmissão: 115.200
    • Porta: a porta à qual o Kit de Desenvolvimento MXCHIP está conectado. Caso haja várias opções de portas na lista suspensa, será possível localizar a porta adequada para uso. Abra o Gerenciador de Dispositivos do Windows e exiba a opção Portas para identificar qual porta usar.

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

  4. Selecione OK.

  5. Clique no botão Reiniciar do dispositivo. O botão está rotulado no dispositivo e próximo ao micro conector USB.

  6. No aplicativo Termite, verifique os valores do ponto de verificação a seguir para confirmar se o dispositivo foi inicializado e conectado à IoT do Azure.

     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 Termite aberto para monitorar a saída do dispositivo nas etapas a seguir.

Exibir propriedades do dispositivo

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

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

  1. Na exibição da página inicial no Explorer do IoT, selecione hubs IoT e Exibir dispositivos neste hub.

  2. Selecione seu dispositivo.

  3. Selecione Componentes IoT Plug and Play.

  4. Selecione Componente padrão. O Explorer do IoT exibe os componentes do IoT Plug and Play que estão implementados em seu dispositivo.

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

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

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

    Tab Tipo Nome Descrição
    Interface Interface MXCHIP Getting Started Guide Modelo de exemplo para MXCHIP DevKit
    Propriedades (somente leitura) Propriedade ledState O estado atual do LED
    Propriedades (graváveis) Propriedade telemetryInterval Intervalo em que o dispositivo envia a telemetria
    Comandos Comando setLedState Ativar ou desativar o LED

Para exibir as propriedades do dispositivo usando o Explorer da Internet das Coisas do Azure:

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

  2. Altere telemetryInterval para 5 e selecione Atualizar o valor desejado. Seu dispositivo passou a usar esse intervalo para enviar a telemetria.

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

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

  4. Retorne a definição do intervalo de telemetria 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.

Exibir telemetria

Ao usar o Explorer da Internet das Coisas do Azure, é possível exibir o fluxo de telemetria do seu dispositivo para a nuvem. Opcionalmente, você pode executar a mesma tarefa usando a CLI do Azure.

Para exibir a telemetria no Explorer da Internet das Coisas do Azure:

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

  2. Selecione Iniciar.

  3. Exiba a telemetria conforme o dispositivo envia mensagens à nuvem.

    Captura de tela da telemetria do dispositivo no Explorer do IoT

    Observação

    Também é possível monitorar a telemetria do dispositivo usando o aplicativo Termite.

  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 dos eventos de telemetria modelados no Explorer do IoT

  5. Selecione Parar para encerrar 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 criados anteriormente na Internet das Coisas do Azure para seu dispositivo e o hub IoT.

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

  2. Exiba a saída JSON na janela do 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

Também é possível usar o Explorer da Internet das Coisas do Azure para executar uma chamada a um método direto implementado em seu dispositivo. Os métodos diretos têm um nome e, de modo opcional, podem ter um conteúdo JSON, uma conexão configurável e um tempo limite do método. Nesta seção, você executará uma chamada a um método que permite ligar ou desligar um LED. Opcionalmente, você pode executar a mesma tarefa usando a CLI do Azure.

Para chamar um método no Explorer da Internet das Coisas do Azure:

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

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

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

    Captura de tela da chamada ao método setLedState no Explorer do IoT

  4. Defina o estado como false e selecione Enviar comando. O LED amarelo do usuário deve apagar.

  5. Opcionalmente, você pode exibir a saída no Termite 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 o payload. Para esse método, a configuração de method-payload para true liga o LED, e a configuração para false desliga.

    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 ao método no dispositivo, em que 204 indica êxito.

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

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

  3. Olhe no terminal Termite para confirmar as mensagens de saída:

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

Solucionar problemas e depurar

Se tiver problemas para criar o código do dispositivo, para acender/apagar o dispositivo ou se conectar, consulte Solução de problemas.

Para executar a depuração do aplicativo, confira Como executar uma depuração usando o Visual Studio Code.

Limpar recursos

Se não precisar mais dos recursos do Azure criados neste guia de início rápido, use a CLI do Azure para excluí-los.

Importante

A exclusão de um grupo de recursos é irreversível. O grupo de recursos e todos os recursos contidos nele são excluídos permanentemente. Não exclua acidentalmente o grupo de recursos ou os recursos incorretos.

Para excluir um grupo de recursos por nome:

  1. Execute o comando az group delete. Esse comando removerá 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 se o grupo de recursos foi excluído.

    az group list

Próximas etapas

Neste tutorial, você criou uma imagem personalizada que contém o código de exemplo do Eclipse ThreadX. Depois atualizou a imagem no dispositivo do Kit de Desenvolvimento MXCHIP. Também usou a CLI do Azure e/ou o Explorer do IoT para criar recursos do Azure, conectar o Kit de Desenvolvimento MXCHIP ao Azure com segurança, exibir telemetrias e enviar mensagens.

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

Saiba mais sobre como conectar dispositivos inseridos usando o SDK do C e o SDK do C Inserido

O Eclipse ThreadX fornece OEMs juntamente com componentes para proteger a comunicação e criar um isolamento de códigos e dados usando mecanismos subjacentes de MCU/MPU de proteção de hardware. No entanto, cada OEM é responsável por garantir que os dispositivos atendam aos requisitos de segurança em evolução.