Tutorial: Desenvolver módulos do IoT Edge com contêineres do Linux usando o IoT Edge para Linux no Windows

Aplica-se a: IoT Edge 1.5 IoT Edge 1.4

Este tutorial explica como desenvolver, depurar e implantar seu próprio código em um dispositivo Azure IoT Edge usando o IoT Edge para Windows no Windows e o Visual Studio 2022. Você aprenderá o cenário de desenvolvedor mais comum para soluções do IoT Edge implantando um módulo do C# em um dispositivo Linux. Você implantará e depurará um módulo personalizado do IoT Edge em execução em um contêiner do Linux no Windows. Mesmo se você planeja usar uma linguagem diferente ou implantar um serviço do Azure, este tutorial ainda será útil para saber mais sobre os conceitos e as ferramentas de desenvolvimento.

Este tutorial inclui etapas para duas ferramentas de desenvolvimento do IoT Edge:

• A interface de linha de comando (CLI) da Ferramenta de Desenvolvimento do Azure IoT Edge, que é a ferramenta recomendada para desenvolvimento
• A extensão Azure IoT Edge Tools para Visual Studio, que está em modo de manutenção

Use o botão seletor no início deste tutorial para selecionar a versão da ferramenta.

Neste tutorial, você aprenderá como:

Pré-requisitos

Este tutorial presume que você esteja usando um computador Windows como seu computador de desenvolvimento. Em computadores Windows, você pode desenvolver módulos do Windows ou do Linux. Este tutorial orienta você no desenvolvimento de contêineres do Linux, usando o IoT Edge para Linux no Windows para compilar e implantar os módulos.

Antes de começar:

• Instale o IoT Edge para Linux no Windows.

• Leia o início rápido Implantar seu primeiro módulo do IoT Edge em um dispositivo Windows.

• Baixe o SDK do .NET Core.

• Instale ou modifique o Visual Studio 2022 no seu computador de desenvolvimento. Escolha as opções de carga de trabalho Desenvolvimento do Azure e Desenvolvimento de área de trabalho com C++.

• Após a conclusão da instalação do Visual Studio 2022, baixe e instale o Azure IoT Edge Tools no Visual Studio Marketplace.

  Você pode usar a extensão Azure IoT Edge Tools para criar e compilar sua solução do IoT Edge. A ferramenta de desenvolvimento recomendada é a CLI da Ferramenta de Desenvolvimento do Azure IoT Edge. A extensão inclui os modelos de projeto do Azure IoT Edge que você usa para criar o projeto do Visual Studio. Atualmente, você precisa instalar a extensão independentemente da ferramenta de desenvolvimento usada.

  Dica

  Se você estiver usando o Visual Studio 2019, baixe e instale o Azure IoT Edge Tools para Visual Studio 2019 no Visual Studio Marketplace.

• Crie um hub IoT de camada gratuita ou standard como um recurso de nuvem.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Principais conceitos

Este tutorial explica o desenvolvimento de um módulo do IoT Edge. Um módulo do IoT Edge é um contêiner que tem código executável. É possível implantar um ou mais módulos em um dispositivo IoT Edge. Módulos executam tarefas específicas, como ingerir dados de sensores, limpar e analisar dados ou enviar mensagens a um hub IoT. Para saber mais, confira Understand Azure IoT Edge modules (Noções básicas sobre módulos do Azure IoT Edge).

Ao desenvolver módulos do IoT Edge, é importante entender a diferença entre o computador de desenvolvimento e o dispositivo IoT Edge de destino em que o módulo será implantado eventualmente. O contêiner que você criar para armazenar seu código de módulo deverá corresponder ao SO (sistema operacional) do dispositivo de destino.

Por exemplo, o cenário mais comum é alguém desenvolver um módulo em um computador Windows com a intenção de direcionar um dispositivo Linux que executa o IoT Edge. Nesse caso, o sistema operacional do contêiner é Linux.

Ao percorrer este tutorial, lembre-se a diferença entre o sistema operacional do computador de desenvolvimento e o sistema operacional do contêiner. Para este tutorial, você usará o host do Windows para desenvolvimento e a máquina virtual (VM) do IoT Edge para Linux no Windows para compilar e implantar os módulos.

Este tutorial tem como destino dispositivos que executam o IoT Edge com contêineres do Linux. É possível usar o sistema operacional de sua preferência, contanto que o computador de desenvolvimento execute contêineres do Linux. É recomendável usar o Visual Studio para desenvolver com contêineres do Linux, portanto, é isso que o tutorial usa. Você também pode usar o Visual Studio Code, embora haja diferenças no suporte entre as duas ferramentas. Para obter mais informações, confira Desenvolver módulos do Azure IoT Edge usando o Visual Studio Code.

Configurar a CLI do Docker e o mecanismo do Docker para conexão remota

Os módulos do IoT Edge são empacotados como contêineres, portanto, você precisa de um mecanismo de contêiner no computador de desenvolvimento para criar e gerenciá-los.

A VM do IoT Edge para Linux no Windows já contém uma instância do mecanismo do Docker. Este tutorial mostra como se conectar remotamente do computador de desenvolvedor do Windows à instância do Docker da VM do IoT Edge para Linux no Windows. Usando essa conexão remota, você remove a dependência do Docker Desktop para Windows.

Configurar a CLI do Docker

A primeira etapa é configurar a CLI do Docker no computador de desenvolvimento do Windows para poder se conectar ao mecanismo remoto do Docker:

1. Baixe a versão docker.exe pré-compilada da CLI do Docker do Chocolatey. Você também pode baixar o projeto oficial cli do GitHub e compilá-lo seguindo as instruções do repositório.

2. Extraia docker.exe para um diretório em seu computador de desenvolvimento; por exemplo, C:\Docker\bin.

3. Abra Sobre o computador>Informações do sistema>Configurações avançadas do sistema.

4. Selecione Avançado>Variáveis do ambiente. Em Variáveis de usuário, selecione Path.

5. Edite a variável Path e adicione o local do docker.exe.

6. Abra uma sessão do PowerShell elevada.

7. Verifique se a CLI do Docker está acessível usando este comando:

   docker --version
   

   Se você configurou tudo com êxito, a saída do comando deve mostrar a versão do Docker. Ele deve ser semelhante a Docker version 20.10.12, build e91ed57.

Configurar o mecanismo do Docker

A segunda etapa é configurar o mecanismo do Docker da VM do IoT Edge para Linux no Windows para aceitar conexões externas e adicionar as regras de firewall apropriadas.

1. Abra uma sessão do PowerShell com privilégios elevados e execute os seguintes comandos:

   # Configure the IoT Edge for Linux on Windows VM Docker engine to accept external connections, and add the appropriate firewall rules.
   Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 2375 -j ACCEPT"
   
   # Create a copy of the IoT Edge for Linux on Windows VM _docker.service_ in the system folder.
   Invoke-EflowVmCommand "sudo cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service"
   
   # Replace the service execution line to listen for external connections.
   Invoke-EflowVmCommand "sudo sed -i 's/-H fd:\/\// -H fd:\/\/ -H tcp:\/\/0.0.0.0:2375/g'  /etc/systemd/system/docker.service"
   
   # Reload the IoT Edge for Linux on Windows VM services configurations.
   Invoke-EflowVmCommand "sudo systemctl daemon-reload"
   
   # Reload the Docker engine service.
   Invoke-EflowVmCommand "sudo systemctl restart docker.service"
   
   # Check that the Docker engine is listening to external connections.
   Invoke-EflowVmCommand "sudo netstat -lntp | grep dockerd"
   

   Este é um exemplo de saída:

   PS C:\> # Configure the IoT Edge for Linux on Windows virtual machine Docker engine to accept external connections, and add the appropriate firewall rules.
   PS C:\> Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 2375 -j ACCEPT"
   PS C:\>
   PS C:\> # Create a copy of the IoT Edge for Linux on Windows VM docker.service in the system folder.
   PS C:\> Invoke-EflowVmCommand "sudo cp /lib/systemd/system/docker.service /etc/systemd/system/docker.service"
   PS C:\>
   PS C:\> # Replace the service execution line to listen for external connections.
   PS C:\> Invoke-EflowVmCommand "sudo sed -i 's/-H fd:\/\// -H fd:\/\/ -H tcp:\/\/0.0.0.0:2375/g' /etc/systemd/system/docker.service"
   PS C:\>
   PS C:\> # Reload the IoT Edge for Linux on Windows VM services configurations.
   PS C:\> Invoke-EflowVmCommand "sudo systemctl daemon-reload"
   PS C:\>
   PS C:\> # Reload the Docker engine service.
   PS C:\> Invoke-EflowVmCommand "sudo systemctl restart docker.service"
   PS C:\>
   PS C:\> # Check that the Docker engine is listening to external connections.
   PS C:\> Invoke-EflowVmCommand "sudo netstat -lntp | grep dockerd"
   tcp6       0      0 :::2375                 :::*                    LISTEN      2790/dockerd
   

