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

Aplica-se a: IoT Edge 1.5

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

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

• A interface de linha de comando (CLI) da Ferramenta de Desenvolvimento do Azure IoT Edge, que é a ferramenta preferida para desenvolvimento.
• A extensão Azure IoT Edge Tools para Visual Studio, que está no modo 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 pressupõe que você use um computador executando Windows como seu computador de desenvolvimento. Em computadores Windows, você pode desenvolver módulos Windows ou Linux. Este tutorial orienta você pelo desenvolvimento de contêineres do Linux usando IoT Edge para Linux em Windows para compilar e implantar os módulos.

Antes de começar:

• Instale IoT Edge para Linux em Windows.

• Leia o tutorial rápido Implantar seu primeiro módulo de IoT Edge em um dispositivo Windows.

• Baixe o SDK do .NET Core.

• Instale ou modifique Visual Studio 2022 em seu computador de desenvolvimento. Escolha as opções de carga de trabalho desenvolvimento Azure e desenvolvimento Desktop com C++.

• Depois que a instalação do Visual Studio 2022 estiver pronta, baixe e instale Azure IoT Edge Tools do Visual Studio Marketplace.

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

  Dica

  Se você estiver usando Visual Studio 2019, baixe e instale Azure IoT Edge Tools for Visual Studio 2019 do Visual Studio Marketplace.

• Crie um hub IoT de camada padrão ou gratuito em Azure como um recurso de nuvem.

Se você não tiver uma conta Azure, crie uma conta free antes de começar.

Principais conceitos

Este tutorial explica o desenvolvimento de um módulo IoT Edge. Um módulo IoT Edge é um contêiner que tem código executável. Você pode 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 obter mais informações, consulte os módulos Understand Azure IoT Edge.

Quando você estiver desenvolvendo módulos IoT Edge, é importante entender a diferença entre o computador de desenvolvimento e o IoT Edge dispositivo de destino em que o módulo será eventualmente implantado. 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 desenvolvendo um módulo em um computador Windows que pretende direcionar um dispositivo Linux executando 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á seu host Windows para desenvolvimento e o IoT Edge para Linux em Windows VM (máquina virtual) para compilar e implantar os módulos.

Este tutorial tem como destino dispositivos que estão executando 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 Visual Studio para desenvolver com contêineres do Linux, portanto, é isso que este tutorial usa. Você também pode usar Visual Studio Code, embora haja diferenças no suporte entre as duas ferramentas. Para obter mais informações, consulte Develop Azure IoT Edge módulos usando Visual Studio Code.

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

Módulos IoT Edge são empacotados como contêineres, portanto, você precisa de um mecanismo de contêiner em seu computador de desenvolvimento para construí-los e gerenciá-los.

O IoT Edge para Linux em Windows VM já contém uma instância do mecanismo do Docker. Este tutorial mostra como conectar-se remotamente da máquina do desenvolvedor do Windows à instância do IoT Edge para Linux no Windows VM Docker. 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 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 de 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 IoT Edge para Linux no Windows VM Docker 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"
   

   Aqui está 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 da configuração é testar a conexão do Docker com o IoT Edge para Linux no mecanismo Docker da VM no Windows:

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

   Get-EflowVmAddr
   

   Dica

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

   Aqui está 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 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 de VM do IoT Edge para Linux em 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 de Azure IoT Edge

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

1. Em Visual Studio, crie um novo projeto selecionando Criar um novo projeto na página inicial ou selecionando o botão New Project na barra de ferramentas.

2. Na página Criar um novo projeto, pesquise Azure IoT Edge. Selecione o projeto que corresponde à plataforma (módulo linux IoT Edge) e à arquitetura do dispositivo IoT Edge e selecione Next.

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 o módulo Existing para adicionar um módulo 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. Visual Studio preenche automaticamente o nome do módulo com localhost:5000/<seu nome do módulo>. Substitua-o pelas informações de seu registro.

   Use localhost se você usa um registro local do Docker para testes. Se você usar Azure Container Registry, use o servidor de logon das configurações do registro. O servidor de início de seção é semelhante ao <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 de IoT Edge existente, poderá alterar a 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 IoT Edge e um módulo IoT Edge em sua solução de 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 no dispositivo de 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 IoT Edge que define todos os módulos 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 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, exiba o código-fonte SimulatedTemperatureSensor.csproj.

Definir a versão de runtime do IoT Edge

Atualmente, a versão do runtime estável mais recente é a 1.5. Atualize a versão IoT Edge runtime para a versão estável mais recente ou a versão que você 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 recebe a entrada e a envia para o Azure IoT Hub.

Quando estiver pronto para personalizar o modelo de módulo com seu próprio código, use os SDKs Azure IoT Hub para criar outros módulos que atedam à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á construída ou depurada usando o mecanismo do Docker em execução dentro do IoT Edge para Linux em Windows VM, a primeira etapa é a construção e publicação do módulo para habilitar a depuração remota.

1. Em Solution Explorer, 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 para Azure IoT Edge Módulo AMD64 C# com suporte para depuração remota.

   Observação

   Quando você seleciona Debug, Visual Studio usa Dockerfile.(amd64|windows-amd64).debug para criar imagens do Docker. Este arquivo inclui o depurador de linha de comando VSDBG do .NET Core na imagem do contêiner durante a compilação. Para módulos de IoT Edge prontos para produção, recomendamos que você use a configuração Release, que usa Dockerfile.(amd64|windows-amd64) sem VSDBG.

   Verifique se, na última linha do modelo, ENTRYPOINT ["dotnet", "IotEdgeModule1.dll"], o nome da DLL corresponde ao nome do projeto do módulo 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 do módulo IoT Edge e verifique se o nome da chave está id_rsa.

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

   

5. Se você estiver usando um registro privado como Azure Container Registry, use o seguinte comando do Docker para entrar nele. Você pode obter o nome de usuário e a senha da página de chaves de acesso do 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 no IoT Edge para Linux em Windows VM. (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 o IoT Edge para Linux na VM do Windows é reiniciado, 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 com êxito o serviço SSH, selecione Debug>Anexar a Processo, defina Tipo de Conexão para SSH, e defina Destino da Conexão para o endereço IP do seu IoT Edge para Linux em máquina virtual Windows. Se você não souber o endereço IP do IoT Edge para Linux em Windows VM, poderá usar o cmdlet Get-EflowVmAddr 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 do IoT Edge para Linux em Windows VM
   Porto	10022 (ou aquela que você usou em sua configuração de implantação)
   Nome de usuário	raiz
   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 observar variáveis na janela Visual Studio Locals.

   

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 Azure usados neste artigo para evitar encargos.

Excluir recursos de Azure

Não é possível desfazer a exclusão dos recursos do Azure e grupos de recursos. Não exclua acidentalmente grupo de recursos ou recursos incorretos. Se você criou o IoT Hub dentro de um grupo de recursos existente que tem recursos que deseja manter, exclua apenas o recurso IoT Hub em si, não o grupo de recursos.

Para excluir os recursos:

1. Entre no Azure portal e selecione Resource groups.
2. Selecione o nome do grupo de recursos que contém seus recursos de teste 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 você quiser excluir apenas alguns deles, selecione 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 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: