OtaSoftwareUpdateRequestor Cluster

Cluster ID: 0x002A  |  Endpoint: Endpoint 0 (Root Endpoint)  |  Role: Server (device acts as OTA client)

OtaSoftwareUpdateRequestor is the client side of the Matter OTA update system — i.e., the device that needs to be updated. It is responsible for querying the OTA Provider (update provider, corresponding to Cluster 0x0029) for new versions, downloading firmware, and applying updates. All Matter devices that support OTA must implement this Cluster.

Commands

OtaSoftwareUpdateRequestor has only 1 command. It is not initiated by the device itself, but sent to the device by an external node (typically an OTA Provider or management node), informing the device that it can query a specific Provider for updates.

AnnounceOTAProvider — Announce OTA Provider (0x00)

An external node uses this command to inform a device: "There is an OTA Provider that can provide updates for you." Upon receiving this command, the device should query the specified Provider for updates as soon as possible (by invoking the Provider's QueryImage command). This is the core trigger mechanism for push-style OTA — allowing devices to be passively notified rather than constantly polling.

↑ Back to Commands

Attributes

OtaSoftwareUpdateRequestor has 4 application attributes, divided into two groups: "Provider Configuration" and "Update State".

Provider Configuration (0x0000)

Configures which OTA Providers the device should query for updates. Each Fabric can configure at most one Provider.

ProviderLocation Struct

↑ Back to Attributes

Update State (0x0001 - 0x0003)

Reflects the device's current OTA update state. These attributes are all read-only; apps track update progress by subscribing to them.

↑ Back to Attributes

Enum Quick Reference

UpdateStateEnum — Update State

Describes the complete lifecycle of the device's OTA state machine, with 9 states:

AnnouncementReasonEnum — Announcement Reason

Used in the AnnounceOTAProvider command to inform the device of the reason for this announcement:

ChangeReasonEnum — State Change Reason

Used in the StateTransition event to explain the reason for the state machine transition:

Events

OtaSoftwareUpdateRequestor defines 3 events covering the key milestones of the OTA lifecycle. Subscribing to these events allows real-time tracking of the device's update process, which is more timely than polling attributes.

StateTransition — State Transition Event (0x00)

Triggered whenever the OTA state machine transitions from one state to another. This is the most critical event for tracking the update flow — by listening to it, you can follow every step from idle to querying, from downloading to applying.

Event report example — transitioning from Idle to Downloading:

{
  "eventReports": [{
    "eventData": {
      "path": {
        "endpointId": 0,
        "clusterId": "0x002A",
        "eventId": "0x00"          // StateTransition
      },
      "eventNumber": 15,
      "priority": "INFO",
      "data": {
        "0": 1,                    // PreviousState = Idle
        "1": 4,                    // NewState = Downloading
        "2": 1,                    // Reason = Success (query succeeded, starting download)
        "3": 5                     // TargetSoftwareVersion = 5
      }
    }
  }]
}

↑ Back to Events

VersionApplied — Version Applied Event (0x01)

Triggered after a new firmware version is successfully applied (typically reported after device reboot). This event confirms that the update is truly complete. Its priority is Critical, ensuring it is not discarded even when the event queue is full.

Event report example:

{
  "eventReports": [{
    "eventData": {
      "path": {
        "endpointId": 0,
        "clusterId": "0x002A",
        "eventId": "0x01"          // VersionApplied
      },
      "eventNumber": 18,
      "priority": "CRITICAL",
      "data": {
        "0": 5,                    // SoftwareVersion = 5 (newly applied version number)
        "1": 4                     // ProductID = 4 (product ID)
      }
    }
  }]
}

↑ Back to Events

DownloadError — Download Error Event (0x02)

Triggered when an error is encountered during firmware download. This event provides contextual information at the time of failure (bytes downloaded, progress, etc.), which helps diagnose network issues or Provider-side faults.

Event report example — error occurred at 75% download:

{
  "eventReports": [{
    "eventData": {
      "path": {
        "endpointId": 0,
        "clusterId": "0x002A",
        "eventId": "0x02"          // DownloadError
      },
      "eventNumber": 16,
      "priority": "INFO",
      "data": {
        "0": 5,                    // SoftwareVersion = 5
        "1": 512,                  // BytesDownloaded = 512
        "2": 75,                   // ProgressPercent = 75 (error occurred at 75% download)
        "3": -1                    // PlatformCode = -1 (platform error code, nullable)
      }
    }
  }]
}

↑ Back to Events

Example Data

Attribute read results from an idle device's OtaSoftwareUpdateRequestor Cluster:

{
  // --- Default OTA Providers ---
  "0x0000": [                     // DefaultOTAProviders (can configure multiple)
    {
      "providerNodeID": 12345,    // Provider's Node ID
      "endpoint": 0,              // Endpoint on the Provider where the OTA Provider Cluster resides
      "fabricIndex": 1            // Fabric index this entry belongs to
    }
  ],

  // --- Update Capability ---
  "0x0001": true,                 // UpdatePossible = true (device can currently accept updates)

  // --- Update State ---
  "0x0002": 0,                    // UpdateState = Idle (currently idle, not in an update flow)
  "0x0003": null                  // UpdateStateProgress = null (no progress information)
}

Common Scenarios