Testar a conexão

A etapa final de instalação é testar a conexão do Docker com o mecanismo do Docker da VM do IoT Edge para Linux no Windows:

1. Obtenha o endereço IP da VM do IoT Edge para Linux no Windows:

   Get-EflowVmAddr
   

   Dica

   Se a VM do IoT Edge para Linux no Windows foi implantada sem um IP estático, o endereço IP poderá ser alterado nas reinicializações ou alterações de rede do sistema operacional host do Windows. Verifique se você está usando o endereço IP correto para a VM do IoT Edge para Linux no Windows sempre que quiser estabelecer uma conexão remota com o mecanismo do Docker.

   Este é um exemplo de saída:

   PS C:\> Get-EflowVmAddr
   [03/15/2022 15:22:30] Querying IP and MAC addresses from virtual machine (DESKTOP-J1842A1-EFLOW)
    - Virtual machine MAC: 00:15:5d:6f:da:78
    - Virtual machine IP : 172.31.24.105 retrieved directly from virtual machine
   00:15:5d:6f:da:78
   172.31.24.105 
   

2. Conecte-se ao mecanismo do Docker da VM do IoT Edge para Linux no Windows e execute o contêiner de exemplo hello-world. Substitua <EFLOW-VM-IP> pelo endereço IP da VM do IoT Edge para Linux no Windows obtido na etapa anterior.

   docker -H tcp://<EFLOW-VM-IP>:2375 run --rm hello-world
   

   Quando o download do contêiner for concluído, o contêiner será executado e produzirá essa saída:

   PS C:\> docker -H tcp://172.31.24.105:2375 run --rm hello-world
   Unable to find image 'hello-world:latest' locally
   latest: Pulling from library/hello-world
   2db29710123e: Pull complete
   Digest: sha256:4c5f3db4f8a54eb1e017c385f683a2de6e06f75be442dc32698c9bbe6c861edd
   Status: Downloaded newer image for hello-world:latest
   
   Hello from Docker!
   This message shows that your installation appears to be working correctly.
   
   To generate this message, Docker took the following steps:
    1. The Docker client contacted the Docker daemon.
    2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
       (amd64)
    3. The Docker daemon created a new container from that image which runs the
       executable that produces the output you're currently reading.
    4. The Docker daemon streamed that output to the Docker client, which sent it
       to your terminal.
   
   To try something more ambitious, you can run an Ubuntu container with:
    $ docker run -it ubuntu bash
   
   Share images, automate workflows, and more with a free Docker ID:
    https://hub.docker.com/
   
   For more examples and ideas, visit:
    https://docs.docker.com/get-started/
   

Criar um projeto do Azure IoT Edge

O modelo de projeto do IoT Edge no Visual Studio cria uma solução que você pode implantar em dispositivos IoT Edge. Use as etapas a seguir para criar uma solução do Azure IoT Edge e gere o primeiro módulo nessa solução. Cada solução do IoT Edge pode conter mais de um módulo.

1. No Visual Studio, crie um novo projeto selecionando Criar um novo projeto na página inicial ou selecionando o botão Novo Projeto na barra de ferramentas.

2. Na página Criar um novo projeto, procure Azure IoT Edge. Selecione o projeto que corresponde à plataforma (módulo do IoT Edge do Linux) e à arquitetura de seu dispositivo IoT Edge e selecione Avançar.

3. Na página Configurar novo projeto, insira um nome para o projeto, especifique o local e selecione Criar.

4. Na caixa de diálogo Adicionar Módulo, selecione o tipo de módulo que você deseja desenvolver. Você também pode selecionar Módulo existente para adicionar um módulo do IoT Edge existente à sua implantação.

5. Em Nome do Módulo, especifique o nome do módulo.

6. Em URL do Repositório, forneça o nome do repositório de imagens do módulo. O Visual Studio preenche automaticamente o nome do módulo com localhost:5000/<nome do seu módulo>. Substitua-o pelas informações de seu registro.

   Use localhost se você usa um registro local do Docker para testes. Se usar o Registro de Contêiner do Azure, utilize o servidor de início de sessão nas configurações do registro. O servidor de início de seção é semelhante a <nome do registro>.azurecr.io. Substitua apenas a parte da cadeia de caracteres localhost:5000 para que o resultado final se parece com <nome do registro>.azurecr.io/<nome do seu módulo>.

7. Selecione Adicionar para adicionar o módulo ao projeto.

   

   Observação

   Se você tiver um projeto do IoT Edge existente, poderá alterar o URL do repositório abrindo o arquivo module.json. O URL do repositório está localizado na propriedade repository do arquivo JSON.

Agora você tem um projeto do IoT Edge e um módulo do IoT Edge na sua solução do Visual Studio.

Estrutura do projeto

Sua solução tem duas pastas de nível de projeto: uma pasta de projeto principal e uma pasta de módulo. Por exemplo, você pode ter uma pasta de projeto principal chamada AzureIotEdgeApp1 e uma pasta de módulo chamada IotEdgeModule1.

A pasta de projeto principal contém o manifesto de implantação. O manifesto de implantação é um documento JSON que descreve os módulos a serem configurados nos dispositivos IoT Edge de destino.

A pasta de módulo contém um arquivo para o código do módulo. Ele se chama Program.cs ou main.c, dependendo da linguagem escolhida. Essa pasta também contém um arquivo chamado module.json que descreve os metadados do seu módulo. Vários arquivos do Docker fornecem as informações necessárias para criar seu módulo como um contêiner do Windows ou do Linux.

Manifesto de implantação do seu projeto

O manifesto de implantação que você edita se chama deployment.debug.template.json. Esse arquivo é um modelo de um manifesto de implantação do IoT Edge que define todos os módulos que são executados em um dispositivo. O arquivo também define como os módulos se comunicam entre si. Para obter mais informações sobre a criação de manifestos de implantação, confira o artigo Saiba como implantar módulos e estabelecer rotas.

O modelo de implantação inclui:

• Os dois módulos de runtime, edgeAgent e edgeHub.
• O módulo personalizado que você criou neste projeto do Visual Studio.
• Um módulo chamado SimulatedTemperatureSensor. Este módulo padrão gera dados simulados que você pode usar para testar seus módulos (ou excluir se não for necessário). Para ver como o sensor de temperatura simulado funciona, veja o código-fonte do SimulatedTemperatureSensor.csproj.

Definir a versão de runtime do IoT Edge

Atualmente, a versão do runtime estável mais recente é a 1.4. Atualize a versão de runtime do IoT Edge para a versão estável mais recente ou a versão que deseja direcionar para seus dispositivos:

Desenvolver seu módulo

Quando você adiciona um novo módulo, ele vem com o código padrão que está pronto para ser compilado e implantado em um dispositivo para que você possa começar a testar sem lidar com nenhum código. O código do módulo está localizado na pasta do módulo em um arquivo chamado Program.cs (para C#) ou main.c (para C).

Na solução padrão, os dados simulados do módulo SimulatedTemperatureSensor são roteados para o seu módulo. O módulo usa a entrada e a envia para o Hub IoT do Azure.

Quando você estiver pronto para personalizar o modelo do módulo com seu próprio código, use os SDKs do Hub IoT do Azure para criar outros módulos que atendam às principais necessidades de soluções de IoT. Essas necessidades podem incluir segurança, gerenciamento de dispositivos e confiabilidade.

Criar e efetuar push de um único módulo

Normalmente, queremos testar/depurar cada módulo antes de colocá-lo em execução dentro de uma solução com vários módulos. Como a solução será criar ou depurar usando o mecanismo do Docker em execução na VM do IoT Edge para Linux no Windows, a primeira etapa será criar e publicar o módulo para habilitar a depuração remota:

1. No Gerenciador de Soluções, selecione a pasta do projeto do módulo (por exemplo, myIotEdgeModule).

2. Defina o módulo personalizado como o projeto de inicialização. No menu, selecione Projeto>Definir como Projeto de Inicialização.

3. Para depurar o módulo C# Linux, você precisa atualizar o arquivo Dockerfile.amd64.debug para habilitar o serviço SSH. Atualize o arquivo Dockerfile.amd64.debug para usar o seguinte modelo: Dockerfile for Azure IoT Edge AMD64 C# Module with Remote Debug Support.

   Observação

   Ao selecionar Depurar, o Visual Studio usará Dockerfile.(amd64|windows-amd64).debug para criar imagens do Docker. Esse arquivo inclui o VSDBG, depurador de linha de comando do .NET Core, na imagem de contêiner durante a criação. É recomendável que você use a configuração Versão que usa o Dockerfile.(amd64|windows-amd64) sem o VSDBG para os módulos do IoT Edge prontos para produção.

   Verifique se a última linha do modelo, ENTRYPOINT ["dotnet", "IotEdgeModule1.dll"], nome da DLL corresponde ao nome do projeto do módulo do IoT Edge.

4. Para estabelecer uma conexão SSH com o módulo do Linux, você precisa criar uma chave RSA. Abra uma sessão do PowerShell com privilégios elevados e execute os seguintes comandos para criar uma chave RSA. Salve a chave RSA na mesma pasta de módulo do IoT Edge e verifique se o nome da chave é id_rsa.

   ssh-keygen -t RSA -b 4096 -m PEM
   

   

5. Se estiver usando um registro privado, como o Registro de Contêiner do Azure, use o seguinte comando do Docker para se conectar a ele. Você pode obter o nome de usuário e a senha na página Chaves de acesso do seu registro no portal do Azure. Se estiver usando o registro local, você poderá executar um registro local.

   docker -H tcp://<EFLOW-VM-IP>:2375 login -u <Container Registry username> -p <Container Registry password> <Container Registry login server>
   

docker build --rm -f "<DockerFilePath>" -t <ImageNameAndTag> "<ContextPath>" 

# Build the image for the local registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t localhost:5000/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

# Or build the image for an Azure container registry

docker build --rm -f "./IotEdgeModule1/Dockerfile.amd64.debug" -t myacr.azurecr.io/iotedgemodule1:0.0.1-amd64 "./IotEdgeModule1"

# Push the Docker image to the local registry

docker push localhost:5000/iotedgemodule1:0.0.1-amd64

# Or push the Docker image to an Azure container registry
az acr login --name myacr
docker push myacr.azurecr.io/iotedgemodule1:0.0.1-amd64

Depurar a solução

1. Em uma sessão do PowerShell com privilégios elevados, execute os seguintes comandos:

   1. Obtenha o valor moduleId, com base no nome usado para o módulo C# do Linux. Substitua o espaço reservado <iot-edge-module-name> pelo nome do seu módulo.

      $moduleId = Invoke-EflowVmCommand "sudo docker ps -aqf name=<iot-edge-module-name>"
      

   2. Verifique se $moduleId está correto. Se a variável estiver vazia, verifique se você está usando o nome do módulo correto.

   3. Iniciar o serviço SSH dentro do contêiner do Linux:

      Invoke-EflowVmCommand "sudo docker exec -it -d $moduleId service ssh start"
      

   4. Abra a porta SSH do módulo na VM do IoT Edge para Linux no Windows. (Este tutorial usa a porta 10022.)

      Invoke-EflowVmCommand "sudo iptables -A INPUT -p tcp --dport 10022 -j ACCEPT"
      

   Aviso

   Por motivos de segurança, sempre que a VM do IoT Edge para Linux no Windows é reiniciada, a regra da tabela IP é excluída e volta para as configurações originais. Além disso, você precisa reiniciar o serviço SSH do módulo manualmente.

2. Depois de iniciar o serviço SSH com êxito, selecione Depurar>Anexar ao Processo, definir Tipo de Conexão como SSH e definir Destino de conexão para o endereço IP da VM do IoT Edge para Linux no Windows. Se você não souber o endereço IP da VM do IoT Edge para Linux no Windows, poderá usar o cmdlet Get-EflowVmAddr do PowerShell.

   Digite o IP e selecione a tecla ENTER. Na janela pop-up, insira as seguintes configurações:

   Campo	Valor
   Nome do host	Endereço IP para a VM do IoT Edge para Linux no Windows
   Porta	10022 (ou aquela que você usou em sua configuração de implantação)
   Nome de usuário	root
   Tipo de autenticação	Chave Privada
   Arquivo de chave privada	Caminho completo para o valor id_rsa criado em uma etapa anterior
   Frase secreta	Frase secreta usada para a chave criada em uma etapa anterior

3. Depois de se conectar com êxito ao módulo usando SSH, você pode escolher o processo e selecionar Anexar. Para o módulo C#, você precisa escolher o processo dotnet e Anexá-lo a Gerenciado (CoreCLR). Pode levar de 10 a 20 segundos na primeira vez.

4. Definir um ponto de interrupção para inspecionar o módulo:

   • Se você estiver desenvolvendo em C#, defina um ponto de interrupção na função PipeMessage() em ModuleBackgroundService.cs.
   • Se estiver usando C, defina um ponto de interrupção na função InputQueue1Callback() em main.c.

5. A saída de SimulatedTemperatureSensor deve ser redirecionada para input1 do módulo C# personalizado do Linux. O ponto de interrupção deve ser disparado. Você pode assistir as variáveis na janela Locais do Visual Studio.

   

6. Para interromper a depuração, selecione Ctrl+F5 ou selecione o botão Parar.

Limpar os recursos

Se você pretende continuar no próximo artigo recomendado, pode manter os recursos e as configurações já criados e reutilizá-los. Você também pode continuar usando o mesmo dispositivo IoT Edge como um dispositivo de teste.

Caso contrário, exclua as configurações locais e os recursos do Azure usados neste artigo para evitar encargos.

Excluir recursos do Azure

A exclusão de recursos do Azure e dos grupos de recursos é irreversível. Não exclua acidentalmente grupo de recursos ou recursos incorretos. Se você criou o hub IoT em um grupo de recursos existente que contém recursos que deseja manter, exclua apenas o recurso do hub IoT, não o grupo de recursos.

Para excluir os recursos:

1. Entre no portal do Azure e selecione Grupos de recursos.

2. Selecione o nome do grupo de recursos que contém os recursos de teste do IoT Edge.

3. Examine a lista de recursos que seu grupo de recursos contém. Se você deseja excluir todos eles, selecione Excluir grupo de recursos. Se quiser excluir apenas alguns, clique em cada recurso para excluí-los individualmente.

Próxima etapa

Neste tutorial, você configurou o Visual Studio em seu computador de desenvolvimento e implantou e depurou seu primeiro módulo do IoT Edge a partir dele. Agora que você conhece os conceitos básicos, tente adicionar uma funcionalidade a um módulo para que ele possa analisar os dados que passam por ele: