a5c-ai/ota-firmware-update

OTA Firmware Update Skill

Expert skill for over-the-air firmware update implementation in embedded systems. Provides expertise in update image generation, signing, transport protocols, partition management, and rollback mechanisms.

Overview

The OTA Firmware Update skill enables comprehensive firmware update capabilities:

• Delta update generation (diff algorithms)
• Image signing and encryption
• Update manifest generation
• MCUboot configuration
• A/B partition management
• Rollback mechanism implementation
• Cloud integration (AWS IoT, Azure IoT Hub)
• Update progress and status reporting

Capabilities

1. Update Image Generation

Generate firmware update images with metadata:

// Example: Update image generation configuration
const imageConfig = {
  type: 'full',  // or 'delta'
  input: 'build/firmware.bin',
  output: 'release/firmware-v1.2.0.update',
  version: {
    major: 1,
    minor: 2,
    patch: 0,
    build: 456
  },
  compression: 'lz4',  // none, lz4, zlib, lzma
  encryption: {
    algorithm: 'aes-128-ctr',
    keyFile: 'keys/update-key.bin'
  }
};

2. Image Signing

Sign firmware images for secure boot chain:

# Sign image with MCUboot imgtool
imgtool sign \
  --key keys/signing-key.pem \
  --align 4 \
  --version 1.2.0 \
  --header-size 0x200 \
  --slot-size 0x60000 \
  --pad-header \
  build/firmware.bin \
  release/firmware-v1.2.0-signed.bin

# Verify signature
imgtool verify \
  --key keys/signing-key.pub.pem \
  release/firmware-v1.2.0-signed.bin

3. Delta Update Generation

Generate differential updates to minimize transfer size:

// Delta update configuration
const deltaConfig = {
  baseVersion: 'v1.1.0',
  baseImage: 'releases/firmware-v1.1.0.bin',
  targetImage: 'build/firmware.bin',
  algorithm: 'bsdiff',  // bsdiff, xdelta, vcdiff
  output: 'patches/v1.1.0-to-v1.2.0.patch',
  metadata: {
    sourceVersion: '1.1.0',
    targetVersion: '1.2.0',
    sourceHash: 'sha256:...',
    targetHash: 'sha256:...'
  }
};

// Size comparison
// Full image: 245,760 bytes
// Delta patch: 12,340 bytes (95% reduction)

4. Update Manifest Generation

Generate update manifest with metadata:

{
  "version": "1.2.0",
  "build": 456,
  "timestamp": "2026-01-24T10:30:00Z",
  "images": [
    {
      "slot": "primary",
      "type": "application",
      "file": "firmware-v1.2.0-signed.bin",
      "size": 245760,
      "hash": {
        "algorithm": "sha256",
        "value": "3b9d8a2f..."
      },
      "signature": {
        "algorithm": "ecdsa-p256",
        "value": "base64..."
      }
    }
  ],
  "compatibility": {
    "minBootloaderVersion": "1.0.0",
    "hardwareRevision": ["rev-a", "rev-b"],
    "requiredBaseVersion": "1.1.0"
  },
  "delta": {
    "available": true,
    "baseVersions": ["1.1.0", "1.0.0"],
    "files": {
      "1.1.0": "patches/v1.1.0-to-v1.2.0.patch"
    }
  },
  "releaseNotes": "Bug fixes and performance improvements"
}

5. Partition Management (A/B Scheme)

Configure A/B partition scheme for safe updates:

/**
 * @brief Flash partition layout for A/B updates
 *
 * Partition    | Start      | Size   | Purpose
 * -------------|------------|--------|------------------
 * Bootloader   | 0x08000000 | 32KB   | MCUboot bootloader
 * Slot A       | 0x08008000 | 240KB  | Primary application
 * Slot B       | 0x08044000 | 240KB  | Secondary/staging
 * Scratch      | 0x08080000 | 64KB   | Swap scratch area
 * Config       | 0x08090000 | 16KB   | Persistent config
 */

typedef struct {
    uint32_t magic;           // Partition magic number
    uint8_t  image_ok;        // Image confirmed working
    uint8_t  copy_done;       // Swap operation complete
    uint16_t swap_type;       // None, Test, Revert, Permanent
    uint32_t version;         // Firmware version
    uint32_t crc32;           // Image CRC
} partition_header_t;

6. MCUboot Integration

Configure MCUboot for secure firmware updates:

# MCUboot configuration (prj.conf for Zephyr)
CONFIG_BOOTLOADER_MCUBOOT=y
CONFIG_MCUBOOT_SIGNATURE_KEY_FILE="keys/signing-key.pem"
CONFIG_MCUBOOT_ENCRYPTION_KEY_FILE="keys/encryption-key.pem"
CONFIG_MCUBOOT_EXTRA_IMGTOOL_ARGS="--pad --confirm"

# Image configuration
CONFIG_MCUBOOT_IMGTOOL_SIGN_VERSION="1.2.0"
CONFIG_MCUBOOT_GENERATE_UNSIGNED_IMAGE=n
CONFIG_MCUBOOT_GENERATE_CONFIRMED_IMAGE=y

# Update settings
CONFIG_MCUBOOT_SWAP_USING_SCRATCH=y
CONFIG_IMG_MANAGER=y
CONFIG_STREAM_FLASH=y

7. Rollback Mechanism

Implement automatic rollback on update failure:

/**
 * @brief Firmware update state machine
 */
typedef enum {
    UPDATE_STATE_IDLE,           // No update in progress
    UPDATE_STATE_DOWNLOADING,    // Receiving update image
    UPDATE_STATE_VERIFYING,      // Verifying signature/hash
    UPDATE_STATE_APPLYING,       // Writing to flash
    UPDATE_STATE_PENDING_REBOOT, // Ready to boot new image
    UPDATE_STATE_TESTING,        // Running new image (not confirmed)
    UPDATE_STATE_CONFIRMED,      // Update successful
    UPDATE_STATE_REVERTING,      // Rolling back to previous
    UPDATE_STATE_FAILED          // Update failed
} update_state_t;

/**
 * @brief Confirm update after successful boot
 *
 * Must be called after new firmware boots successfully.
 * Failure to confirm within timeout triggers automatic rollback.
 *
 * @param timeout_ms  Confirmation timeout in milliseconds
 * @return OTA_OK on success, error code otherwise
 */
ota_status_t ota_confirm_update(uint32_t timeout_ms);

/**
 * @brief Trigger manual rollback to previous version
 *
 * @return OTA_OK if rollback initiated, error otherwise
 */
ota_status_t ota_rollback(void);

8. Cloud Integration

Integrate with IoT cloud platforms:

// AWS IoT Jobs integration
const jobDocument = {
  operation: 'firmware-update',
  version: '1.2.0',
  files: {
    firmware: {
      url: 'https://firmware.s3.amazonaws.com/v1.2.0/firmware.bin',
      fileType: 'binary',
      size: 245760,
      sha256: '3b9d8a2f...'
    }
  },
  autoReboot: true,
  confirmationRequired: true
};

// Azure IoT Hub device twin update
const desiredProperties = {
  firmware: {
    version: '1.2.0',
    downloadUrl: 'https://blob.azure.com/firmware/v1.2.0.bin',
    checksum: 'sha256:3b9d8a2f...',
    updateTime: '2026-01-24T12:00:00Z'
  }
};

Process Integration

This skill integrates with the following processes:

| Process | Integration Point | |---------|-------------------| | ota-firmware-update.js | Primary OTA implementation | | secure-boot-implementation.js | Secure update chain | | bootloader-implementation.js | Bootloader integration |

Workflow

1. Setup Update Infrastructure

# Generate signing keys
imgtool keygen -k keys/signing-key.pem -t ecdsa-p256

