Atualizações Delta (Pré-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 o Hub IoT

• Os arquivos de atualização de origem e destino devem estar no formato SWUpdate (SWU).
• Dentro de 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 compressã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 junto 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 de Atualização de Dispositivo, seu dispositivo precisa do agente de Atualização de Dispositivo com o manipulador de atualizações 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çõ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.

Processador Delta

O processador delta no 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 seu manipulador de atualização possa instalar o arquivo SWU. Para adicionar o componente do processador delta à imagem do seu dispositivo e configurá-lo para uso, você pode baixar um pacote Debian para Ubuntu 20.04 e posterior a partir de https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0.

Se você usar outra distro, siga as instruções de README.md para usar o CMAKE para construir o processador delta a partir do código-fonte. 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 seu dispositivo

Depois que o arquivo de atualização delta é baixado para um dispositivo, ele é comparado com um válido <source_archive> previamente armazenado 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 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, em vez disso, pretender pré-preencher diretamente a imagem de origem no 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 providerparte 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

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

Você pode criar atualizações delta usando a ferramenta Diff Generation (DiffGen).

Pré-requisitos do ambiente

Antes de criar deltas com o DiffGen, você precisa baixar e instalar várias coisas na máquina do ambiente. Idealmente, use um ambiente Ubuntu 20.04 Linux ou um Subsistema 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>. Em seguida, o DiffGen usa o <recompressed_target_file>em vez de como o arquivo de <target_archive> destino para criar o diff. Os arquivos de imagem dentro do <recompressed_target_archive> são compactados com gzip.

Se seus arquivos SWU estiverem assinados, eles também exigirão o <signing_command> argumento 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 string de comando de assinatura executa o script recompress_and_sign_tool.py . Este script cria o <recompressed_target_file>. Além disso, esse script também assina o arquivo sw-description dentro do arquivo para criar um arquivo sw-description.sig .

Você pode usar o script de sign_file.sh de exemplo do repositório GitHub Azure/iot-hub-device-update-delta para criar uma comparação 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 seu arquivo de chave privada e salve-o. Consulte a seção Exemplos para obter exemplos de uso.

A tabela a seguir descreve os argumentos com mais detalhes:

Exemplos de DiffGen

Os exemplos a seguir operam a partir do diretório /mnt/o/temp no Subsistema 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 você deve se o arquivo SWU estiver assinado, você pode usar o exemplo sign_file.sh script mencionado anteriormente. Abra o script, edite-o para adicionar o caminho ao seu arquivo de chave privada, salve o script e execute o DiffGen da seguinte maneira.

O código a seguir cria uma comparação 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 que para qualquer outra atualização. Se ainda não o fez, certifique-se de que revê Como preparar uma atualização para ser importada para a Atualização de Dispositivo do Azure para o 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 Importando atualizações para a Atualização de dispositivo.

Os arquivos de manifesto de importação para atualizações delta devem fazer referência aos seguintes arquivos criados pela ferramenta DiffGen:

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

O recurso de atualização delta usa um recurso chamado 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 em 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. Mais importante, você também deve especificar as duas propriedades a seguir que são 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 uma entrada para a ferramenta DiffGen quando você criou sua 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 de baixarem a atualização delta.

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

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

Você pode usar o comando CLI az iot du update init v5 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 seu manifesto de importação gerado JSON com a extensão de arquivo .importmanifest.json.

Importar com o portal do Azure

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

• O arquivo *importmanifest.json que você criou anteriormente nas etapas anteriores
• A <recompressed_target_file> imagem SWU que a ferramenta DiffGen criou
• A <delta file> ferramenta DiffGen criada

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

A experiência de implantação da atualização delta no portal do Azure é a mesma que a implantação de 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 sua 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 no qual você está implantando. Se encontrarem um delta válido, 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 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:

• 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 for bem-sucedida, o dispositivo mostrará um 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 superior a 0>
  • extendedResultCode: <valor diferente de zero>

Solucionar problemas de atualizações com falha

As 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 que são 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 é um erro no componente do processador delta, separado do agente de Atualização de Dispositivo. Em caso afirmativo, o extendedResultCode é um valor decimal negativo no formato 0x90AXXXXXhexadecimal.

• 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 (Field Installation Tool)

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.

Conteúdos relacionados

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