Tutorial: Conectar um kit ESPRESSIF ESP32-Hub IoT do Azure ao IoT Hub

Artigo
04/07/2024

Nesse tutorial, você usa o middleware Azure IoT para FreeRTOS para conectar o ESPRESSIF ESP32-Azure IoT Kit (a partir de agora, o ESP32 DevKit) ao Azure IoT.

Conclua as seguintes tarefas:

Instalar um conjunto de ferramentas de desenvolvimento incorporadas para programar um ESP32 DevKit
Criar uma imagem e instalá-la no ESP32 DevKit
Usar a CLI do Azure para criar e gerenciar um hub da Internet das Coisas do Azure ao qual o Kit de Desenvolvimento ESP32 se conecta
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
Obter o Git para executar a clonagem do repositório
Hardware
- ESPRESSIF ESP32-Kit de IoT do Azure
- Uma entrada USB 2.0 A macho para um cabo Micro USB macho
- Wi-Fi de 2.4 GHz
Uma assinatura ativa do Azure. Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.

Preparar o ambiente de desenvolvimento

Instalar as ferramentas

Para configurar o ambiente de desenvolvimento, primeiro instale o ambiente de compilação do ESPRESSIF ESP-IDF. O instalador inclui todas as ferramentas necessárias para clonar, compilar, instalar e monitorar seu dispositivo.

Para instalar as ferramentas ESP-IDF:

Baixe e inicie o instalador offline do ESP-IDF v5.0.
Quando o instalador listar os componentes a serem instalados, selecione todos os componentes e conclua a instalação.

Clonar o repositório

Clone o repositório a seguir para baixar todos os códigos de exemplo de dispositivos, scripts de configuração e documentação do SDK. Caso já tenha clonado este repositório, não será preciso clonar novamente.

Execute o seguinte comando para clonar o repositório:

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

Para Windows 10 e 11, verifique se os caminhos longos estão habilitados.

Para habilitar caminhos longos, consulte Habilitar caminhos longos no Windows 10.
No git, execute o comando a seguir em um terminal com permissões de Administrador:
```
git config --system core.longpaths true
```

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:

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.
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
```
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
```
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
```
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:

Instalar o Explorador de IoT do Azure. Esta ferramenta é um utilitário multiplataforma para monitorar e gerenciar os recursos de IoT do Azure.
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}
```
Copie a cadeia de conexão sem os caracteres de aspas.
No Explorer da Internet das Coisas do Azure, selecione hubs IoT no menu à esquerda.
Selecione + Adicionar Conexão.
Cole a cadeia de conexão copiada no campo Cadeia de conexão.
Clique em Salvar.

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:

No Explorer do IoT, selecione Página Inicial para retornar à exibição da página inicial.
No menu à esquerda, selecione Configurações do IoT Plug and Play, +Adicionar e Repositório público no menu suspenso.
Uma entrada é exibida para o repositório de modelo público em https://devicemodels.azure.com.
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:

Na exibição da página inicial no Explorer do IoT, selecione hubs IoT.
A conexão que você adicionou anteriormente será exibida. Selecione Exibir dispositivos neste hub abaixo das propriedades de conexão.
Selecione + Novo e insira uma ID de dispositivo para o dispositivo. Por exemplo, mydevice. Não altere as demais propriedades.
Selecione Criar.
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 ESP32 ao Azure, você modifica as definições de configuração, cria a imagem e instala a imagem para o dispositivo.

Configurar o ambiente

Para iniciar o ambiente ESP-IDF:

Selecione Iniciar no Windows, localize CMD ESP-IDF 5.0 e execute-o.
No CMD ESP-IDF 5.0, navegue até o diretório iot-middleware-freertos-samples que você clonou anteriormente.
Acesse o diretório de projeto do kit de IoT do Azure - ESP32 demos\projects\ESPRESSIF\aziotkit.
Execute o seguinte comando para iniciar o menu de configuração:
```
idf.py menuconfig
```

Adicionar configuração

Para adicionar a configuração da rede sem fio:

No CMD ESP-IDF 5.0, selecione o middleware da Internet das Coisas do Azure para configuração de exemplo do FreeRTOS ---> e pressione Enter.
Defina as seguintes definições de configuração usando as credenciais de rede sem fio local.

Configuração Valor

Wi-Fi SSID {Seu SSID de Wi-Fi}

Senha do Wi-Fi {Sua senha de Wi-Fi}
Selecione Esc para retornar ao menu anterior.

Configuração	Valor
Wi-Fi SSID	{Seu SSID de Wi-Fi}
Senha do Wi-Fi	{Sua senha de Wi-Fi}

Para adicionar a configuração para se conectar ao Hub IoT do Azure:

Selecione o middleware da Internet das Coisas do Azure para configuração de tarefa principal do FreeRTOS ---> e pressione Enter.

Defina as seguintes definições de configuração da IoT do Azure para os valores que você salvou depois de criar os recursos do Azure.

Configuração	Valor
FQDN do Hub IoT do Azure	{Seu nome de host}
ID do dispositivo da Internet das Coisas do Azure	{ID do seu dispositivo}
Chave simétrica do dispositivo da Internet das Coisas do Azure	{Sua chave primária}

Observação

Na configuração Método de Autenticação da Internet das Coisas do Azure, confirme se o valor padrão de Chave Simétrica está selecionado.

Selecione Esc para retornar ao menu anterior.

Para salvar a configuração:

Selecione Shift+S para abrir as opções de salvamento. Este menu permite salvar a configuração em um arquivo chamado skconfig no diretório .\aziotkit atual.
Selecione Enter para salvar a configuração.
Selecione Enter para descartar a mensagem de confirmação.
Selecione Q para sair do menu de configuração.

Compilar e instalar a imagem

Nesta seção, você usará as ferramentas ESP-IDF para compilar, instalar e monitorar o ESP32 DevKit conforme ele se conecta à Internet das Coisas do Azure.

Observação

Nos seguintes comandos nesta seção, use um caminho curto de saída de compilação próximo ao diretório raiz. Especifique o caminho de compilação após o parâmetro -B em cada comando que o exige. O caminho curto ajuda a evitar um problema atual nas ferramentas ESPRESSIF ESP-IDF que podem causar erros com nomes longos de caminho de compilação. Os comandos a seguir usam um caminho local C:\espbuild como exemplo.

Para compilar a imagem:

No CMD ESP-IDF 5.0, a partir do diretório iot-middleware-freertos-samples\demos\projects\ESPRESSIF\aziotkit, execute o comando a seguir para compilar a imagem.
```
idf.py --no-ccache -B "C:\espbuild" build 
```
Depois que a compilação for concluída, confirme se o arquivo de imagem binária foi criado no caminho de compilação especificado anteriormente.

C:\espbuild\azure_iot_freertos_esp32.bin

Para instalar a imagem:

No ESP32 DevKit, localize a porta micro USB, realçada na imagem a seguir:
Conecte o cabo micro USB à porta micro USB no ESP32 DevKit, depois conecte-o ao seu computador.
Abra o Gerenciador de dispositivos do Windows e exiba Portas para descobrir a qual porta COM o ESP32 DevKit está conectado.
No CMD ESP-IDF 5.0, execute o comando a seguir, substituindo o espaço reservado <Your-COM-port> e os colchetes pela porta COM correta da etapa anterior. Por exemplo, substitua o espaço reservado por COM3.
```
idf.py --no-ccache -B "C:\espbuild" -p <Your-COM-port> flash
```
Confirme se a saída foi concluída com o seguinte texto para uma instalação bem-sucedida:
```
Hash of data verified

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

Para confirmar se o dispositivo se conecta à Azure IoT Central:

No CMD ESP-IDF 5.0, execute o comando a seguir para iniciar a ferramenta de monitoramento. Como você fez em um comando anterior, substitua o espaço reservado <Your-COM-port> e os colchetes pela porta COM à qual o dispositivo está conectado.
```
idf.py -B "C:\espbuild" -p <Your-COM-port> monitor
```

Verifique se há blocos repetitivos de saída semelhantes ao exemplo a seguir. Essa saída confirma que o dispositivo se conecta à Internet das Coisas do Azure e envia telemetria.

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

Exibir propriedades do dispositivo

Você pode usar o Explorer da Internet das Coisas do Azure para exibir e gerenciar as propriedades de seus dispositivos. Nas seções a seguir, você usa as funcionalidades Plug and Play visíveis no Explorer do IoT para gerenciar e interagir com o Kit de Desenvolvimento ESP32. Esses recursos dependem do modelo de dispositivo publicado para o Kit de Desenvolvimento ESP32 no repositório de modelo público. Você configurou o IoT Explorer para pesquisar modelos de dispositivos nesse repositório anteriormente nesse tutorial. Em muitos casos, você pode executar a mesma ação sem usar plug and play selecionando as opções de menu do IoT Explorer. 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:

Na exibição da página inicial no Explorer do IoT, selecione hubs IoT e Exibir dispositivos neste hub.
Selecione seu dispositivo.
Selecione Componentes IoT Plug and Play.
Selecione Componente padrão. O Explorer do IoT exibe os componentes do IoT Plug and Play que estão implementados em seu dispositivo.

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	`Espressif ESP32 Azure IoT Kit`	Modelo de dispositivo de exemplo para o Kit de Desenvolvimento ESP32
Propriedades (graváveis)	Propriedade	`telemetryFrequencySecs`	Intervalo em que o dispositivo envia a telemetria
Comandos	Comando	`ToggleLed1`	Ativar ou desativar o LED
Comandos	Comando	`ToggleLed2`	Ativar ou desativar o LED
Comandos	Comando	`DisplayText`	Exibe o texto enviado na tela do dispositivo

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

Selecione a guia Propriedades (graváveis) . Ela exibe o intervalo em que a telemetria é enviada.
Altere o valor telemetryFrequencySecs para 5 e selecione Atualizar o valor desejado. Seu dispositivo passou a usar esse intervalo para enviar a telemetria.
O Explorer do IoT responde com uma notificação.

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

No console da CLI, execute o comando az iot hub device-twin show.

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

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

Dica

Você também pode usar o Explorer da Internet das Coisas do Azure para exibir as propriedades do dispositivo. No painel de navegação esquerdo, selecione Dispositivo gêmeo.

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:

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.
Selecione Iniciar.
Exiba a telemetria conforme o dispositivo envia mensagens à nuvem.
Marque a caixa de seleção Mostrar eventos modelados para exibir os eventos no formato de dados, especificado pelo modelo de dispositivo.
Selecione Parar para encerrar o recebimento de eventos.

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

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}
```

Exiba a saída JSON na janela do console.

{
    "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}"
    }
}

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:

No painel Componentes IoT Plug and Play (Componente Padrão) do dispositivo no Explorer do IoT, selecione a guia Comandos.
Para o comando ToggleLed1, selecione Enviar comando. O LED no Kit de Desenvolvimento ESP32 ativa ou desativa. Você também deve visualizar uma notificação no IoT Explorer.
Para o comando DisplayText, insira algum texto no campo de conteúdo.
Selecione Enviar comando. O texto é exibido na tela do Kit de Desenvolvimento ESP32.

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

Execute o comando az iot hub invoke-device-method e especifique o nome do método e o payload. Para esse método, definir method-payload como true significa que o LED alterna para o oposto de seu estado atual.
```
az iot hub invoke-device-method --device-id mydevice --method-name ToggleLed2 --method-payload true --hub-name {YourIoTHubName}
```
O console da CLI mostra o status da chamada ao método no dispositivo, em que 200 indica êxito.
```
{
  "payload": {},
  "status": 200
} 
```
Verifique o dispositivo para confirmar o estado do LED.

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:

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
```
Execute o comando az group list para confirmar se o grupo de recursos foi excluído.
```
az group list
```

Próximas etapas

Nesse tutorial, você criou uma imagem personalizada que contém o middleware Azure IoT para o código de exemplo do FreeRTOS e, em seguida, atualizou a imagem para o dispositivo ESP32 DevKit. Você conectou o Kit de Desenvolvimento ESP32 ao Hub IoT do Azure e realizou tarefas como exibir a telemetria e chamar métodos no dispositivo.

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