Como entender e usar atualizações delta na Atualização de Dispositivo para Hub IoT (versão prévia)

Artigo
03/06/2024

As atualizações delta permitem gerar uma pequena atualização que representa apenas as alterações entre duas atualizações completas: uma imagem de origem e uma imagem de destino. Essa abordagem é ideal para reduzir a largura de banda usada para baixar uma atualização para um dispositivo, principalmente se houver apenas algumas alterações entre as atualizações de origem e de destino.

Observação

O recurso atualização delta está atualmente em versão prévia pública.

Requisitos para usar atualizações delta na Atualização de Dispositivo para Hub IoT

Os arquivos de atualização de origem e destino devem estar no formato SWUpdate (SWU).
Em cada arquivo SWUpdate, deve haver uma imagem bruta que use o sistema de arquivos Ext2, Ext3 ou Ext4. Essa imagem pode ser compactada com gzip ou zstd.
O processo de geração delta recompacta a atualização SWU de destino usando a compactação zstd para produzir um delta ideal. Importe essa atualização SWU de destino recompactada para o serviço de atualização de dispositivos junto com o arquivo de atualização delta gerado.
Dentro do SWUpdate no dispositivo, a descompactação zstd também deve ser habilitada.
- Esse processo requer o uso do SWUpdate 2019.11 ou posterior.

Configurar um dispositivo com o agente de Atualização de Dispositivo e o componente do processador delta

Para que seu dispositivo baixe e instale atualizações delta do serviço de Atualização de Dispositivo, você precisa ter vários componentes presentes e configurados.

Agente de Atualização de Dispositivo

O agente de Atualização de Dispositivo orquestra o processo de atualização no dispositivo, incluindo ações de download, instalação e reinicialização. Adicione o agente de Atualização de Dispositivo a um dispositivo e configure-o para uso. Use o agente versão 1.0 ou posterior. Para obter instruções, consulte Provisionamento do agente de Atualização de Dispositivo.

Manipulador de atualização

Um manipulador de atualização se integra ao agente de Atualização de Dispositivo para executar a instalação de atualização real. Para atualizações delta, comece com o microsoft/swupdate:2 manipulador de atualização caso ainda não tinha seu próprio manipulador de atualização SWUpdate que deseja modificar. Se usar seu próprio manipulador de atualização, habilite a descompactação zstd no SWUpdate.

Processador delta

O processador delta recria o arquivo de imagem SWU original em seu dispositivo após o download do arquivo delta, para que seu manipulador de atualização possa instalar o arquivo SWU. O código do processador delta está disponível no repositório Azure/iot-hub-device-update-delta GitHub.

Para adicionar o componente do processador delta à imagem do dispositivo e configurá-lo para uso, siga as instruções README.md para usar o CMAKE para criar o processador delta da origem. Em seguida, instale o objeto compartilhado (libadudiffapi.so) diretamente copiando-o no /usr/lib diretório:

sudo cp <path to libadudiffapi.so> /usr/lib/libadudiffapi.so
sudo ldconfig

Adicionar um arquivo de imagem SWU de origem ao dispositivo

Depois que uma atualização delta é baixada para um dispositivo, ela deve ser comparada com um arquivo SWU de origem válido que foi previamente armazenado em cache no dispositivo. Esse processo é necessário para que a atualização delta recrie a imagem de destino completa. A maneira mais simples de preencher essa imagem armazenada em cache é implantar uma atualização de imagem completa no dispositivo por meio do serviço de Atualização de Dispositivo (usando os processos de importação e implantação existentes). Contanto que o dispositivo esteja configurado com o agente de atualização de dispositivos (versão 1.0 ou posterior) e processador delta, o agente de atualização de dispositivos armazena em cache o arquivo SWU instalado automaticamente para uso posterior da atualização delta.

Se você quiser pré-preencher diretamente a imagem de origem no seu dispositivo, o caminho onde a imagem é esperada é:

[BASE_SOURCE_DOWNLOAD_CACHE_PATH]/sha256-[ENCODED HASH]

Por padrão, BASE_SOURCE_DOWNLOAD_CACHE_PATH é o caminho /var/lib/adu/sdc/[provider]. O valor [provider] é a parte Provider da updateId do arquivo SWU de origem.

ENCODED_HASH é a cadeia de caracteres hexadecimais base64 do SHA256 do binário, mas após a codificação para a cadeia de caracteres hexadecimais base64, ela codifica os caracteres da seguinte maneira:

+ codificado como octets _2B
/ codificado como octets _2F
= codificado como octets _3D

Gerar atualizações delta usando a ferramenta DiffGen

Pré-requisitos do ambiente

Antes de criar deltas com DiffGen, várias coisas precisam ser baixadas e/ou instaladas no computador de ambiente. Recomendamos um ambiente Linux e especificamente Ubuntu 20.04 (ou Subsistema do Windows para Linux se for nativamente no Windows).

A tabela a seguir fornece uma lista dos conteúdos necessário, onde recuperá-los e a instalação recomendada, se necessário:

Nome do binário	Onde adquirir	Como instalar o
DiffGen	Repositório GitHub Azure/iot-hub-device-update-delta	Na pasta raiz, selecione o arquivo Microsoft.Azure.DeviceUpdate.Diffs.[version].nupkg. Saiba mais sobre pacotes NuGet.
Tempo de execução .NETCore, versão 6.0.0	Por meio de Gerenciadores de Pacotes/Terminais	Instruções para Linux. Somente o Runtime é necessário.

Dependências

O zstd_compression_tool é usado para descompactar os arquivos de imagem de uma camada de arquivos e recompactá-los com zstd. Esse processo garante que todos os arquivos da camada de arquivos usados para a geração diff tenham o mesmo algoritmo de compactação para as imagens dentro dos arquivos.

Comandos para instalar pacotes/bibliotecas necessários:

sudo apt update  
sudo apt-get install -y python3 python3-pip  
sudo pip3 install libconf zstandard

Criar uma atualização delta usando DiffGen

A ferramenta DiffGen é executada com vários argumentos. Todos os argumentos são necessários e a sintaxe geral é a seguinte:

DiffGenTool [source_archive] [target_archive] [output_path] [log_folder] [working_folder] [recompressed_target_archive]

O script recompress_tool.py é executado para criar o arquivo [recompressed_target_archive], que é, então, usado em vez de [target_archive] como arquivo de destino para criar a comparação.
Os arquivos de imagem contidos em [recompressed_target_archive] são compactados com zstd.

Se seus arquivos SWU estiverem assinados (provavelmente), você também precisará de outro argumento:

DiffGenTool [source_archive] [target_archive] [output_path] [log_folder] [working_folder] [recompressed_target_archive] "[signing_command]"

Além de usar [recompressed_target_archive] como o arquivo de destino, fornecer um parâmetro de cadeia de caracteres de comando de assinatura executa recompress_and_sign_tool.py a fim de criar o arquivo [recompressed_target_archive] e assinar o arquivo sw-description na camada de arquivos (o que significa que um arquivo sw-description.sig está presente). Você pode usar o script sign_file.sh de exemplo do repositório do GitHub Azure/iot-hub-device-update-delta. Abra o script, edite-o para adicionar o caminho para o seu arquivo de chave privada e depois salve-o. Veja a seção de exemplos para obter exemplos de uso.

A tabela a seguir descreve os argumentos com mais detalhes:

Argumento	Descrição
[source_archive]	Essa é a imagem na qual o delta se baseia ao criar o delta. Importante: essa imagem deve ser idêntica à imagem que já está presente no dispositivo (por exemplo, armazenada em cache de uma atualização anterior).
[target_archive]	Essa é a imagem para a qual o delta atualiza o dispositivo.
[output_path]	O caminho (incluindo o nome desejado do arquivo delta que está sendo gerado) no computador host em que o arquivo delta é colocado após a criação. Se o caminho não existir, a ferramenta o cria.
[log_folder]	O caminho no computador host em que os logs são criados. É recomendável definir esse local como uma subpasta do caminho da saída. Se o caminho não existir, a ferramenta o cria.
[working_folder]	Caminho no computador em que os arquivos colaterais e outros de trabalho são colocados durante a geração delta. É recomendável definir esse local como uma subpasta do caminho da saída. Se o caminho não existir, a ferramenta o cria.
[recompressed_target_archive]	O caminho no computador host em que o arquivo de destino recompactado é criado. Esse arquivo é usado em vez de <target_archive> como o arquivo de destino para geração da comparação. Se esse caminho existir antes da chamada a DiffGenTool, o caminho será substituído. Recomendamos definir esse caminho como um arquivo na subpasta do caminho de saída.
"[signing_command]" (opcional)	Um comando personalizável usado para assinar o arquivo sw-description no arquivo da camada de arquivos recompressed. O arquivo sw-description na camada de arquivos recompressed é usado como um parâmetro de entrada para o comando de assinatura; DiffGenTool espera que o comando de assinatura crie um novo arquivo de assinatura, usando o nome da entrada com `.sig` acrescentado. Colocar o parâmetro entre aspas duplas é necessário para que todo o comando seja passado como um único parâmetro. Além disso, evite colocar o caractere '~' em um caminho de chave usado para assinatura e use o caminho de casa completo (por exemplo, use /home/USER/keys/priv.pem em vez de ~/keys/priv.pem).

Exemplos de DiffGen

Nesses exemplos, estamos operando no diretório /mnt/o/temp (em WSL):

Criar diferença entre o arquivo de origem de entrada e o arquivo de destino recompressed:

sudo ./DiffGenTool  
/mnt/o/temp/[source file.swu]  
/mnt/o/temp/[target file.swu]  
/mnt/o/temp/[delta file to be created]  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/[recompressed file to be created.swu]

Se você também estiver usando o parâmetro de assinatura (necessário se o arquivo SWU estiver assinado), é possível usar o script sign_file.sh de exemplo referenciado anteriormente. Primeiro, abra o script e edite-o para adicionar o caminho para o seu arquivo de chave privada. Salve o script e execute DiffGen da seguinte maneira:

Criar diferença entre o arquivo de origem de entrada e o arquivo de destino recompressed/re-signed:

sudo ./DiffGenTool  
/mnt/o/temp/[source file.swu]
/mnt/o/temp/[target file.swu]   
/mnt/o/temp/[delta file to be created]  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/[recompressed file to be created.swu]  
/mnt/o/temp/[path to script]/sign_file.sh

Importar a atualização delta gerada

O processo básico de importação de uma atualização para o serviço de Atualização de Dispositivo permanece inalterado para atualizações delta e, portanto, se você ainda não fez isso, revise esta página: Como preparar uma atualização para ser importada para a Atualização de Dispositivo do Azure para Hub IoT

Gerar manifesto de importação

A primeira etapa para importar uma atualização para o serviço de Atualização de Dispositivo é sempre criar um manifesto de importação se você ainda não tiver um. Para obter mais informações sobre manifestos de importação, consulte Importar atualizações para a Atualização de Dispositivo. Nas atualizações delta, o manifesto de importação precisa referenciar dois arquivos:

A imagem SWU de destino recompactada criada quando você executou a ferramenta DiffGen.
O arquivo delta criado quando você executou a ferramenta DiffGen.

O recurso de atualização delta usa um recurso chamado arquivos relacionados, que requer um manifesto de importação que seja versão 5 ou posterior.

Para criar um manifesto de importação para sua atualização delta usando o recurso de arquivos relacionados, você precisa adicionar os objetos relatedFiles e downloadHandler ao seu manifesto de importação.

Use o objeto relatedFiles para especificar informações sobre o arquivo de atualização delta, incluindo o nome do arquivo, o tamanho do arquivo e o hash sha256. É importante ressaltar que você também precisa especificar duas propriedades exclusivas para o recurso de atualização delta:

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "[insert the source SWU image file hash]"
}

Ambas as propriedades são específicas do arquivo de imagem SWU de origem que você usou como entrada para a ferramenta DiffGen ao criar sua atualização delta. As informações sobre a imagem SWU de origem são necessárias no manifesto de importação, mesmo que você não esteja realmente importando a imagem de origem. Os componentes delta no dispositivo usam esses metadados sobre a imagem de origem para localizar a imagem no dispositivo depois que o delta é baixado.

Use o objeto downloadHandler para especificar como o agente de Atualização de Dispositivo orquestra a atualização delta usando o recurso de arquivos relacionados. A menos que você esteja personalizando sua própria versão do agente de atualização de dispositivos para funcionalidade delta, você só deve usar esse downloadHandler:

"downloadHandler": {
  "id": "microsoft/delta:1"
}

Você pode usar a CLI (Interface de Linha de Comando) do Azure para gerar um manifesto de importação para sua atualização delta. Se você não usou a CLI do Azure para criar um manifesto de importação antes, consulte Criar um manifesto de importação básico.

az iot du update init v5
--update-provider <replace with your Provider> --update-name <replace with your update Name> --update-version <replace with your update Version> --compat manufacturer=<replace with the value your device will report> model=<replace with the value your device will report> --step handler=microsoft/swupdate:2 properties=<replace with any desired handler properties (JSON-formatted), such as '{"installedCriteria": "1.0"}'> --file path=<replace with path(s) to your update file(s), including the full file name> downloadHandler=microsoft/delta:1 --related-file path=<replace with path(s) to your delta file(s), including the full file name> properties='{"microsoft.sourceFileHashAlgorithm": "sha256", "microsoft.sourceFileHash": "<replace with the source SWU image file hash>"}'

