Tutorial: Desenvolva módulos de IoT Edge com contentores Linux usando IoT Edge para Linux no Windows

Aplica-se a: IoT Edge 1.5

Este tutorial guia-o como desenvolver, depurar e implementar o seu próprio código num dispositivo Azure IoT Edge, utilizando IoT Edge for Linux no Windows e Visual Studio 2022. Vai aprender o cenário mais comum para programadores de soluções IoT Edge ao implementar um módulo C# num dispositivo Linux. Vais implementar e depurar um módulo IoT Edge personalizado a correr num contentor Linux no Windows. Mesmo que planeie usar uma linguagem diferente ou implementar um serviço Azure, este tutorial continua a ser útil para aprender sobre as ferramentas e conceitos de desenvolvimento.

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

• A interface de linha de comandos (CLI) do Azure IoT Edge Dev Tool, que é a ferramenta preferida para desenvolvimento
• A extensão Azure IoT Edge Tools para Visual Studio, que está em modo manutenção

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

Neste tutorial, irá aprender a:

Pré-requisitos

Este tutorial assume que usas uma máquina a correr o Windows como máquina de desenvolvimento. Em computadores Windows, pode desenvolver módulos Windows ou Linux. Este tutorial orienta-o no desenvolvimento de contentores Linux, usando IoT Edge para Linux em Windows para construir e implementar os módulos.

Antes de começar:

• Instala o IoT Edge para Linux no Windows.

• Leia o guia de iniciação Desenvolva o seu primeiro módulo IoT Edge num dispositivo Windows.

• Descarregue o SDK Core .NET.

• Instale ou modifique o Visual Studio 2022 na sua máquina de desenvolvimento. Escolha as opções de carga de trabalho desenvolvimento no Azure e desenvolvimento de Desktop com C++.

• Depois de a sua instalação Visual Studio 2022 estar pronta, descarregue e instale Azure IoT Edge Tools a partir Visual Studio Marketplace.

  Pode usar a extensão Azure IoT Edge Tools para criar e construir a sua solução IoT Edge. A ferramenta de desenvolvimento preferida é a Azure IoT Edge Dev Tool CLI. A extensão inclui os modelos de projeto Azure IoT Edge que utiliza para criar o projeto Visual Studio. Atualmente, você precisa instalar a extensão independentemente da ferramenta de desenvolvimento que você usa.

  Gorjeta

  Se estiver a utilizar o Visual Studio 2019, descarregue e instale do Visual Studio Marketplace as ferramentas Azure IoT Edge Tools para Visual Studio 2019.

• Crie um hub gratuito ou de nível padrão IoT em Azure como recurso cloud.

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

Conceitos-chave

Este tutorial explica o desenvolvimento de um módulo IoT Edge. Um módulo IoT Edge é um contentor que contém código executável. Pode implementar um ou mais módulos num dispositivo IoT Edge. Os módulos executam tarefas específicas, como ingerir dados de sensores, limpar e analisar dados ou enviar mensagens para um hub IoT. Para mais informações, veja Compreender Azure IoT Edge módulos.

Ao desenvolver módulos IoT Edge, é importante compreender a diferença entre a máquina de desenvolvimento e o dispositivo IoT Edge alvo onde o módulo será eventualmente implementado. O contêiner que você cria para armazenar o código do módulo deve corresponder ao sistema operacional (SO) do dispositivo de destino.

Por exemplo, o cenário mais comum é alguém desenvolver um módulo num computador Windows para direcionar um dispositivo Linux que executa IoT Edge. Nesse caso, o sistema operacional do contêiner é Linux.

Ao passar por este tutorial, tenha em mente a diferença entre o sistema operacional da máquina de desenvolvimento e o sistema operacional do contêiner. Para este tutorial, vais usar o teu host Windows para desenvolvimento e o IoT Edge para Linux na máquina virtual (VM) Windows para construir e implementar os módulos.

Este tutorial destina-se a dispositivos que estejam a correr IoT Edge com contentores Linux. Você pode usar seu sistema operacional preferido, desde que sua máquina de desenvolvimento execute contêineres Linux. Recomendamos usar o Visual Studio para desenvolver com contentores Linux, por isso é isso que este tutorial utiliza. Também pode usar o Visual Studio Code, embora existam diferenças de suporte entre as duas ferramentas. Para 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

Os módulos IoT Edge são embalados como contentores, por isso precisa de um motor de containers na sua máquina de desenvolvimento para os construir e gerir.

O IoT Edge para Linux na VM Windows já contém uma instância do motor Docker. Este tutorial mostra-lhe como se ligar remotamente da máquina do programador Windows à instância IoT Edge for Linux no Windows VM Docker. Ao usar esta ligação remota, elimina a dependência do Docker Desktop para Windows.

Configurar a CLI do Docker

O primeiro passo é configurar a CLI Docker na máquina de desenvolvimento Windows para poder ligar-se ao motor Docker remoto:

1. Faça o download da versão pré-compilada docker.exe da CLI do Docker da Chocolatey. Também pode descarregar 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 sua máquina de desenvolvimento, por exemplo, C:\Docker\bin.

3. Abra Acerca do seu PC>Informações do sistema>Configurações avançadas do sistema.

4. SelecioneVariáveis de ambiente avançadas>. Em Variáveis de usuário, selecione Caminho.

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

6. Abra uma sessão do PowerShell com privilégios elevados.

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. Deve ser algo como Docker version 20.10.12, build e91ed57.

Configurar o mecanismo do Docker

O segundo passo é configurar o IoT Edge para Linux no motor Docker do Windows VM para aceitar ligações externas e adicionar as regras de firewall apropriadas.

1. Abra uma sessão elevada do PowerShell 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"
   

   Segue 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 ligação

O passo final de configuração é testar a ligação Docker ao IoT Edge para Linux no motor Docker do Windows VM:

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

   Get-EflowVmAddr
   

   Gorjeta

   Se o IoT Edge para Linux na VM Windows fosse implementado sem um IP estático, o endereço IP poderia mudar durante reinicios do sistema operativo do host Windows ou alterações na rede. Certifique-se de que está a usar o endereço IP correto para o IoT Edge for Linux na máquina virtual do Windows sempre que quiser estabelecer uma ligação remota ao motor Docker.

   Segue 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. Liga-te ao IoT Edge para Linux na VM do Windows, ao motor Docker, e executa o contentor de exemplo hello-world. Substitua <EFLOW-VM-IP> pelo IoT Edge para Linux no endereço IP Windows VM que obteve no passo anterior.

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

   Quando o download do contêiner termina, o contêiner é executado e produz esta 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 Azure IoT Edge

O modelo de projeto IoT Edge no Visual Studio cria uma solução que pode implementar em dispositivos IoT Edge. Use os passos seguintes para criar uma solução Azure IoT Edge e depois gere o primeiro módulo dessa solução. Cada solução IoT Edge pode conter mais do que 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 Novo Projeto na barra de ferramentas.

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

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

4. Na caixa de diálogo Adicionar módulo , selecione o tipo de módulo que deseja desenvolver. Também pode selecionar Módulo existente para adicionar um módulo de IoT Edge existente à sua implementaçã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/<nome do teu módulo>. Substitua-o por suas próprias informações de registro.

   Utilize localhost se utilizar um registo Docker local para testes. Se usares o Azure Container Registry, então usa o servidor de login nas definições do teu registo. O servidor de login parece-se com <nome de registro>.azurecr.io. Substitua apenas a parte localhost:5000 da cadeia de caracteres, para que o resultado final se pareça com <nome do registo>.azurecr.io/<seu nome de módulo>.

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

   

   Nota

   Se tiver um projeto IoT Edge existente, pode alterar a URL do repositório abrindo o ficheiro module.json. A URL do repositório está localizada na repository propriedade do arquivo JSON.

Agora, tem um projeto IoT Edge e um módulo IoT Edge na sua solução 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 principal do projeto contém seu manifesto de implantação. O manifesto de implementação é um documento JSON que descreve os módulos a configurar no dispositivo IoT Edge alvo.

A pasta do módulo contém um arquivo para o código do módulo. Chama-se ou Program.cs ou main.c, dependendo do idioma que escolheu. Esta pasta também contém um arquivo chamado module.json que descreve os metadados do seu módulo. Vários ficheiros Docker fornecem a informação necessária para construir o seu módulo como um contentor Windows ou Linux.

Manifesto de implantação do seu projeto

O manifesto de implantação que você edita é chamado deployment.debug.template.json. Este ficheiro é um modelo de manifesto de implementação do IoT Edge que define todos os módulos que correm num dispositivo. O arquivo também define como os módulos se comunicam entre si. Para obter mais informações sobre manifestos de implantação, consulte Saiba como implantar módulos e estabelecer rotas.

O modelo de implantação inclui:

• Os dois módulos de tempo de execução, edgeAgent e edgeHub.
• O módulo personalizado que criaste 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 funciona o sensor de temperatura simulado, consulte o código-fonte SimulatedTemperatureSensor.csproj.

Definir a versão de runtime do IoT Edge

Atualmente, a última versão de tempo de execução estável é 1.5. Atualize a versão de runtime do IoT Edge para a versão estável mais recente ou para a versão que pretende direcionar para os seus dispositivos:

Desenvolva o seu módulo

Quando você adiciona um novo módulo, ele vem com um código padrão pronto para ser criado e implantado em um dispositivo para que você possa começar a testar sem tocar em nenhum código. O código do módulo está localizado dentro da 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 são roteados para o módulo SimulatedTemperatureSensor. O módulo recebe a entrada e depois envia-a para o Azure IoT Hub.

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

Crie e envie um único módulo

Normalmente, você deseja testar e depurar cada módulo antes de executá-lo em uma solução inteira com vários módulos. Como a solução irá construir ou depurar usando o motor Docker a correr dentro do IoT Edge for Linux na VM Windows, o primeiro passo é construir e publicar o módulo para permitir 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>definido como projeto de inicialização.

3. Para depurar o módulo C# Linux, você precisa atualizar o Dockerfile.amd64.debug arquivo para habilitar o serviço SSH. Atualize o ficheiro Dockerfile.amd64.debug para usar o seguinte modelo: Dockerfile para Azure IoT Edge Módulo AMD64 C# com suporte para depuração remota.

   Nota

   Quando selecionas Debug, Visual Studio usa Dockerfile.(amd64|windows-amd64).debug para construir imagens Docker. Este arquivo inclui o depurador de linha de comandos VSDBG do .NET Core na imagem do contentor durante a sua construção. Para módulos de IoT Edge prontos para produção, recomendamos que utilize a configuração Release, que utiliza Dockerfile.(amd64|windows-amd64) sem VSDBG.

   Certifique-se de que na última linha do modelo, ENTRYPOINT ["dotnet", "IotEdgeModule1.dll"], o nome da DLL corresponde ao nome do seu projeto de módulo IoT Edge.

4. Para estabelecer uma conexão SSH com o módulo Linux, você precisa criar uma chave RSA. Abra uma sessão elevada do PowerShell e execute os seguintes comandos para criar uma nova chave RSA. Guarda a chave RSA na mesma pasta IoT Edge módulo e certifica-te de que o nome da chave é id_rsa.

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

   

5. Se estiver a usar um registo privado como o Azure Container Registry, use o seguinte comando Docker para iniciar sessão nele. Pode obter o nome de utilizador e a palavra-passe na página Chaves de Acesso do seu registo no portal Azure. Se estiver a utilizar um registo local, pode executar um registo 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 elevada do PowerShell, execute os seguintes comandos:

   1. Obtenha o moduleId valor, com base no nome do módulo Linux C#. Substitua o marcador de posição <iot-edge-module-name> pelo nome do 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, certifique-se de que está a utilizar o nome de módulo correto.

   3. Inicie o serviço SSH dentro do contêiner 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 que corre numa máquina virtual Windows. (Este tutorial usa a porta 10022.)

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

   Aviso

   Por razões de segurança, sempre que o IoT Edge para Linux no Windows VM reinicia, a regra da tabela IP é eliminada e volta às definições originais. Além disso, você tem que iniciar o serviço SSH do módulo novamente manualmente.

2. Depois de iniciar com sucesso o serviço SSH, selecione Debug>Anexar ao Processo, defina Tipo de Ligação para SSH, e defina Connection Target para o endereço IP do seu IoT Edge para Linux na Windows VM. Se não souberes o endereço IP do teu IoT Edge Linux na Windows VM, podes usar o cmdlet PowerShell Get-EflowVmAddr.

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

   Campo	Valor
   Nome do host	Endereço IP para o IoT Edge para Linux na VM Windows
   Porto	10022 (ou aquele que você usou em sua configuração de implantação)
   Nome de utilizador	raiz
   Tipo de autenticação	Chave Privada
   Arquivo de chave privada	Caminho completo para o id_rsa valor que criaste num passo anterior
   Frase secreta	Senha usada para a chave que você criou 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 Anexar ao Gerenciado (CoreCLR). Pode levar de 10 a 20 segundos na primeira vez.

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

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

5. A saída do SimulatedTemperatureSensor deve ser redirecionada para o input1 do módulo personalizado C# Linux. O ponto de interrupção deve ser acionado. Podes observar variáveis na janela Visual Studio Locais.

   

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

Limpar recursos

Se planeia avançar para o próximo artigo recomendado, pode manter os recursos e as configurações que criou e reutilizá-los. Também pode continuar a usar o mesmo dispositivo IoT Edge como dispositivo de teste.

Caso contrário, elimine as configurações locais e os recursos do Azure que utilizou neste artigo para evitar cobranças.

Eliminar recursos do Azure

Não podes desfazer a eliminação de recursos e grupos de recursos do Azure. Certifique-se de que não elimina acidentalmente o grupo de recursos ou recursos errados. Se criaste o IoT Hub dentro de um grupo de recursos existente que tem recursos que queres manter, elimina apenas o próprio recurso do IoT Hub, não o grupo de recursos.

Para eliminar os recursos:

1. Inicie sessão no portal Azure e depois selecione Resource groups.
2. Selecione o nome do grupo de recursos que contém os seus recursos de teste IoT Edge.
3. Reveja a lista de recursos que o seu grupo de recursos contém. Se quiser excluir todos eles, selecione Excluir grupo de recursos. Se quiseres eliminar apenas alguns, seleciona cada recurso para os eliminar individualmente.

Próximo passo

Neste tutorial, configuraste o Visual Studio na tua máquina de desenvolvimento e implementaste e depuraste o teu primeiro módulo IoT Edge a partir dele. Agora que você já conhece os conceitos básicos, tente adicionar funcionalidade a um módulo para que ele possa analisar os dados que passam por ele: