Tutorial: Atualização de Dispositivo para Hub IoT do Azure usando a imagem de referência do Raspberry Pi 3 B+

Artigo
03/17/2023

A Atualização de Dispositivo para Hub IoT do Azure é compatível com atualizações baseadas em imagem, pacote e script.

As atualizações de imagem fornecem um nível mais alto de confiança no estado final do dispositivo. Normalmente, é mais fácil replicar os resultados de uma atualização de imagem entre um ambiente de pré-produção e um ambiente de produção, já que não são apresentados os mesmos desafios que os pacotes e suas dependências. Devido à natureza atômica, também é possível adotar facilmente um modelo de failover A/B.

Este tutorial apresenta as etapas para concluir uma atualização de ponta a ponta baseada em imagem usando a Atualização de Dispositivo para Hub IoT em uma placa Raspberry Pi 3 B+.

Neste tutorial, você aprenderá como:

Baixe uma imagem.
Adicione uma marca ao dispositivo IoT.
Importar uma atualização.
Implantar uma atualização de imagem.
Monitore a implantação da atualização.

Observação

As atualizações de imagem neste tutorial foram validadas na placa do Raspberry Pi B3.

Pré-requisitos

Se você ainda não tiver feito isso, crie uma conta e uma instância de Atualização de Dispositivo e configure um hub IoT. Este tutorial precisa que o dispositivo esteja conectado por meio de uma conexão ethernet.

Baixe arquivos na seção Ativos da Página de lançamentos de atualização de dispositivos do GitHub. O arquivo Tutorial_RaspberryPi.zip tem todos os arquivos necessários para o tutorial.

Criar um dispositivo no Hub IoT e obter uma cadeia de conexão

Agora, adicione o dispositivo ao Hub IoT. No Hub IoT, uma cadeia de conexão será gerada para o dispositivo.

No portal do Azure, navegue até o seu hub IoT.
No painel esquerdo, selecione Dispositivos. Em seguida, selecione Novo.
Em ID do Dispositivo, insira um nome para o dispositivo. Verifique se a caixa de seleção Gerar chaves automaticamente está marcada.
Selecione Salvar. Na página Dispositivos, o dispositivo criado deve estar na lista.
Obtenha a cadeia de conexão do dispositivo navegando até a exibição do dispositivo e selecionando o ícone Copiar ao lado da Cadeia de Conexão Primária.
Cole os caracteres copiados em algum lugar para usá-los posteriormente nas etapas a seguir:

Essa cadeia de caracteres copiada é a cadeia de conexão do dispositivo.

Observação

Este tutorial usa uma cadeia de conexão de dispositivo para se autenticar e se conectar ao Hub IoT para facilitar a configuração. Para cenários de produção, recomendamos usar a identidade do módulo e aproveitar o AIS (Serviço de Identidade IoT) para provisionar dispositivos. Saiba mais em

Configurar o Raspberry Pi

Fornecemos a imagem base e arquivos de atualização na seção Ativos da Página de lançamentos de atualização de dispositivos do GitHub. O arquivo Tutorial_RaspberryPi.zip tem todos os arquivos necessários para o tutorial. O arquivo .wic é a imagem base que você pode instalar em uma placa do Raspberry Pi 3 B+. O arquivo swUpdate(.swu), o script swupdate personalizado e o manifesto são os arquivos de atualização que você importaria por meio da Atualização de Dispositivo para Hub IoT.

Essa imagem base usa um build Yocto (baseado na versão 3.4.4) com:

SWUpdate que habilita a atualização de partição dupla com a Atualização de Dispositivo
Agente de Atualização de Dispositivo

Para saber mais sobre as camadas Yocto usadas, confira Atualização de Dispositivo Yocto GitHub..

Você poder usar sua ferramenta de atualização de SO favorita para instalar a imagem de base da Atualização de dispositivo (adu-base-image) no cartão SD que será usada no dispositivo Raspberry Pi 3 B+. Abaixo estão as instruções para usar o bmaptool para instalar no cartão SD.

Usar bmaptool para atualizar o cartão SD

Instale o utilitário bmaptool, se ainda não o tiver feito.
```
sudo apt-get install bmap-tools
```
Localize o caminho do cartão SD no /dev. O caminho deve ter a seguinte aparência: /dev/sd* ou /dev/mmcblk*. Você pode usar o utilitário dmesg para ajudar a localizar o caminho correto.
Desmonte todas as partições montadas antes de atualizar.
```
sudo umount /dev/<device>
```
Verifique se você tem permissões de gravação para o dispositivo.
```
sudo chmod a+rw /dev/<device>
```
Opcional: para uma atualização mais rápida, baixe o arquivo bimap e o arquivo de imagem e coloque-os no mesmo diretório.

Atualize o cartão SD.

sudo bmaptool copy <path to image> /dev/<device>

A Atualização de dispositivo do software do Hub IoT do Azure está sujeita aos seguintes termos de licença:

Leia os termos da licença antes de usar o agente. A instalação e o uso confirmam sua aceitação desses termos. Caso não concorde com os termos de licença, não use o agente de Atualização de Dispositivo para Hub IoT.

Configurar o agente de Atualização de Dispositivo no Raspberry Pi

Verifique se o Raspberry Pi 3 está conectado à rede.
Entre por meio do SSH no Raspberry Pi 3 usando o seguinte comando na janela do PowerShell:
```
  ssh raspberrypi3 -l root
```
Os arquivos de configuração da Atualização de Dispositivo devem estar no dispositivo para que a Atualização de Dispositivo para Hub IoT seja configurada corretamente.
1. Para criar ou abrir o arquivo du-config.json para edição usando:
```
  nano /adu/du-config.json
```
1. Depois de executar o comando, você deverá ver um editor aberto com o arquivo. Se você nunca criou o arquivo, ele estará vazio. Agora copie o conteúdo du-config.json baixo e substitua as configurações necessárias para seu dispositivo. Em seguida, substitua a cadeia de conexão de exemplo pela cadeia de conexão do dispositivo criado nas etapas acima.
  
  du-config.json
```
{
   "schemaVersion": "1.0",
   "aduShellTrustedUsers": [
      "adu",
      "do"
   ],
   "manufacturer": "contoso",
   "model": "virtual-vacuum-v2",
   "agents": [
      {
      "name": "main",
      "runas": "adu",
      "connectionSource": {
         "connectionType": "string",
         "connectionData": "HostName=example-connection-string.azure-devices.net;DeviceId=example-device;SharedAccessKey=M5oK/rOP12aB5678YMWv5vFWHFGJFwE8YU6u0uTnrmU=" 
      },
      "manufacturer": "contoso",
      "model": "virtual-vacuum-v2"
      }
   ]
}  
```
1. Depois de concluir as alterações, selecione Ctrl+X para sair do editor. Em seguida, insira y para salvar as alterações.
Agora você precisa criar o arquivo du-diagnostics-config.json usando comandos semelhantes.
1. Comece criando ou abrindo o arquivo du-diagnostics-config.json para editar usando:
```
  nano /adu/du-diagnostics-config.json
```
1. Copie o conteúdo du-diagnostics-config.json disponibilizado abaixo e substitua as configurações que diferem da compilação padrão. O arquivo de exemplo du-diagnostics-config.json representa os locais de log padrão da Atualização de Dispositivo para Hub IoT. Você só precisará alterar esses valores padrão se a implementação for diferente.
du-diagnostics-config.json
```
{
   "logComponents":[
      {
         "componentName":"adu",
         "logPath":"/adu/logs/"
      },
      {
         "componentName":"do",
         "logPath":"/var/log/deliveryoptimization-agent/"
      }
   ],
   "maxKilobytesToUploadPerLogPath":50
}
```
1. Depois de concluir as alterações, selecione Ctrl+X para sair do editor. Em seguida, insira y para salvar as alterações.
Use o comando a seguir para mostrar os arquivos localizados no diretório /adu/. Você deve ver os dois arquivos de configuração files.du-diagnostics-config.json para edição usando:
```
  ls -la /adu/
```
Reinicie o daemon do sistema de Atualização de Dispositivo para verificar se as configurações foram aplicadas. Use o seguinte comando no terminal conectado ao raspberrypi:
```
  systemctl start deviceupdate-agent
```
Verifique se o agente está ativo usando o seguinte comando:
```
  systemctl status deviceupdate-agent
```
Você deverá ver o status aparecer como ativo e verde.

Conectar o dispositivo na Atualização de Dispositivo para Hub IoT

No painel esquerdo, selecione Dispositivos.
Selecione o link com o nome do dispositivo.
Na parte superior da página, selecione Dispositivo Gêmeo.
Na seção Relatado das propriedades do Dispositivo Gêmeo, procure a versão do kernel do Linux.

Para um novo dispositivo, que não recebeu uma Atualização de Dispositivo, o valor DeviceManagement:DeviceInformation:1.swVersion representa a versão do firmware em execução no dispositivo. Depois que um dispositivo tiver sido atualizado, a Atualização de Dispositivo usará o valor da propriedade AzureDeviceUpdateCore:ClientMetadata:4.installedUpdateId para representar a versão do firmware em execução no dispositivo.
Os arquivos de imagem de base e de atualização contam com um número de versão no nome de arquivo.
```
 adu-<image type>-image-<machine>-<version number>.<extension>
```
Use esse número de versão na seção posterior "Importar a atualização".

Adicionar uma tag de grupo de Atualização de Dispositivo ao seu dispositivo

No portal do Azure, navegue para o hub IoT.
No painel esquerdo, em Dispositivos, localize o dispositivo IoT e acesse o dispositivo gêmeo ou o módulo gêmeo.
No módulo gêmeo do módulo de agente de Atualização de Dispositivo, exclua os valores de marca de Atualização de Dispositivo existentes definindo-os como nulo. Se você estiver usando a Identidade do dispositivo com o agente de Atualização de Dispositivo, faça essas alterações no dispositivo gêmeo.
Adicione um novo valor de marca da Atualização de dispositivo, conforme mostrado:
```
    "tags": {
            "ADUGroup": "<CustomTagValue>"
            }
```
Essa captura de tela mostra a seção em que a marca precisa ser adicionada ao gêmeo.

Importar a atualização

Baixe o manifesto do tutorial de exemplo e a atualização do exemplo (arquivo .swu) e o script de amostra A/B do Tutorial_RaspberryPi.zip em Ativos de versão para o agente mais recente.
Entre no portal do Azure e vá para o Hub IoT com a Atualização de Dispositivo. No painel esquerdo, em Gerenciamento Automático de Dispositivo, selecione Atualizações.
Selecione a guia Atualizações.
Selecione + Importar nova atualização.
Selecione + Selecionar no contêiner de armazenamento. Selecione uma conta existente ou crie uma usando + Conta de armazenamento. Em seguida, selecione um contêiner existente ou crie um contêiner usando + Contêiner. Esse contêiner será usado para preparar os arquivos de atualização para importação.

Observação

É recomendável usar um contêiner novo cada vez que você importar uma atualização para evitar a importação acidental de arquivos de atualizações anteriores. Se você não usar um contêiner novo, não deixe de excluir todos os arquivos do contêiner existente antes de concluir esta etapa.
No contêiner, selecione Upload e navegue até os arquivos baixados na etapa 1. Após selecionar todos os arquivos de atualização, selecione Upload. Em seguida, selecione o botão Selecionar para retornar à página Importar atualização.

Esta captura de tela mostra a etapa de importação. Os nomes de arquivo podem não corresponder aos usados no exemplo.
Na página Importar atualização, examine os arquivos a serem importados. Em seguida, selecione Importar atualização para iniciar o processo de importação. Para o tutorial, importe o manifesto do tutorial de exemplo, a atualização de exemplo (arquivo .swu) e o script A/B de exemplo baixado anteriormente.
O processo de importação é iniciado e a tela é alterada para a seção Histórico de importação. Quando a coluna Status indicar que a importação foi bem-sucedida, selecione o cabeçalho Atualizações Disponíveis. Agora a atualização importada deve estar presente na lista.

Para obter mais informações sobre o processo de importação, confira Importar uma atualização para a Atualização de Dispositivo.

Exibir grupos de dispositivos

A Atualização de Dispositivos usa grupos para organizar os dispositivos. A Atualização de Dispositivo classifica automaticamente os dispositivos em grupos com base nas marcas atribuídas e propriedades de compatibilidade. Cada dispositivo pertence a apenas um grupo, mas os grupos podem ter vários subgrupos para classificar as diferentes classes de dispositivos.

Acesse a guia Grupos e Implantações na parte superior da página.
Exiba a lista de grupos e o gráfico de conformidade de atualização. O gráfico de conformidade da atualização mostra a contagem de dispositivos em vários estados de conformidade: Com a atualização mais recente, Novas atualizações disponíveis e Atualizações em andamento. Saiba mais sobre a conformidade de atualizações.
Você deverá visualizar um grupo de dispositivos contendo o dispositivo simulado que você configurou neste tutorial juntamente com as atualizações disponíveis para os dispositivos no novo grupo. Se houver dispositivos que não atendem aos requisitos de classe de dispositivo do grupo, eles aparecerão em um grupo inválido correspondente. Para implantar a melhor atualização disponível para o novo grupo definido pelo usuário deste modo de exibição, selecione Implantar ao lado do grupo.

Para obter mais informações sobre as marcas e os grupos, consulte Gerenciar grupos de dispositivos.

Implantar a atualização

Depois que o grupo for criado, você verá uma nova atualização disponível para o grupo de dispositivos, juntamente com um link para a atualização em Melhor atualização. Talvez você precise atualizar novamente.

Para obter mais informações sobre a conformidade, consulte Conformidade de Atualização de Dispositivo.
Escolha o grupo de destino selecionando o nome do grupo. Você será direcionado para os detalhes do grupo em Noções básicas do grupo.
Para iniciar a implantação, acesse a guia Implantação atual. Selecione o link implantar ao lado da atualização desejada na seção de Atualizações disponíveis. A melhor atualização disponível para determinado grupo é indicada com a Melhor em destaque.
Agende sua implantação para iniciar imediatamente ou no futuro. Em seguida, selecione Criar.

Dica

Por padrão, a data e a hora de Início são 24 horas a partir do horário atual. Lembre-se de selecionar a data e a hora diferentes, caso deseje que a implantação comece mais cedo.
Em Detalhes da implantação, o Status se torna Ativo. A atualização implantada é marcada com (implantando).
Exiba o gráfico de conformidade para ver se a atualização está em andamento.
Após atualizar o dispositivo com êxito, você verá que o gráfico de conformidade e os detalhes de implantação são atualizados para refletir as informações.

Monitorar a implantação da atualização

Selecione a guia Histórico de Implantações na parte superior da página.
Selecione o link de detalhes ao lado da implantação que você criou.
Selecione Atualizar para exibir os detalhes mais recentes do status.

Agora você concluiu com êxito uma atualização de imagem de ponta a ponta usando a Atualização de Dispositivo para Hub IoT em um dispositivo Raspberry Pi 3 B+.

Limpar recursos

Quando não for mais necessária, limpe a conta da Atualização de Dispositivo, a instância, o hub IoT e o dispositivo IoT.

Próximas etapas

Atualizar pacotes de dispositivos com a Atualização de Dispositivo