Início Rápido: Implantar seu primeiro módulo do IoT Edge em um dispositivo virtual Linux

Artigo
04/11/2024

Aplica-se a: IoT Edge 1.4

Importante

A versão com suporte é a IoT Edge 1.4. Se você estiver em uma versão anterior, confira Atualizar o Azure IoT Edge.

Teste o Azure IoT Edge neste início rápido implantando um código em contêineres em um dispositivo virtual Linux do IoT Edge. O IoT Edge permite que você gerencie remotamente o código em seus dispositivos para que você possa enviar mais cargas de trabalho para a borda. Para este início rápido, recomendamos usar uma máquina virtual do Azure para o dispositivo IoT Edge, o que permitirá criar rapidamente um computador de teste e excluí-lo quando você terminar.

Neste guia de início rápido, você aprende a:

Crie um Hub IoT.
Registrar um dispositivo IoT Edge em seu Hub IoT.
Instalar e iniciar o runtime do IoT Edge em um dispositivo virtual.
Implantar um módulo em um dispositivo IoT Edge remotamente.

Diagrama da arquitetura do Guia de Início Rápido para dispositivo e nuvem.

Este Início Rápido orienta você pela criação de uma máquina virtual Linux configurada para ser um dispositivo do IoT Edge. Em seguida, implante um módulo do portal do Azure em seu dispositivo. O módulo usado neste guia de início rápido é um sensor simulado que gera dados de temperatura, umidade e pressão. Os outros tutoriais do Azure IoT Edge se baseiam no trabalho feito aqui com a implantação de módulos adicionais que analisam os dados simulados para obter informações de negócios.

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

Pré-requisitos

Prepare seu ambiente para a CLI do Azure.

Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, confira Início Rápido para Bash no Azure Cloud Shell.
Se preferir executar os comandos de referência da CLI localmente, instale a CLI do Azure. Para execuções no Windows ou no macOS, considere executar a CLI do Azure em um contêiner do Docker. Para obter mais informações, confira Como executar a CLI do Azure em um contêiner do Docker.
- Se estiver usando uma instalação local, entre com a CLI do Azure usando o comando az login. Para concluir o processo de autenticação, siga as etapas exibidas no terminal. Para ver outras opções de entrada, confira Conectar-se com a CLI do Azure.
- Quando solicitado, instale a extensão da CLI do Azure no primeiro uso. Para obter mais informações sobre extensões, confira Usar extensões com a CLI do Azure.
- Execute az version para localizar a versão e as bibliotecas dependentes que estão instaladas. Para fazer a atualização para a versão mais recente, execute az upgrade.

Recursos de nuvem:

Um grupo de recursos para gerenciar todos os recursos que você usará neste início rápido. Usamos o nome do grupo de recursos de exemplo IoTEdgeResources em todo este guia de início rápido e nos tutoriais a seguir.
```
az group create --name IoTEdgeResources --location westus2
```

Crie um hub IoT

Comece o início rápido criando um Hub IoT com a CLI do Azure.

Diagrama de como criar um hub IoT na nuvem.

O nível gratuito do Hub IoT funciona para este guia de início rápido. Se você tiver usado o Hub IoT antes e já tiver um hub criado, poderá usar esse Hub IoT.

O código a seguir cria um hub F1 gratuito no grupo de recursos IoTEdgeResources. Substitua {hub_name} por um nome exclusivo para o Hub IoT. A criação de um Hub IoT pode demorar alguns minutos.

az iot hub create --resource-group IoTEdgeResources --name {hub_name} --sku F1 --partition-count 2

Se você receber um erro porque já exsite um hub gratuito na sua assinatura, altere o SKU para S1. Cada assinatura pode ter somente um hub IoT gratuito. Caso você receba um erro que o nome do Hub IoT não está disponível, isso significa que alguém já tem um hub com esse nome. Tente usar um novo nome.

Registrar um dispositivo IoT Edge

Registre um dispositivo IoT Edge no Hub IoT recém-criado.

Diagrama de como registrar um dispositivo com uma identidade do Hub IoT.

Crie uma identidade do dispositivo para seu dispositivo IoT Edge para que ele possa se comunicar com o hub IoT. A identidade do dispositivo reside na nuvem e você usa uma cadeia de conexão de dispositivo exclusiva para associar um dispositivo físico a uma identidade do dispositivo.

Como os dispositivos IoT Edge se comportam e podem ser gerenciados diferentemente de dispositivos IoT comuns, declare essa identidade para ser um dispositivo IoT Edge com o sinalizador --edge-enabled.

No Azure Cloud Shell, digite o comando a seguir para criar um dispositivo denominado myEdgeDevice no seu hub.
```
az iot hub device-identity create --device-id myEdgeDevice --edge-enabled --hub-name {hub_name}
```
Se você receber um erro sobre as chaves de política do iothubowner, verifique se o Cloud Shell está executando a última versão da extensão azure-iot.
Veja a cadeia de conexão para o seu dispositivo, o que vincula o dispositivo físico à sua identidade no Hub IoT. Ele contém o nome do seu hub IoT, o nome do seu dispositivo e uma chave compartilhada que autentica as conexões entre os dois. Vamos nos referir a essa cadeia de conexão novamente na próxima seção quando você configurar seu dispositivo do IoT Edge.
```
az iot hub device-identity connection-string show --device-id myEdgeDevice --hub-name {hub_name}
```
Por exemplo, a cadeia de conexão deve parecer com HostName=contoso-hub.azure-devices.net;DeviceId=myEdgeDevice;SharedAccessKey=<DEVICE_SHARED_ACCESS_KEY>.

Configurar o dispositivo IoT Edge

Crie uma máquina virtual com o Azure runtime do IoT Edge nela.

Diagrama de como iniciar o runtime em um dispositivo.

O runtime do IoT Edge é implantado em todos os dispositivos IoT Edge. Tem três componentes. O daemon de segurança do IoT Edge é iniciado sempre que um dispositivo IoT Edge é iniciado e inicializa o dispositivo inicializando o agente do IoT Edge. O agente do IoT Edge facilita a implantação e o monitoramento de módulos no dispositivo IoT Edge, incluindo o hub do IoT Edge. O hub IoT Edge gerencia a comunicação entre os módulos no dispositivo IoT Edge e entre o dispositivo e o Hub IoT.

Durante a configuração do runtime, você precisa fornecer uma cadeia de conexão do dispositivo. Essa é a cadeia de caracteres que você recuperou da CLI do Azure. Essa cadeia de caracteres associa seu dispositivo físico à identidade do dispositivo IoT Edge no Azure.

Implantar o dispositivo do IoT Edge

Esta seção usa um modelo do Azure Resource Manager para criar uma máquina virtual e instalar o runtime do IoT Edge nela. Se você quiser usar seu dispositivo Linux, poderá seguir as etapas de instalação em Provisionar manualmente um dispositivo do IoT Edge no Linux e retorne a este início rápido.

Use o botão Implantar no Azure ou os comandos da CLI para criar seu dispositivo IoT Edge com base no modelo iotedge-vm-deploy pré-criado.

Implemente usando o modelo ARM IoT Edge Azure.

Para os usuários do Bash ou do Cloud Shell, copie o seguinte comando em um editor de texto, substitua o texto do espaço reservado pelas suas informações e copie-as na janela do Bash ou do Cloud Shell:

az deployment group create \
--resource-group IoTEdgeResources \
--template-uri "https://raw.githubusercontent.com/Azure/iotedge-vm-deploy/main/edgeDeploy.json" \
--parameters dnsLabelPrefix='<REPLACE_WITH_VM_NAME>' \
--parameters adminUsername='azureUser' \
--parameters deviceConnectionString=$(az iot hub device-identity connection-string show --device-id myEdgeDevice --hub-name <REPLACE_WITH_HUB_NAME> -o tsv) \
--parameters authenticationType='password' \
--parameters adminPasswordOrKey="<REPLACE_WITH_PASSWORD>"

Para usuários do PowerShell, copie o seguinte comando para a janela do PowerShell e substitua o texto do espaço reservado pelas suas informações:

az deployment group create `
--resource-group IoTEdgeResources `
--template-uri "https://raw.githubusercontent.com/Azure/iotedge-vm-deploy/main/edgeDeploy.json" `
--parameters dnsLabelPrefix='<REPLACE_WITH_VM_NAME>' `
--parameters adminUsername='azureUser' `
--parameters deviceConnectionString=$(az iot hub device-identity connection-string show --device-id myEdgeDevice --hub-name <REPLACE_WITH_HUB_NAME> -o tsv) `
--parameters authenticationType='password' `
--parameters adminPasswordOrKey="<REPLACE_WITH_PASSWORD>"

Este modelo usa os seguintes parâmetros:

Parâmetro	Descrição
resource-group	O grupo de recursos no qual os recursos serão criados. Use o IoTEdgeResources padrão que usamos neste artigo ou forneça o nome de um grupo de recursos em sua assinatura.
template-uri	Um ponteiro para o modelo do Resource Manager que estamos usando.
dnsLabelPrefix	Uma cadeia de caracteres que será usada para criar o nome de host da máquina virtual. Substitua o texto do espaço reservado por um nome para a sua máquina virtual.
adminUsername	Um nome de usuário para a conta do administrador da máquina virtual. Use o exemplo azureUser ou fornecer um novo nome de usuário.
deviceConnectionString	A cadeia de conexão da identidade do dispositivo no Hub IoT, que é usada para configurar o runtime do IoT Edge na máquina virtual. O comando da CLI dentro desse parâmetro captura a cadeia de conexão para você. Substitua o texto do espaço reservado pelo nome do hub IoT.
authenticationType	O método de autenticação para a conta do administrador. Este guia de início rápido usa autenticação por senha, mas você também pode definir esse parâmetro como sshPublicKey.
adminPasswordOrKey	A senha ou o valor da chave SSH para a conta do administrador. Substitua o texto do espaço reservado por uma senha segura. Sua senha deve ter pelo menos 12 caracteres e ter três dos quatro seguintes itens: caracteres minúsculos, caracteres maiúsculos, dígitos e caracteres especiais.

Depois que a implantação for concluída, você deverá receber a saída formatada em JSON na CLI que contém as informações de SSH para se conectar à máquina virtual. Copie o valor da entrada de SSH pública da seção saídas. Por exemplo, seu comando SSH deve parecer com ssh azureUser@edge-vm.westus2.cloudapp.azure.com.

Veja o status do runtime do IoT Edge

O restante dos comandos neste início rápido ocorrem em seu dispositivo IoT Edge propriamente dito, para que você possa ver o que está acontecendo no dispositivo. Se você estiver usando uma máquina virtual, conecte-se a esse computador agora usando o nome de usuário do administrador que você configurou e o nome DNS que foi apresentado pelo comando de implantação. Também é possível encontrar o nome DNS em sua página de visão geral da máquina virtual no portal do Azure. Use o comando a seguir para se conectar à sua máquina virtual. Substitua {admin username} e {DNS name} pelos seus próprios valores.

ssh {admin username}@{DNS name}

Uma vez conectado à sua máquina virtual, verifique se o runtime foi instalado e configurado com êxito em seu dispositivo do IoT Edge.

Verifique se o IoT Edge está sendo executado. O comando a seguir deverá retornar o status OK se o IoT Edge estiver em execução ou fornecer erros de serviço.
```
sudo iotedge system status
```
Dica

Você precisa de privilégios elevados para executar comandos iotedge. Depois que você sair da sua máquina e fizer login novamente na primeira vez após instalar o runtime do IoT Edge, suas permissões serão atualizadas automaticamente. Até lá, use sudo na frente dos comandos.
Se você precisar solucionar problemas do serviço, recupere os logs de serviço.
```
sudo iotedge system logs
```
Exiba todos os módulos em execução no seu dispositivo IoT Edge. Como o serviço acabou de ser iniciado pela primeira vez, você só verá o módulo edgeAgent em execução. O módulo edgeAgent é executado por padrão e ajuda a instalar e a iniciar quaisquer módulos adicionais que você implante em seu dispositivo.
```
sudo iotedge list
```

Seu dispositivo IoT Edge já está configurado. Ele está pronto para executar os módulos implantados na nuvem.

Implantar um módulo

Gerencie o dispositivo Azure IoT Edge na nuvem para implantar um módulo que enviará dados telemétricos ao Hub IoT.

Diagrama de como implantar um módulo da nuvem para o dispositivo.

Uma das principais funcionalidades do Azure IoT Edge é a implantação do código nos seus dispositivos IoT Edge por meio da nuvem. Módulos do IoT Edge são pacotes executáveis implementados como contêineres. Nesta seção, você implantará um módulo predefinido na seção Módulos do IoT Edge do Azure Marketplace diretamente no Hub IoT do Azure.

O módulo que você implanta nesta seção simula um sensor e envia os dados gerados. Esse módulo é uma informação útil de código quando você estiver começando a usar o IoT Edge porque você pode usar os dados simulados para desenvolvimento e teste. Se quiser ver exatamente o que esse módulo faz, você poderá exibir o código-fonte do sensor de temperatura simulado.

Siga estas etapas para iniciar o assistente Definir Módulos para implantar seu primeiro módulo do Azure Marketplace.

Entre no portal do Azure e acesse seu hub IoT.
No menu à esquerda, em Gerenciamento de Dispositivo, selecione Dispositivos.
Escolha a identificação do dispositivo IoT Edge de destino na lista.

Quando você criar um novo dispositivo do IoT Edge, ele exibirá o código de status 417 -- The device's deployment configuration is not set no portal do Azure. Esse status é normal e significa que o dispositivo está pronto para receber uma implantação do módulo.
Na barra superior, selecione Definir Módulos.

Escolha quais módulos deseja executar no dispositivo. Você pode escolher entre módulos que já tenha criado, módulos do Azure Marketplace ou módulos que você mesmo tenha criado. Neste início rápido, você implantará um módulo do Azure Marketplace.
Em Módulos do IoT Edge, abra o menu suspenso Adicionar e selecione Módulo do Marketplace.
Em Marketplace do Módulo do IoT Edge, procure e selecione o módulo Simulated Temperature Sensor. O módulo será adicionado à seção Módulos do IoT Edge com o status em execução desejado.
Selecione Avançar: Rotas para continuar a configurar rotas.

Uma rota chamada SimulatedTemperatureSensorToIoTHub foi criada automaticamente quando você adicionou o módulo do Azure Marketplace. Essa rota envia todas as mensagens do módulo de temperatura simulada para o Hub IoT.
Selecione Avançar: Revisar + criar.
Examine o arquivo JSON e selecione Criar. O arquivo JSON define todos os módulos que você implanta no seu dispositivo IoT Edge.

Observação

Quando você envia uma nova implantação para um dispositivo IoT Edge, nada é enviado por push para o seu dispositivo. Em vez disso, o dispositivo consulta o Hub IoT regularmente para verificar se há novas instruções. Se o dispositivo encontrar um manifesto de implantação atualizada, ele usará as informações sobre a nova implantação para efetuar pull das imagens de módulo da nuvem e, em seguida, começa a executar os módulos localmente. Esse processo pode levar alguns minutos.

Depois que você criar os detalhes de implantação do módulo, o assistente direcionará você à página de detalhes do dispositivo. Veja o status da implantação na guia Módulos.

Você verá três módulos: $edgeAgent, $edgeHub e SimulatedTemperatureSensor. Se um ou mais módulos mostrarem Sim em Especificado na Implantação, mas não em Relatado pelo Dispositivo, isso indicará que o dispositivo IoT Edge ainda está iniciando os módulos. Aguarde alguns minutos e atualize a página.

Se tiver problemas para implantar módulos, consulte Solucionar problemas de dispositivos do IoT Edge no portal do Azure.

Exibir os dados gerados

Neste guia de início rápido, você criou um novo dispositivo IoT Edge e instalou o runtime do IoT Edge nele. Em seguida, você usou o portal do Azure para implantar um módulo do IoT Edge para ser executado no dispositivo sem precisar fazer alterações no próprio dispositivo.

Nesse caso, o módulo enviado por push gera dados de ambiente de exemplo que você pode usar para testar mais tarde. O sensor simulado está monitorando um computador e o ambiente em torno do computador. Por exemplo, esse sensor pode estar em uma sala de servidor, em um chão de fábrica ou em uma turbina eólica. A mensagem inclui a temperatura ambiente e umidade, temperatura do computador, pressão e um carimbo de data/hora. Os tutoriais do IoT Edge usam os dados criados por esse módulo de dados de teste para análise.

Abra novamente o prompt de comando no seu dispositivo IoT Edge ou use a conexão SSH na CLI do Azure. Confirme se o módulo implantado da nuvem está em execução no seu dispositivo IoT Edge:

sudo iotedge list

Exiba as mensagens que estão sendo enviadas do módulo do sensor de temperatura:

sudo iotedge logs SimulatedTemperatureSensor -f

Dica

Ao fazer referência a nomes de módulo, comandos do IoT Edge diferenciam maiúsculas de minúsculas.

Limpar os recursos

Se você deseja prosseguir para os tutoriais do IoT Edge, pode usar o dispositivo registrado e configurado neste guia de início rápido. Caso contrário, você pode excluir os recursos do Azure que criou para evitar encargos.

Se você tiver criado a sua máquina virtual e o Hub IoT em um novo grupo de recursos, é possível excluir esse grupo e todos os recursos associados. Verifique novamente o conteúdo do grupo de recursos para ter certeza de que não haja nada que você queira manter. Caso não queira excluir o grupo inteiro, é possível excluir recursos individuais em vez disso.

Importante

A exclusão de um grupo de recursos é irreversível.

Remova o grupo IoTEdgeResources. A exclusão de um grupo de recursos pode demorar alguns minutos.

az group delete --name IoTEdgeResources --yes

Para confirmar se o grupo de recursos foi removido, veja a lista de grupos de recursos.

az group list

Próximas etapas

Neste início rápido, você criou um dispositivo IoT Edge e usou a interface de nuvem do Azure IoT Edge para implantar código no dispositivo. Agora, você tem um dispositivo de teste que gera dados brutos sobre seu ambiente.

No próximo tutorial, você aprenderá a monitorar a atividade e a integridade do seu dispositivo no portal do Azure.

Monitorar dispositivos do IoT Edge