Tutorial: Conectar um ESPRESSIF ESP32-Azure IoT Kit ao Hub IoT

Artigo
11/11/2024

Neste tutorial, você usa o middleware do Azure IoT para FreeRTOS para conectar o ESPRESSIF ESP32-Azure IoT Kit (doravante, o ESP32 DevKit) ao Azure IoT.

Conclua as seguintes tarefas:

Instale um conjunto de ferramentas de desenvolvimento incorporadas para programar um ESP32 DevKit
Crie uma imagem e pisce-a no ESP32 DevKit
Use a CLI do Azure para criar e gerenciar um hub IoT do Azure ao qual o ESP32 DevKit se conecta
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
Git para clonar o repositório
Equipamento
- ESPRESSIF ESP32-Azure IoT Kit
- USB 2.0 Um cabo macho para Micro USB macho
- Wi-Fi de 2,4 GHz
Uma subscrição ativa do Azure. Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Preparar o ambiente de desenvolvimento

Instale as ferramentas

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

Para instalar as ferramentas ESP-IDF:

Transfira e inicie o instalador offline 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 todo o código de dispositivo de exemplo, scripts de configuração e documentação do SDK. Se você clonou anteriormente este repositório, não precisa fazê-lo novamente.

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

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

Para o Windows 10 e 11, certifique-se de que os caminhos longos estão ativados.

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

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:

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

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

Instale o Azure IoT Explorer. Esta ferramenta é um utilitário multiplataforma para monitorar e gerenciar recursos do Azure IoT.
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}
```
Copie a cadeia de conexão sem os caracteres de cotação ao redor.
No Azure IoT Explorer, selecione Hubs IoT no menu à esquerda.
Selecione + Adicionar ligação.
Cole a cadeia de conexão na caixa Cadeia de conexão .
Selecione Guardar.

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:

No IoT Explorer, selecione Página Inicial para retornar ao modo de exibição inicial.
No menu à esquerda, selecione Configurações Plug and Play da IoT.
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:

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:

Na visualização inicial no IoT Explorer, selecione Hubs IoT.
A conexão que você adicionou anteriormente deve aparecer. Selecione Exibir dispositivos neste hub abaixo das propriedades de conexão.
Selecione + Novo e insira um ID de dispositivo para o seu dispositivo, por exemplo, mydevice. Deixe todas as outras propriedades iguais.
Selecione Criar.
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 ESP32 DevKit ao Azure, modifique as definições de configuração, crie a imagem e pisce a imagem no dispositivo.

Configurar o ambiente

Para iniciar o ambiente ESP-IDF:

Selecione Iniciar do Windows, localize ESP-IDF 5.0 CMD e execute-o.
No ESP-IDF 5.0 CMD, navegue até o diretório iot-middleware-freertos-samples que você clonou anteriormente.
Navegue até o diretório de projeto do ESP32-Azure IoT Kit 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 de rede sem fio:

No ESP-IDF 5.0 CMD, selecione Azure IoT middleware for FreeRTOS Sample Configuration ---> e pressione Enter.
Defina as seguintes definições de configuração usando suas credenciais de rede sem fio local.

Definição Value

WiFi SSID {O seu SSID Wi-Fi}

Palavra-passe WiFi {A sua palavra-passe Wi-Fi}
Selecione Esc para voltar ao menu anterior.

Definição	Value
WiFi SSID	{O seu SSID Wi-Fi}
Palavra-passe WiFi	{A sua palavra-passe Wi-Fi}

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

Selecione Azure IoT middleware for FreeRTOS Main Task Configuration ---> e pressione Enter.

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

Definição	Value
Azure IoT Hub FQDN	{O seu nome de anfitrião}
ID do dispositivo IoT do Azure	{ID do seu dispositivo}
Chave Simétrica de Dispositivo IoT do Azure	{A sua chave primária}

Nota

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

Selecione Esc para voltar ao menu anterior.

Para salvar a configuração:

Selecione Shift+S para abrir as opções de salvamento. Este menu permite que você salve 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.

Construir e piscar a imagem

Nesta seção, você usa as ferramentas ESP-IDF para criar, piscar e monitorar o ESP32 DevKit à medida que ele se conecta ao Azure IoT.

Nota

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

Para construir a imagem:

No ESP-IDF 5.0 CMD, no diretório iot-middleware-freertos-samples\demos\projects\ESPRESSIF\aziotkit , execute o seguinte comando para criar a imagem.
```
idf.py --no-ccache -B "C:\espbuild" build 
```
Após a conclusão da compilação, 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 piscar a imagem:

No ESP32 DevKit, localize a porta Micro USB, que é realçada na imagem a seguir:
Ligue o cabo Micro USB à porta Micro USB no ESP32 DevKit e, em seguida, ligue-o ao computador.
Abra o Gestor de Dispositivos do Windows e veja Portas para descobrir a que porta COM o ESP32 DevKit está ligado.
No ESP-IDF 5.0 CMD, execute o seguinte comando, substituindo o espaço reservado e os <colchetes da porta Your-COM-port> 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 é concluída com o seguinte texto para um flash bem-sucedido:
```
Hash of data verified

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

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

No ESP-IDF 5.0 CMD, execute o seguinte comando 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 repetidos de saída semelhantes ao exemplo a seguir. Essa saída confirma que o dispositivo se conecta ao Azure IoT 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...

Ver propriedades do dispositivo

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

Na vista inicial no Explorador do IoT, selecione Hubs IoT e, em seguida, selecione Ver dispositivos neste hub.
Selecione o seu dispositivo.
Selecione Componentes IoT Plug and Play.
Selecione Componente padrão. O IoT Explorer exibe os componentes IoT Plug and Play implementados no seu dispositivo.

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	`Espressif ESP32 Azure IoT Kit`	Exemplo de modelo de dispositivo para o ESP32 DevKit
Propriedades (graváveis)	Property	`telemetryFrequencySecs`	O intervalo que o dispositivo envia telemetria
Comandos	Comando	`ToggleLed1`	Ligue ou desligue o LED
Comandos	Comando	`ToggleLed2`	Ligue ou desligue o LED
Comandos	Comando	`DisplayText`	Exibe o texto enviado na tela do dispositivo

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

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

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

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.

Gorjeta

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

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:

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.
Selecione Iniciar.
Visualize a telemetria enquanto o dispositivo envia mensagens para a 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 terminar 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 que você criou anteriormente no Azure IoT para seu dispositivo e hub IoT.
```
az iot hub monitor-events --device-id mydevice --hub-name {YourIoTHubName}
```

Exiba a saída JSON no 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

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:

No painel Componentes Plug and Play da IoT (Componente Padrão) do seu dispositivo no IoT Explorer, selecione a guia Comandos.
Para o comando ToggleLed1 , selecione Enviar comando. O LED no ESP32 DevKit liga ou desliga. Você também deve ver 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 ESP32 DevKit.

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 a carga útil. Para esse método, a configuração method-payload significa true 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 de método no dispositivo, onde 200 indica sucesso.
```
{
  "payload": {},
  "status": 200
} 
```
Verifique o dispositivo para confirmar o estado do LED.

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:

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
```
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 middleware do Azure IoT para código de exemplo FreeRTOS e, em seguida, piscou a imagem para o dispositivo ESP32 DevKit. Você conectou o ESP32 DevKit ao Hub IoT do Azure e executou tarefas como exibir telemetria e métodos de chamada no dispositivo.

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

Partilhar via