agent-reference

Device Update for IoT Hub - Reference Agent Documentation

Overview

Device Update for IoT Hub is an Azure service that enables secure, scalable over-the-air (OTA) updates for IoT devices. This repository contains the reference implementation of the Device Update agent — a comprehensive, production-ready agent that demonstrates best practices for integrating Device Update capabilities into IoT devices and applications.

📖 For service documentation and tutorials, visit Device Update for IoT Hub on Microsoft Learn

What's New in 1.3.0

Feature	Description	Documentation
X.509 Certificate Auth	Full client certificate authentication with PKCS#11 and HSM support	X.509 Authentication Guide
Delta Download Handler	Bandwidth-efficient differential updates using Microsoft Delta	Building with Delta Handler
Service Status API	Cross-process SDK for querying agent state and managing idle/pause	GetAduServiceStatus SDK
Curl Default Downloader	Curl content downloader as default (required for Ubuntu 24.04, Debian 13)	Build Guide — Content Downloader
Ubuntu 24.04 LTS	Full support with GCC 13	Platform Matrix
Debian 13 (Trixie)	Full support with GCC 12	Platform Matrix
Detailed Error Reporting	ExtendedResultCode shown in IoT Hub "Last Attempted Update" details	Error Codes
Logging Improvements	Enhanced agent and rootkey workflow logging	—

Documentation Structure

🎯 Getting Started

Document	Description
Architecture Overview	Agent components, communication flow, security model, and update lifecycle
Quick Start Guide	Get the agent built and running in 15 minutes
Configuration Guide	Complete du-config.json reference with all connection types

🏗️ Building & Running

Document	Description
Building the Agent	Dependencies, platform support, build options, and CMake configuration
Building with Delta Handler	Enable the optional Microsoft Delta Download Handler
Running the Agent	Daemon setup, user/group configuration, command-line options
Installing from Packages	Install pre-built Debian packages on Raspberry Pi

🔐 Authentication & Security

Document	Description
X.509 Authentication	Certificate setup, PKCS#11, HSM integration, and testing
Goal State & Workflow	Deployment protocol, state machine, and cryptographic validation

🔌 Extensibility

Document	Description
Extensibility Points	Overview of all 5 extension types and first-party plugins
Implementing Custom Handlers	Step-by-step guide for creating custom Step Handlers
Registering Extensions	How to register handlers, downloaders, and enumerators
Extension Contract Versions	Versioning scheme for extension compatibility
Multi-Component Updates	Proxy updates and multi-step ordered execution

📱 Integration & SDK

Document	Description
Service Status API (SDK)	CrossProc query API, idle pause timer, and SDK examples
Modifying the Agent	Customization points for PnP interfaces, handlers, and OS porting
Simulating Update Results	Test deployments without real updates using the simulator handler

🔍 Operations & Troubleshooting

Document	Description
Troubleshooting Guide	Common issues, log collection, and error code decoding
Diagnostics Log Collection	Remote log collection and Azure Storage upload
Error Codes Reference	ExtendedResultCode encoding, facility codes, and result code generation
Update Manifest v4 Schema	Manifest format for multi-step and proxy updates

Quick Navigation

By Role

• 🔰 New to Device Update: Architecture Overview → Quick Start
• 📱 App Developer: Service Status API → Simulating Updates
• 🔧 Device Integrator: Building the Agent → X.509 Authentication
• 🏗️ Extension Developer: Extensibility Points → Implementing Custom Handlers
• 🛠️ DevOps Engineer: Running the Agent → Diagnostics Log Collection → Troubleshooting

By Scenario

• 🚀 Quick Evaluation: Quick Start Guide
• 🏭 Production Deployment: Configuration Guide → X.509 Authentication
• 📦 Delta Updates: Building with Delta Handler
• 🔧 Custom Update Types: Implementing Custom Handlers → Registering Extensions
• 🌐 Multi-Component Devices: Multi-Component Updates

Key Features by Version

Feature	v1.1	v1.2	v1.3	Description
Basic Updates	✅	✅	✅	APT, SWUpdate, Script handlers
Multi-Component	✅	✅	✅	Proxy updates and component enumeration
Enhanced Security	✅	✅	✅	Root key package validation
X.509 Auth	⚠️	✅	✅	Full certificate authentication with PKCS#11
Service Status API	❌	❌	✅	CrossProc query SDK with idle pause
Delta Download Handler	❌	❌	✅	Differential updates via Microsoft Delta
Curl Default Downloader	❌	❌	✅	Curl as default content downloader
Ubuntu 24.04 / Debian 13	❌	❌	✅	Latest platform support
Detailed Error Reporting	❌	❌	✅	ExtendedResultCode in IoT Hub details

Prerequisites

System Requirements

Requirement	Minimum	Recommended	Notes
Operating System	Ubuntu 20.04, Debian 11	Ubuntu 22.04+, Debian 12+	Platform matrix
Architecture	x64, ARM32, ARM64	x64, ARM64	ARM64 recommended for ARM deployments
Memory	128MB RAM	256MB RAM	Additional space needed during updates
Storage	100MB for agent	500MB+	Varies by update content size
Network	Internet connectivity	Stable broadband	Required for Azure IoT Hub communication

Quick Start

# Clone the repository
git clone https://github.com/Azure/iot-hub-device-update.git
cd iot-hub-device-update

# Install all dependencies
./scripts/install-deps.sh -a

# Build the agent
./scripts/build.sh -c

📚 See Building the Agent for build options, platform-specific guidance, and cross-compilation.

Sample Configuration

{
  "schemaVersion": "1.2",
  "aduShellTrustedUsers": ["adu", "do"],
  "iotHubProtocol": "mqtt",
  "agents": [
    {
      "name": "main",
      "runas": "adu",
      "connectionSource": {
        "connectionType": "string",
        "connectionData": "HostName=<hub>.azure-devices.net;DeviceId=<device>;SharedAccessKey=<key>"
      },
      "manufacturer": "Contoso",
      "model": "Smart-Device-v1"
    }
  ]
}

See Configuration Guide for all connection types (Connection String, AIS, X.509) and advanced options.

Getting Help

• 📖 Documentation: Microsoft Learn - Device Update
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Support: Azure Support
• 🤝 Contributing: CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md

---

Next Steps: Start with the Architecture Overview to understand the core concepts, then follow the Quick Start Guide to get hands-on.