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

Artigo
03/05/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, especialmente se houver apenas algumas alterações entre as atualizações de origem e de destino.

Nota

O recurso de atualização delta está atualmente em visualização pública.

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

Os arquivos de atualização de origem e destino devem ser no formato SWUpdate (SWU).
Dentro de 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 compressão zstd para produzir um delta ideal. Importe essa atualização SWU de destino recompactada para o serviço de Atualização de Dispositivo junto com o arquivo de atualização delta gerado.
Dentro do SWUpdate no dispositivo, a descompressão zstd também deve ser ativada.
- Este 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 de 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ções

Um manipulador de atualização integra-se com o 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ções se você ainda não tiver seu próprio manipulador de atualização SWUpdate que deseja modificar. Se você usar seu próprio manipulador de atualização, certifique-se de habilitar a descompactação zstd no SWUpdate.

Processador Delta

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

Para adicionar o componente do processador delta à imagem do dispositivo e configurá-lo para uso, siga as instruções de README.md para usar o CMAKE para construir o processador delta a partir da origem. A partir daí, instale o objeto compartilhado (libadudiffapi.so) diretamente copiando-o para o /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 seu 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 armazenado anteriormente 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 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). Desde que o dispositivo esteja configurado com o agente de Atualização de Dispositivo (versão 1.0 ou posterior) e o processador delta, o agente de Atualização de Dispositivo armazena em cache o arquivo SWU instalado automaticamente para uso posterior da atualização delta.

Se, em vez disso, 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 [provider] valor é a parte Provider do updateId para o arquivo SWU de origem.

ENCODED_HASH é a cadeia de caracteres hexadecimais base64 do SHA256 do binário, mas depois de codificar para a cadeia hexadecimal 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 o DiffGen, várias coisas precisam ser baixadas e/ou instaladas na máquina do ambiente. Recomendamos um ambiente Linux e especificamente o Ubuntu 20.04 (ou o Subsistema Windows para Linux se nativamente no Windows).

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

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

Dependências

O zstd_compression_tool é usado para descompactar os arquivos de imagem de um arquivo e recompactá-los com zstd. Este processo garante que todos os arquivos usados para geração diff tenham o mesmo algoritmo de compressã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 o 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 o arquivo de destino para criar o diff.
Os arquivos de imagem dentro de [recompressed_target_archive] são compactados com zstd.

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

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 string de comando de assinatura é executado recompress_and_sign_tool.py para criar o arquivo [recompressed_target_archive] e ter o arquivo sw-description dentro do arquivo assinado (o que significa que um arquivo sw-description.sig está presente). Você pode usar o script de exemplo sign_file.sh do repositório GitHub Azure/iot-hub-device-update-delta . Abra o script, edite-o para adicionar o caminho ao seu arquivo de chave privada e salve-o. Consulte a seção de exemplos para obter exemplos de uso.

A tabela a seguir descreve os argumentos com mais detalhes:

Argumento	Description
[source_archive]	Esta é a imagem contra a qual o delta se baseia ao criar o delta. Importante: esta imagem deve ser idêntica à imagem que já está presente no dispositivo (por exemplo, armazenada em cache de uma atualização anterior).
[target_archive]	Esta é 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) na máquina host onde o arquivo delta é colocado após a criação. Se o caminho não existir, a ferramenta o cria.
[log_folder]	O caminho na máquina host onde os logs são criados. Recomendamos definir esse local como uma subpasta do caminho de saída. Se o caminho não existir, a ferramenta o cria.
[working_folder]	O caminho na máquina onde os colaterais e outros arquivos de trabalho são colocados durante a geração delta. Recomendamos definir esse local como uma subpasta do caminho de saída. Se o caminho não existir, a ferramenta o cria.
[recompressed_target_archive]	O caminho na máquina host onde o arquivo de destino recompactado é criado. Este arquivo é usado em vez de target_archive> como o arquivo de <destino para geração de comparação. Se esse caminho existir antes de chamar 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 dentro do arquivo compactado. O arquivo sw-description no arquivo recompactado é 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` anexado. Cercar 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 inicial completo em vez disso (por exemplo, use /home/USER/keys/priv.pem em vez de ~/keys/priv.pem).

Exemplos de DiffGen

Nestes exemplos, estamos operando a partir do diretório /mnt/o/temp (no WSL):

Criando diferença entre o arquivo de origem de entrada e o arquivo de destino recompactado:

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), poderá usar o script de exemplo sign_file.sh mencionado anteriormente. Primeiro, abra o script e edite-o para adicionar o caminho ao seu arquivo de chave privada. Salve o script e execute o DiffGen da seguinte maneira:

Criando diferença entre o arquivo de origem de entrada e o arquivo de destino recompactado/reassinado:

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, portanto, se você ainda não o fez, não deixe de revisar esta página: Como preparar uma atualização a ser importada para a Atualização de Dispositivo do Azure para o 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, caso ainda não tenha um. Para obter mais informações sobre como importar manifestos, consulte Importando atualizações para a Atualização de Dispositivo. Para atualizações delta, seu manifesto de importação precisa fazer referência a 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 é a 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 objetos relatedFiles e downloadHandler ao seu manifesto de importação.

Use o relatedFiles objeto 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 que são 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 para o 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 importe 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 downloadHandler objeto 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 Dispositivo para a funcionalidade delta, você só deve usar este 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 tiver usado 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 com o portal do Azure

Depois de criar o 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 o Hub IoT. Você deve incluir estes itens ao importar:

O manifesto de importação .json arquivo 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 como implantar atualizações, consulte Implantar uma atualização usando a Atualização de Dispositivo para o Hub IoT do Azure.

Depois de criar a implantação para sua atualização delta, o serviço de Atualização de Dispositivo e o cliente identificam automaticamente se há uma atualização delta válida para cada dispositivo no qual você está implantando. Se um delta válido for encontrado, a atualização delta será baixada e instalada nesse dispositivo. Se não houver nenhuma atualização delta válida encontrada, a atualização de imagem completa (a imagem SWU de destino recompactada) será baixada como um fallback. Essa abordagem garante que todos os dispositivos que 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 nova versão.
A atualização Delta não estava disponível ou não foi instalada, mas ocorreu uma instalação de fallback bem-sucedida da imagem completa. O dispositivo está em nova versão.
Tanto o delta quanto o fallback para a imagem completa falharam. O dispositivo ainda está na versão antiga.

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

Se a atualização delta for bem-sucedida, o dispositivo mostrará um status "Aprovado".

Se a atualização delta falhou, mas fez um fallback bem-sucedido para a imagem completa, ele mostra o seguinte status de erro:

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

Se a atualização não foi bem-sucedida, ela mostra um status de erro que pode ser interpretado usando estas instruções:

Comece com os erros do Device Update Agent em result.h.

Os erros do Device Update Agent que são específicos para a funcionalidade do manipulador de download usada para atualizações delta começam com 0x9:

Componente	Decimal	Hex	Nota
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 o manipulador de download. Exemplo: 0x902XXXXX
COMUM	8	0x08	Indica erros na lógica de nível superior da extensão Delta Download Handler. 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, é provável que seja um erro no componente do processador delta (separado do agente de Atualização de Dispositivo). Em caso afirmativo, o extendedResultCode é um valor decimal negativo do seguinte formato hexadecimal: 0x90AXXXXX
- 9 é "Delta Facility"
- 0A é "Componente do processador Delta" (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 do código de erro, registre um problema no GitHub para obter mais assistência.

Próximos passos

Resolver problemas comuns

Share via