Salve o JSON do manifesto de importação gerado em um arquivo com a extensão .importmanifest.json

Importar usando o portal do Azure

Depois de criar seu manifesto de importação, você estará pronto para importar a atualização delta. Para importar, siga as instruções em Adicionar uma atualização à Atualização de Dispositivo para Hub IoT. Você deve incluir estes itens ao importar:

O arquivo .json do manifesto de importação criado na etapa anterior.
A imagem SWU de destino recompactada criada quando você executou a ferramenta DiffGen.
O arquivo delta criado quando você executou a ferramenta DiffGen.

Implantar a atualização delta em seus dispositivos

Quando você implanta uma atualização delta, a experiência no portal do Azure parece idêntica à implantação de uma atualização de imagem regular. Para obter mais informações sobre a implementação de atualizações, veja Implementar uma atualização utilizando a Atualização de Dispositivos para o Hub IoT do Azure.

Depois de criar a implantação para sua atualização delta, o serviço e o cliente de atualização de dispositivos identificam automaticamente se há uma atualização delta válida para cada dispositivo em que você está implantando. Se um delta válido for encontrado, a atualização delta será baixada e instalada nesse dispositivo. Se não for encontrada nenhuma atualização delta válida, a atualização completa da imagem (a imagem SWU de destino recompactada) será baixada como um substituto. Essa abordagem garante que todos os dispositivos nos quais você está implantando a atualização cheguem à versão apropriada.

Há três resultados possíveis para uma implantação de atualização delta:

Atualização delta instalada com êxito. O dispositivo está em uma nova versão.
A atualização delta não estava disponível ou falhou na instalação, mas ocorreu uma instalação de fallback bem-sucedida da imagem completa. O dispositivo está em uma nova versão.
Falha no delta e no fallback para a imagem completa. O dispositivo ainda está na versão antiga.

Para determinar quais dos resultados acima ocorreram, você pode exibir os resultados da instalação com o código de erro e o código de erro estendido selecionando qualquer dispositivo que esteja em um estado de falha. Se necessário, você também pode coletar logs de vários dispositivos com falha.

Se a atualização delta foi bem-sucedida, o dispositivo mostra o status "Bem-sucedido".

Se ocorreu uma falha na atualização delta, mas ela fez um fallback bem-sucedido para a imagem completa, ela mostra o seguinte status de erro:

resultCode: [valor maior que 0]
extendedResultCode: [diferente de zero]

Se a atualização não for bem-sucedida, será exibido um status de erro que pode ser interpretado usando essas instruções:

Comece com os erros do agente de Atualização de Dispositivo em result.h.

Os erros do agente de Atualização de Dispositivo específicos para a funcionalidade do Manipulador de Download usada para atualizações delta começam com 0x9:

Componente	Decimal	Hex	Observação
EXTENSION_MANAGER	0	0x00	Indica erros da lógica do manipulador de download do gerenciador de extensões. Exemplo: 0x900XXXXX
PLUGIN	1	0x01	Indica erros com o uso de bibliotecas compartilhadas de plug-in do manipulador de download. Exemplo: 0x901XXXXX
RESERVADO	2 - 7	0x02 – 0x07	Reservado para manipulador de download. Exemplo: 0x902XXXXX
COMMON	8	0x08	Indica erros na lógica de nível superior da extensão do manipulador de download delta. Exemplo: 0x908XXXXX
SOURCE_UPDATE_CACHE	9	0x09	Indica erros no cache de atualização de origem da extensão do manipulador de Download Delta. Exemplo: 0x909XXXXX
DELTA_PROCESSOR	10	0x0A	Código de erro para erros da API do processador delta. Exemplo: 0x90AXXXXX

Se o código de erro não estiver presente em result.h, provavelmente será um erro no componente do processador delta (separado do agente de Atualização de Dispositivo). Nesse caso, o extendedResultCode é um valor decimal negativo do seguinte formato hexadecimal: 0x90AXXXXX
- 9 é "Delta Facility"
- 0A is "Delta Processor Component" (ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)
- XXXXX é o código de erro de 20 bits do processador delta FIT

Se você não conseguir resolver o problema com base nas informações de código de erro, registre um problema do GitHub para obter assistência adicional.

Próximas etapas

Solução de problemas comuns