델타 업데이트(미리 보기)

아티클
02/25/2025

델타 업데이트를 사용하면 원본 이미지와 대상 이미지의 두 가지 전체 업데이트 간의 변경 내용만 나타내는 작은 업데이트를 생성할 수 있습니다. 이 방법은 특히 원본 업데이트와 대상 업데이트 간에 몇 가지 변경 내용만 있는 경우 디바이스에 업데이트를 다운로드하는 데 사용되는 대역폭을 줄이는 데 적합합니다.

참고 항목

Azure Device Update for IoT Hub의 델타 업데이트 기능은 현재 공개 미리 보기로 제공됩니다.

IoT Hub용 디바이스 업데이트에서 델타 업데이트를 사용하기 위한 요구 사항

원본 및 대상 업데이트 파일은 SWU(SWUpdate) 형식이어야 합니다.
각 SWUpdate 파일 내에는 Ext2, Ext3 또는 Ext4 파일 시스템을 사용하는 원시 이미지가 있어야 합니다.

델타 생성 프로세스는 gzip 압축을 사용하여 대상 SWU 업데이트를 다시 압축하여 최적의 델타를 생성합니다. 생성된 델타 업데이트 파일과 함께 압축된 대상 SWU 업데이트를 Device Update 서비스로 가져옵니다.

델타 프로세서 구성 요소에 대한 디바이스 업데이트 에이전트 구성

디바이스 업데이트 서비스에서 델타 업데이트를 다운로드하고 설치하려면 디바이스에 업데이트 처리기 및 델타 프로세서 구성 요소가 있고 구성된 디바이스 업데이트 에이전트가 필요합니다.

Device Update 에이전트

디바이스 업데이트 에이전트는 다운로드, 설치 및 다시 시작 작업을 포함하여 디바이스에서 업데이트 프로세스를 ‘오케스트레이션’합니다. 디바이스 업데이트 에이전트를 디바이스에 추가하고 사용하도록 구성하려면 디바이스 업데이트 에이전트 프로비저닝을 참조 하세요. 에이전트 버전 1.0 이상을 사용합니다.

업데이트 처리기

업데이트 처리기는 디바이스 업데이트 에이전트와 통합하여 실제 업데이트 설치를 수행합니다. 델타 업데이트의 경우 수정하려는 고유한 SWUpdate 업데이트 처리기가 아직 없는 경우 microsoft/swupdate:2 업데이트 처리기로 시작합니다.

델타 프로세서

Azure/iot-hub-device-update-delta의 델타 프로세서는 델타 파일이 다운로드된 후 디바이스에 원래 SWU 이미지 파일을 다시 만들어 업데이트 처리기가 SWU 파일을 설치할 수 있도록 합니다. 델타 프로세서 구성 요소를 디바이스 이미지에 추가하고 사용하도록 구성하려면 Ubuntu 20.04 이상용 https://github.com/Azure/iot-hub-device-update-delta/tree/main/preview/2.0.0Debian 패키지를 다운로드할 수 있습니다.

다른 배포를 사용하는 경우 README.md 지침에 따라 CMAKE를 사용하여 원본에서 델타 프로세서를 빌드합니다. 여기에서 다음과 같이 공유 개체를 /usr/lib 디렉터리에 복사하여 libadudiffapi.so 직접 설치합니다.

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

디바이스에 원본 SWU 이미지 파일 추가

델타 업데이트 파일이 디바이스에 다운로드되면 이전에 디바이스에 캐시된 유효한 <source_archive> 파일과 비교됩니다. 이 프로세스를 통해 델타 업데이트에서 전체 대상 이미지를 다시 만들 수 있습니다.

이 캐시된 이미지를 채우는 가장 간단한 방법은 디바이스 업데이트 서비스를 통해 디바이스에 전체 이미지 업데이트를 가져오 고 배포 하는 것입니다. 디바이스가 디바이스 업데이트 에이전트 버전 1.0 이상 및 델타 프로세서로 구성된 경우 에이전트는 이후 델타 업데이트 사용을 위해 설치된 SWU 파일을 자동으로 캐시합니다.

대신 디바이스에서 원본 이미지를 직접 미리 채울 경우 이미지가 필요한 경로입니다 <BASE_SOURCE_DOWNLOAD_CACHE_PATH>/sha256-<ENCODED HASH>. 기본적으로 <BASE_SOURCE_DOWNLOAD_CACHE_PATH> 경로 /var/lib/adu/sdc/<provider>입니다. 값은 providerprovider 원본 SWU 파일에 대한 updateId의 일부입니다.

ENCODED_HASH는 이진 파일 SHA256의 base64 16진수 문자열이지만 base64 16진수 문자열로 인코딩한 후 다음과 같이 문자를 인코딩합니다.

