Atualizações delta (Visualização)

As atualizações delta permitem gerar pequenas atualizações que representam 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.

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

• Os arquivos de atualização de origem e de 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.

O processo de geração delta recompacta a atualização SWU de destino usando a compactação gzip para produzir um delta ideal. Você importa a atualização SWU de destino recompactada para o serviço de Atualização de Dispositivo, juntamente com o arquivo de atualização delta gerado.

Configuração do agente de Atualização de Dispositivo para o componente do processador delta

Para baixar e instalar atualizações delta do serviço atualização de dispositivo, seu dispositivo precisa do agente de Atualização de Dispositivo com o manipulador de atualização e o componente do processador delta 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. Para adicionar o agente de Atualização de Dispositivo a um dispositivo e configurá-lo para uso, consulte provisionamento do agente de Atualização de Dispositivo. Use o agente versão 1.0 ou posterior.

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.

Processador delta

O processador delta em Azure/iot-hub-device-update-delta recria o arquivo de imagem SWU original em seu dispositivo após o download do arquivo delta, para que o manipulador de atualização possa instalar o arquivo SWU. Para adicionar o componente do processador delta à imagem do dispositivo e configurá-lo para uso, você pode baixar um pacote Debian para Ubuntu 20.04 e posterior de https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

Se você usar outra distribuição, siga as instruções de README.md para usar o CMAKE para criar o processador delta de origem. A partir daí, instale o objeto compartilhado libadudiffapi.so diretamente copiando-o para o diretório /usr/lib, da seguinte maneira:

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

Adicionar um arquivo de imagem SWU de origem ao dispositivo

Depois que o arquivo de atualização delta é baixado em um dispositivo, ele é comparado com um <source_archive> válido armazenado anteriormente em cache no dispositivo. Esse processo permite que a atualização delta recrie a imagem de destino completa.

A maneira mais simples de preencher essa imagem armazenada em cache é importar e implantar uma atualização de imagem completa no dispositivo por meio do serviço de Atualização de Dispositivo. Se o dispositivo estiver configurado com o agente de Atualização de Dispositivo versão 1.0 ou posterior e o processador delta, o agente armazenará em cache o arquivo SWU instalado automaticamente para uso posterior da atualização delta.

Se você quiser pré-preencher diretamente a imagem de origem em seu dispositivo, o caminho em que 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/<provedor>. 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

Geração de atualização delta usando a ferramenta DiffGen

Você pode criar atualizações delta usando a ferramenta DiffGen (Geração DiffGen).

Pré-requisitos do ambiente

Antes de criar deltas com DiffGen, você precisa baixar e instalar várias coisas no computador do ambiente. Idealmente, use um ambiente do Ubuntu 20.04 Linux ou o Subsistema do Windows para Linux se você estiver no Windows.

A tabela a seguir mostra o conteúdo necessário, onde obtê-lo e a instalação recomendada, se necessário.

Criação de atualização delta usando DiffGen

A ferramenta DiffGen é executada com os seguintes argumentos e sintaxe necessários:

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive>

O comando anterior executa o script recompress_tool.py, que cria o <recompressed_target_file>. DiffGen, em seguida, usa o <recompressed_target_file> em vez de <target_archive> como o arquivo de destino para criar a diferença. Os arquivos de imagem dentro do <recompressed_target_archive> são compactados com gzip.

Se os arquivos SWU estiverem assinados, eles também exigirão o argumento <signing_command> no comando DiffGen:

DiffGenTool <source_archive> <target_archive> <output_path> <log_folder> <working_folder> <recompressed_target_archive> "<signing_command>"

O DiffGenTool com o parâmetro de cadeia de caracteres de comando de assinatura executa o script recompress_and_sign_tool.py. Esse script cria o <recompressed_target_file>. Além disso, esse script também assina o arquivo sw-description no arquivo morto para criar um arquivo sw-description.sig.

Você pode usar o script sign_file.sh de exemplo do repositório GitHub Azure/iot-hub-device-update-delta para criar uma diferença entre o arquivo de origem de entrada e um arquivo de destino recompactado e reassinado. Abra o script, edite-o para adicionar o caminho ao arquivo de chave privada e salve-o. Consulte a seção Exemplos para uso de exemplo.

A tabela a seguir descreve os argumentos com mais detalhes:

Exemplos de DiffGen

Os exemplos a seguir operam fora do diretório /mnt/o/temp no Subsistema do Windows para Linux.

O código a seguir cria uma diferença entre o arquivo de origem de entrada e um arquivo de destino recompactado:

sudo ./DiffGenTool  
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu
/mnt/o/temp/<delta file to create>
/mnt/o/temp/logs
/mnt/o/temp/working
/mnt/o/temp/<recompressed target file to create>.swu

