How azure/iot-hub-device-update works
Project Type and Purpose
• This is a native-agent project (“Device Update for IoT Hub”) written in C/C++ with a CLI tool, libraries, extensions and build/deployment scripts.
• Purpose: run on an edge or IoT device, retrieve OTA updates from Azure IoT Hub’s Device Update service, orchestrate update workflows, apply updates via pluggable handlers, then report status back to IoT Hub.
File Structure Analysis
Top-level components:
• cmake, vcpkg.json, CMakeLists.txt – cross-platform build & dependency definitions.
• src/agent – the core agent implementation (main.c, health management, shutdown service).
• src/adu-shell – CLI (“adu” shell) for local/manual update operations.
• src/communication_* – abstractions and IoT Hub manager implementation.
• src/adu_workflow, src/agent_orchestration, src/rootkey_workflow – orchestrate update life-cycle, cryptographic root-key handling.
• src/extensions – plugin framework: content downloaders, download handlers, component enumerators, step handlers, update-manifest handlers, extension manager.
• src/diagnostics_component – diagnostics workflows & helpers.
• src/logging – zlog integration.
• src/libaducpal, src/platform_layers – platform-abstraction layer (Linux/Windows).
• src/utils – common utilities (parsing, file, crypto, retry, reporting, D2C messaging, etc.).
• scripts & tools – CI/CD, Docker, package build, tests, sample tools.
• docs – architecture reference and how-to.
README Insights
• Confirms it’s the “reference agent” that talks to Azure IoT Hub’s Device Update service.
• Build/test instructions illustrating CLI, agent install, valgrind testing.
Main Components
a. Agent Core – process hosting workflows, extension loader and orchestrator.
b. CLI (adu-shell) – user-facing shell that invokes the Agent Core APIs.
c. Workflow Engine (agent_orchestration + adu_workflow + rootkey_workflow) – state machine managing update stages (download, validation, install, reboot, rollback).
d. Communication Layer – abstraction + IoT Hub communication manager for twin-desired/property subscriptions and D2C reporting.
e. Extension Manager & Extensions – dynamically loaded libraries for:
• Component Enumeration
• Content Downloading (curl, delivery optimization)
• Download Handlers (delta, full payload)
• Step Handlers (APT, script, wim, swupdate, simulator)
• Update-Manifest Handlers
f. Diagnostics Component – run diagnostic steps, upload logs.
g. Logging Subsystem – zlog integration.
h. Platform Abstraction – libaducpal + OS-specific layers (Linux/Windows).
i. Utilities – collection of helper libraries (config, crypto, parser, retry, file, URL, workflow data, etc.).
Interactions & Data Flows
• Agent Core ↔ IoT Hub (via Communication Layer): subscribe to desired properties, receive update instructions, send reported state & diagnostics.
• Agent Core → Workflow Engine: start new update workflow on instruction or CLI command.
• Workflow Engine → Extension Manager: load appropriate extension for each workflow stage (download, install, etc.).
• Extension → Platform Layer and Utils: perform file I/O, process spawning, cryptographic checks.
• Diagnostics Component invoked by Agent Core or workflows to gather device info and send back via Communication Layer.
• CLI → Agent Core APIs (IPC or direct function call) for manual operations.
Architectural Patterns & Principles
• Plugin architecture: extensions loaded at runtime via a shared-lib abstraction (shared_lib, extension_manager).
• Layered separation: presentation (CLI), orchestration (workflow), communication, extensions, platform abstraction, utilities.
• Dependency Injection via config files and CMake symbol exports.
• Event-driven state machine for workflows.
Technologies & Frameworks
• CMake + Ninja / Make – build system
• zlog – logging
• Parson JSON – lightweight JSON parsing
• Azure IoT Hub SDK – communication manager (client handles)
• C99, C++17 – language features
• Docker / Azure Pipelines / Terraform / Packer – CI/CD & E2E test infra