+는 octets _2B로 인코딩됩니다.
/는 octets _2F로 인코딩됩니다.
=는 octets _3D로 인코딩됩니다.

DiffGen 도구를 사용하여 델타 업데이트 생성

DiffGen(Diff Generation) 도구를 사용하여 델타 업데이트를 만들 수 있습니다.

환경 전제 조건

DiffGen을 사용하여 델타를 만들기 전에 환경 머신에 몇 가지 항목을 다운로드하고 설치해야 합니다. 이상적으로는 Ubuntu 20.04 Linux 환경을 사용하거나 Windows에 있는 경우 Linux용 Windows 하위 시스템.

다음 표에서는 필요한 콘텐츠, 다운로드 위치 및 필요한 경우 권장 설치를 보여 있습니다.

이진 이름	가져올 위치	설치 방법
DiffGen	Azure/iot-hub-device-update-delta GitHub 리포지토리	델타 업데이트를 생성하는 데 사용할 컴퓨터에서 OS 또는 배포판과 일치하는 버전을 다운로드합니다.
. NETCore 런타임, 버전 8.0.0	터미널 또는 패키지 관리자를 통해	Linux에 .NET을 설치합니다. 런타임만 필요합니다.

DiffGen을 사용하여 델타 업데이트 만들기

DiffGen 도구는 다음과 같은 필수 인수 및 구문을 사용하여 실행됩니다.

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

위의 명령은 recompress_tool.py 스크립트를 실행하여 만듭니다<recompressed_target_file>. 그런 다음 DiffGen은 diff를 <recompressed_target_file>만들기 위한 대상 파일 대신 <target_archive> 사용합니다. 내의 <recompressed_target_archive> 이미지 파일은 gzip으로 압축됩니다.

SWU 파일이 서명된 경우 DiffGen 명령의 <signing_command> 인수도 필요합니다.

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

서명 명령 문자열 매개 변수가 있는 DiffGenTool은 recompress_and_sign_tool.py 스크립트를 실행합니다. 이 스크립트는 .를 <recompressed_target_file>만듭니다. 또한 이 스크립트는 보관 파일 내에서 sw-description 파일에 서명하여 sw-description.sig 파일을 만듭니 다.

Azure/iot-hub-device-update-delta GitHub 리포지토리의 샘플 sign_file.sh 스크립트를 사용하여 입력 소스 파일과 다시 압축되고 다시 서명된 대상 파일 간에 diff를 만들 수 있습니다. 스크립트를 열고 편집하여 프라이빗 키 파일에 경로를 추가하고 저장합니다. 예제 사용량은 예제 섹션을 참조하세요.

다음 표에서는 이러한 인수를 좀 더 자세히 설명합니다.

인수	설명
`<source_archive>`	DiffGen이 델타를 만들기 위한 시작점으로 사용하는 기본 이미지입니다. 중요: 이 이미지는 디바이스에 이미 있는 이미지와 동일해야 합니다(예: 이전 업데이트에서 캐시됨).
`<target_archive>`	델타가 디바이스를 업데이트하는 이미지입니다.
`<output_path>`	생성된 델타 파일의 원하는 이름을 포함하여 생성된 후 델타 파일을 배치할 호스트 컴퓨터의 경로입니다. 경로가 없으면 도구에서 경로를 만듭니다.
`<log_folder>`	로그를 만들 호스트 컴퓨터의 경로입니다. 이 위치를 출력 경로의 하위 폴더로 정의하는 것이 가장 좋습니다. 경로가 없으면 도구에서 경로를 만듭니다.
`<working_folder>`	델타 생성 중에 담보 및 기타 작업 파일을 배치할 컴퓨터의 경로입니다. 이 위치를 출력 경로의 하위 폴더로 정의하는 것이 가장 좋습니다. 경로가 없으면 도구에서 경로를 만듭니다.
`<recompressed_target_archive>`	in을 만들 호스트 컴퓨터의 경로입니다 `<recompressed_target_file>` . diff `<recompressed_target_file>` 생성을 `<target_archive>` 위한 대상 파일 대신 사용됩니다. DiffGen 도구를 호출하기 전에 이 경로가 있으면 덮어씁니다. 출력 경로의 하위 폴더에서 이 파일을 정의하는 것이 가장 좋습니다.
`"<signing_command>"` (선택 사항)	에서 `<recompressed_target_archive>`sw-description 파일에 서명하기 위한 사용자 지정 가능한 명령입니다. 다시 압축된 보관 파일의 sw-description 파일은 서명 명령에 대한 입력 매개 변수로 사용됩니다. DiffGen은 .sig가 추가된 입력의 이름을 사용하여 서명 명령이 새 서명 파일을 만들 것으로 예상합니다. 전체 명령을 단일 매개 변수로 전달하려면 매개 변수를 큰따옴표로 묶어야 합니다. 또한 서명에 `~` 사용되는 키 경로에 문자를 사용하지 말고 대신 전체 홈 경로를 사용합니다. 예를 들어 ~/keys/priv.pem 대신 /home/USER/keys/priv.pem을 사용합니다.