Se você também usar o parâmetro de assinatura, que deverá ser assinado se o arquivo SWU estiver assinado, você poderá usar o script sign_file.sh de exemplo mencionado anteriormente. Abra o script, edite-o para adicionar o caminho ao arquivo de chave privada, salve o script e execute DiffGen da seguinte maneira.

O código a seguir cria uma diferença entre o arquivo de origem de entrada e um arquivo de destino recompactado e reassinado:

sudo ./DiffGenTool  
/mnt/o/temp/<source file>.swu
/mnt/o/temp/<target file>.swu   
/mnt/o/temp/<delta file to create>  
/mnt/o/temp/logs  
/mnt/o/temp/working  
/mnt/o/temp/<recompressed target file to create>.swu  
/mnt/o/temp/<path to script>/<sign_file>.sh

Importação de atualização delta gerada

O processo básico de importação de uma atualização delta para o serviço de Atualização de Dispositivo é o mesmo de qualquer outra atualização. Caso ainda não tenha feito isso, examine Como preparar uma atualização a ser importada para a Atualização de Dispositivo do Azure para Hub IoT.

Gerar o manifesto de importação

Para importar uma atualização para o serviço de Atualização de Dispositivo, você deve ter ou criar um arquivo de manifesto de importação. Para obter mais informações, consulte Importar atualizações para a Atualização de Dispositivo.

Importar arquivos de manifesto para atualizações delta deve referenciar os seguintes arquivos que a ferramenta DiffGen criou:

• A imagem SWU do <recompressed_target_file>
• O <delta file>

O recurso de atualização delta usa uma funcionalidade chamada arquivos relacionados que requer um manifesto de importação versão 5 ou posterior. Para usar o recurso de arquivos relacionados, você deve incluir os objetos relatedFiles e downloadHandler no 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. O mais importante é que você também deve especificar as duas propriedades a seguir exclusivas para o recurso de atualização delta:

"properties": {
      "microsoft.sourceFileHashAlgorithm": "sha256",
      "microsoft.sourceFileHash": "<source SWU image file hash>"
}

Ambas as propriedades são específicas para o <source image file> que você usou como entrada para a ferramenta DiffGen quando criou a atualização delta. O manifesto de importação precisa das informações sobre a imagem SWU de origem, 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 essa imagem no dispositivo depois que eles baixam a atualização delta.

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ê personalize sua própria versão do agente de Atualização de Dispositivo para funcionalidade delta, use o seguinte downloadHandler:

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

Você pode usar o comando az iot du update init v5 da CLI do Azure para gerar um manifesto de importação para sua atualização delta. Para obter mais informações, consulte Criar um manifesto de importação básico.

--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 com a extensão de arquivo .importmanifest.json.

Importar usando o portal do Azure

Depois de criar o manifesto de importação, importe a atualização delta seguindo as instruções em Adicionar uma atualização à Atualização do Dispositivo para o Hub IoT. Você deve incluir os seguintes itens na importação:

• O arquivo *importmanifest.json criado anteriormente nas etapas anteriores
• A imagem SWU <recompressed_target_file> criada pela ferramenta DiffGen
• O <delta file> criado pela ferramenta DiffGen

Implantação de atualização delta para dispositivos

A experiência de implantação de atualização delta no portal do Azure é a mesma que implantar uma atualização de imagem regular. Para obter mais informações, consulte Implantar uma atualização usando a Atualização de Dispositivo.

Depois de criar a implantação para a atualização delta, o serviço de Atualização de Dispositivo e o cliente determinam automaticamente se há uma atualização delta válida para cada dispositivo em que você está implantando. Se encontrarem um delta válido, eles baixarão e instalarão a atualização delta nesse dispositivo.

Se eles não encontrarem uma atualização delta válida, a atualização de imagem completa (a imagem SWU de destino recompactada) será baixada como um fallback. 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:

• A atualização delta foi instalada com êxito e o dispositivo está na nova versão.
• A atualização delta não estava disponível ou não foi instalada, mas uma instalação de fallback da imagem completa foi bem-sucedida e o dispositivo está na nova versão.
• As instalações delta e fallback falharam e o dispositivo ainda está na versão antiga.

Para determinar qual resultado de falha 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 uma atualização delta tiver sido bem-sucedida, o dispositivo mostrará o status Bem-sucedido.

• Se uma atualização delta falhou, mas o fallback para a imagem completa foi bem-sucedido, o dispositivo mostra o seguinte status de erro:

  • resultCode: <valor maior que 0>
  • extendedResultCode: <valor diferente de zero>

Solucionar problemas de atualizações com falha

Atualizações malsucedidas exibem um status de erro que você pode interpretar usando as instruções a seguir. 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 de atualizações delta começam com 0x9:

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 no 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 da Ferramenta de Instalação de Campo (FIT)

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

Conteúdo relacionado

• Esquema de manifesto de importação da Atualização de Dispositivo do Azure para Hub IoT
• Solução de problemas comuns