# Extract public key for device
imgtool getpub -k keys/signing-key.pem > keys/signing-key.pub.pem

# Generate encryption key (optional)
openssl rand -hex 16 > keys/encryption-key.bin

2. Build Update Image

# Build firmware
west build -b nrf52840dk_nrf52840 app

# Sign with MCUboot
west sign -t imgtool \
  -- --key keys/signing-key.pem \
  --version 1.2.0

# Generate manifest
ota-tools manifest generate \
  --image build/zephyr/zephyr.signed.bin \
  --output release/manifest.json

3. Deploy Update

# Upload to S3 (AWS)
aws s3 cp release/ s3://firmware-bucket/v1.2.0/ --recursive

# Create IoT Job
aws iot create-job \
  --job-id firmware-update-v1.2.0 \
  --targets arn:aws:iot:region:account:thinggroup/devices \
  --document file://job-document.json

4. Monitor Progress

// Device-side progress reporting
const updateStatus = {
  state: 'downloading',
  progress: 45,
  version: '1.2.0',
  details: {
    bytesReceived: 110592,
    totalBytes: 245760,
    downloadSpeed: 12500  // bytes/sec
  }
};

// Report to cloud
mqtt.publish('$aws/things/device-id/jobs/job-id/update',
  JSON.stringify(updateStatus));

Output Schema

{
  "updateImage": {
    "file": "firmware-v1.2.0-signed.bin",
    "size": 245760,
    "hash": "sha256:3b9d8a2f...",
    "version": "1.2.0",
    "signed": true,
    "encrypted": false
  },
  "deltaPatches": [
    {
      "fromVersion": "1.1.0",
      "file": "patches/v1.1.0-to-v1.2.0.patch",
      "size": 12340,
      "savings": "95%"
    }
  ],
  "manifest": {
    "file": "manifest.json",
    "timestamp": "2026-01-24T10:30:00Z"
  },
  "deployment": {
    "platform": "aws-iot",
    "jobId": "firmware-update-v1.2.0",
    "targetDevices": 1500
  },
  "artifacts": [
    "firmware-v1.2.0-signed.bin",
    "manifest.json",
    "patches/v1.1.0-to-v1.2.0.patch"
  ]
}

Security Considerations

Key Management

• Store signing keys in secure HSM or key vault
• Use separate keys for development and production
• Implement key rotation policy
• Never embed private keys in firmware

Image Verification

• Always verify signature before applying update
• Verify hash after download completes
• Use hardware crypto acceleration when available
• Implement anti-rollback protection

Transport Security

• Use TLS 1.2+ for all update downloads
• Implement certificate pinning
• Verify server certificates
• Use unique device credentials

Best Practices

Update Design

• Support delta updates to reduce bandwidth
• Implement progress reporting
• Handle partial downloads (resume support)
• Test rollback thoroughly

Reliability

• Never interrupt flash operations
• Use wear leveling for update counters
• Implement power-loss protection
• Verify update before confirming

Testing

• Test on all hardware revisions
• Verify rollback scenarios
• Test with various network conditions
• Validate full update lifecycle

References

• MCUboot Documentation: https://docs.mcuboot.com/
• AWS IoT Jobs Developer Guide
• Azure IoT Hub Device Update
• TinyMCP for device integration
• Memfault OTA Best Practices

MCP Server Integration

Compatible MCP servers:

| Server | Purpose | |--------|---------| | tinymcp | Device control via Golioth | | esp-rainmaker-mcp | ESP32 RainMaker integration | | aws-iot-mcp | AWS IoT Jobs management |

See Also

• ota-firmware-update.js - OTA implementation process
• secure-boot-implementation.js - Secure boot setup
• bootloader-implementation.js - Bootloader development
• SK-016: Cryptographic Operations skill
• AG-005: Embedded Security Expert agent
• AG-009: Bootloader Expert agent