DiffGen 예제

다음 예제는 Linux용 Windows 하위 시스템 /mnt/o/temp 디렉터리에서 작동합니다.

다음 코드는 입력 소스 파일과 다시 압축된 대상 파일 간에 차이(diff)를 만듭니다.

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

또한 서명 매개 변수를 사용하는 경우 SWU 파일이 서명된 경우 앞에서 언급한 샘플 sign_file.sh 스크립트를 사용할 수 있습니다. 스크립트를 열고 편집하여 프라이빗 키 파일에 경로를 추가하고 스크립트를 저장한 다음 다음과 같이 DiffGen을 실행합니다.

다음 코드는 입력 소스 파일과 다시 압축된 대상 파일과 다시 서명된 대상 파일 간에 차이(diff)를 만듭니다.

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

생성된 델타 업데이트 가져오기

델타 업데이트를 디바이스 업데이트 서비스로 가져오는 기본 프로세스는 다른 업데이트와 동일합니다. 아직 없는 경우 Azure Device Update for IoT Hub로 가져올 업데이트를 준비하는 방법을 검토해야 합니다.

가져오기 매니페스트 생성

디바이스 업데이트 서비스로 업데이트를 가져오려면 가져오기 매니페스트 파일이 있거나 만들어야 합니다. 자세한 내용은 디바이스 업데이트로 업데이트 가져오기를 참조하세요.

델타 업데이트에 대한 매니페스트 파일 가져오기는 DiffGen 도구에서 만든 다음 파일을 참조해야 합니다.

<recompressed_target_file> SWU 이미지
<delta file>입니다.

델타 업데이트 기능은 버전 5 이상 가져오기 매니페스트가 필요한 관련 파일이라는 기능을 사용합니다. 관련 파일 기능을 사용하려면 관련 파일 및 downloadHandler 개체를 가져오기 매니페스트에 포함해야 합니다.

개체를 relatedFiles 사용하여 파일 이름, 파일 크기 및 sha256 해시를 포함하여 델타 업데이트 파일에 대한 정보를 지정할 수 있습니다. 가장 중요한 것은 델타 업데이트 기능에 고유한 다음 두 가지 속성도 지정해야 한다는 것입니다.

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

두 속성은 델타 업데이트를 만들 때 DiffGen 도구에 대한 입력으로 사용한 속성과 관련이 <source image file> 있습니다. 실제로 원본 이미지를 가져오지 않더라도 가져오기 매니페스트에는 원본 SWU 이미지에 대한 정보가 필요합니다. 디바이스의 델타 구성 요소는 원본 이미지에 대한 이 메타데이터를 사용하여 델타 업데이트를 다운로드한 후 디바이스에서 해당 이미지를 찾습니다.

개체를 downloadHandler 사용하여 디바이스 업데이트 에이전트가 관련 파일 기능을 사용하여 델타 업데이트를 오케스트레이션하는 방법을 지정합니다. 델타 기능을 위해 고유한 버전의 디바이스 업데이트 에이전트를 사용자 지정하지 않는 한 다음 downloadHandler을 사용합니다.

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

Azure CLI 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>"}'

파일 확장자 .importmanifest.json 생성된 가져오기 매니페스트 JSON을 저장합니다.

Azure Portal을 사용하여 가져오기

가져오기 매니페스트를 만든 후 IoT Hub용 디바이스 업데이트에 업데이트 추가의 지침에 따라 델타 업데이트를 가져옵니다. 가져오기에 다음 항목을 포함해야 합니다.

이전 단계에서 이전에 만든 *importmanifest.json 파일
<recompressed_target_file> DiffGen 도구가 만든 SWU 이미지
<delta file> 만든 DiffGen 도구

디바이스에 대한 델타 업데이트 배포

Azure Portal의 델타 업데이트 배포 환경은 일반 이미지 업데이트를 배포하는 것과 동일합니다. 자세한 내용은 디바이스 업데이트를 사용하여 업데이트 배포를 참조 하세요.

델타 업데이트에 대한 배포를 만들면 디바이스 업데이트 서비스와 클라이언트는 배포하려는 각 디바이스에 대해 유효한 델타 업데이트가 있는지 자동으로 확인합니다. 유효한 델타를 찾으면 해당 디바이스에 델타 업데이트를 다운로드하여 설치합니다.

유효한 델타 업데이트를 찾지 못하면 전체 이미지 업데이트(압축된 대상 SWU 이미지)가 대신 대체로 다운로드됩니다. 이 접근 방법을 사용하면 업데이트를 배포하는 모든 디바이스에서 적절한 버전을 사용하도록 할 수 있습니다.

델타 업데이트 배포에는 다음과 같은 세 가지 결과가 발생할 수 있습니다.

델타 업데이트가 성공적으로 설치되었고 디바이스가 새 버전에 있습니다.
델타 업데이트를 사용할 수 없거나 설치하지 못했지만 전체 이미지의 대체 설치가 성공했으며 디바이스가 새 버전에 있습니다.
델타 및 대체(fallback) 설치가 모두 실패했으며 디바이스는 여전히 이전 버전에 있습니다.

발생한 오류 결과를 확인하려면 실패한 상태의 디바이스를 선택하여 오류 코드 및 확장된 오류 코드로 설치 결과를 볼 수 있습니다. 필요한 경우 여러 실패한 디바이스에서 로그를 수집할 수도 있습니다.

델타 업데이트에 성공하면 디바이스에 성공 상태가 표시됩니다.
델타 업데이트가 실패했지만 전체 이미지로의 대체에 성공한 경우 디바이스는 다음 오류 상태를 표시합니다.
- resultCode: <0보다 큰 값>
- extendedResultCode: <0이 아닌 값>

실패한 업데이트 문제 해결

실패한 업데이트는 다음 지침을 사용하여 해석할 수 있는 오류 상태를 표시합니다. result.h에서 디바이스 업데이트 에이전트 오류로 시작합니다.

델타 업데이트 다운로드 처리기 기능과 관련된 디바이스 업데이트 에이전트의 오류는 다음으로 0x9시작합니다.

구성 요소	소수	16진수	참고 항목
EXTENSION_MANAGER	0	0x00	확장 관리자 다운로드 처리기 논리의 오류를 나타냅니다. 예: `0x900XXXXX`
PLUGIN	1	0x01	다운로드 처리기 플러그 인 공유 라이브러리 사용 오류를 나타냅니다. 예: `0x901XXXXX`
예약됨	2 - 7	0x02 - 0x07	다운로드 처리기를 위해 예약되었습니다. 예: `0x902XXXXX`
일반	8	0x08	델타 다운로드 처리기 확장 최상위 논리의 오류를 나타냅니다. 예: `0x908XXXXX`
SOURCE_UPDATE_CACHE	9	0x09	델타 다운로드 처리기 확장 원본 업데이트 캐시의 오류를 나타냅니다. 예: `0x909XXXXX`
DELTA_PROCESSOR	10	0x0A	델타 프로세서 API의 오류에 대한 오류 코드입니다. 예: `0x90AXXXXX`

result.h에 오류 코드가 없는 경우 디바이스 업데이트 에이전트와는 별도로 델타 프로세서 구성 요소의 오류일 수 있습니다. 그렇다면 extendedResultCode 16진수 형식 0x90AXXXXX의 음수 10진수 값입니다.

9 는 "Delta Facility"입니다.
0A 는 "Delta Processor Component"(ADUC_COMPONENT_DELTA_DOWNLOAD_HANDLER_DELTA_PROCESSOR)입니다.
XXXXX 는 FIT(필드 설치 도구) 델타 프로세서의 20비트 오류 코드입니다.

오류 코드 정보를 기반으로 문제를 해결할 수 없는 경우 GitHub 문제를 제출하여 추가 지원을 받으세요.

다음을 통해 공유

델타 업데이트(미리 보기)

IoT Hub용 디바이스 업데이트에서 델타 업데이트를 사용하기 위한 요구 사항

델타 프로세서 구성 요소에 대한 디바이스 업데이트 에이전트 구성

Device Update 에이전트

업데이트 처리기

델타 프로세서

디바이스에 원본 SWU 이미지 파일 추가

DiffGen 도구를 사용하여 델타 업데이트 생성

환경 전제 조건

DiffGen을 사용하여 델타 업데이트 만들기

DiffGen 예제

생성된 델타 업데이트 가져오기

가져오기 매니페스트 생성

Azure Portal을 사용하여 가져오기

디바이스에 대한 델타 업데이트 배포

실패한 업데이트 문제 해결

피드백

추가 리소스

다음을 통해 공유

델타 업데이트(미리 보기)

IoT Hub용 디바이스 업데이트에서 델타 업데이트를 사용하기 위한 요구 사항

델타 프로세서 구성 요소에 대한 디바이스 업데이트 에이전트 구성

Device Update 에이전트

업데이트 처리기

델타 프로세서

디바이스에 원본 SWU 이미지 파일 추가

DiffGen 도구를 사용하여 델타 업데이트 생성

환경 전제 조건

DiffGen을 사용하여 델타 업데이트 만들기

DiffGen 예제

생성된 델타 업데이트 가져오기

가져오기 매니페스트 생성

Azure Portal을 사용하여 가져오기

디바이스에 대한 델타 업데이트 배포

실패한 업데이트 문제 해결

관련 콘텐츠

피드백

추가 리소스