OtaSoftwareUpdateProvider Cluster

Cluster ID: 0x0029  |  Endpoint: Fixed on Endpoint 0 (Root Endpoint)  |  Role: Client Cluster (implemented by the Provider node)

OtaSoftwareUpdateProvider is the server-side Cluster of the Matter OTA (Over-The-Air) firmware update mechanism — it runs on the node that provides firmware images (typically a Hub, gateway, or cloud proxy), and is responsible for responding to firmware query requests from other devices, controlling update pacing, and receiving update completion notifications.

In Matter's OTA architecture, the device that needs an update is called the Requestor, and the node that provides firmware is called the Provider. The Requestor proactively queries the Provider, which tells it whether a new version is available, where to download it, and whether user consent is required. The entire flow uses a "pull" model, not push.

Commands

The OtaSoftwareUpdateProvider Cluster has 3 request commands, of which 2 have corresponding response commands and 1 is a one-way notification. These three commands form the complete OTA update lifecycle: Query → Confirm installation → Notify completion. Click on a command ID in the table below to jump to its detailed description.

Requestor → Provider (Request Commands)

Provider → Requestor (Response Commands)

QueryImage — Query Firmware Update (0x00)

The Requestor sends this command to ask the Provider: "I'm a device of this model and version — do you have an update for me?" This is the first step of the entire OTA flow. The Provider determines whether there is an applicable firmware image based on the Requestor's vendor ID, product ID, current version number, and other information.

QueryImageResponse Response Fields

↑ Back to Commands

ApplyUpdateRequest — Request to Install Update (0x02)

After the Requestor downloads and verifies the firmware image, it sends this command to ask the Provider: "I'm ready to install — can I proceed?" The Provider can make a final decision at this point — approve installation, require waiting, or cancel the update. This step gives the Provider ultimate control over the entire update flow.

ApplyUpdateResponse Response Fields

↑ Back to Commands

NotifyUpdateApplied — Notify Update Completed (0x04)

After the Requestor successfully installs the firmware and reboots, it sends this command to inform the Provider that the update is complete. This is the last step of the entire OTA flow — a one-way notification with no response command. Upon receipt, the Provider can update its records (e.g., marking the device as updated to the new version).

↑ Back to Commands

Enum Definitions

StatusEnum (Query Result Status)

The Status field of QueryImageResponse uses this enum to indicate the Provider's answer to the firmware query.

ApplyUpdateActionEnum (Installation Decision)

The Action field of ApplyUpdateResponse uses this enum to indicate the Provider's decision on the installation request.

DownloadProtocolEnum (Download Protocol)

The ProtocolsSupported parameter of QueryImage uses this enum to declare which firmware download methods the Requestor supports.

Example Data

QueryImage Interaction Example

The Requestor queries the Provider for available updates — the Provider replies "new version available":

// Requestor → Provider: Query for available firmware
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0029",
      "commandId": "0x00"          // QueryImage
    },
    "commandFields": {
      "vendorID": 65521,           // Vendor ID (0xFFF1 = test vendor)
      "productID": 32769,          // Product ID
      "softwareVersion": 1,        // Current firmware version number
      "protocolsSupported": [0],   // Supported download protocols: BDXSynchronous
      "hardwareVersion": 0,        // Optional: hardware version
      "location": "CN",            // Optional: ISO 3166-1 country code
      "requestorCanConsent": true, // Optional: whether Requestor can show consent dialog to user
      "metadataForProvider": null  // Optional: vendor-specific data
    }
  }]
}

// Provider → Requestor: Update available
{
  "status": 0,                     // UpdateAvailable
  "delayedActionTime": 0,         // No waiting needed, download immediately
  "imageURI": "bdx://provider-node-id/firmware-v2.ota",
  "softwareVersion": 2,           // New firmware version number
  "softwareVersionString": "2.0.0",
  "updateToken": "dXBkYXRlLXRva2VuLXYy", // Base64-encoded update token
  "userConsentNeeded": false,      // No additional user confirmation needed
  "metadataForRequestor": null     // No vendor-specific data
}

ApplyUpdateRequest Interaction Example

The Requestor has finished downloading and asks the Provider to confirm whether installation can proceed:

// Requestor → Provider: Download complete, requesting to apply update
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0029",
      "commandId": "0x02"          // ApplyUpdateRequest
    },
    "commandFields": {
      "updateToken": "dXBkYXRlLXRva2VuLXYy",  // Token from QueryImageResponse
      "newVersion": 2              // Version number to be installed
    }
  }]
}

// Provider → Requestor: Confirm installation
{
  "action": 0,                     // Proceed (allow installation)
  "delayedActionTime": 0           // No waiting needed
}

NotifyUpdateApplied Example

After the Requestor successfully installs and reboots, it notifies the Provider that the update is complete:

// Requestor → Provider: Successfully installed and rebooted
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0029",
      "commandId": "0x04"          // NotifyUpdateApplied
    },
    "commandFields": {
      "updateToken": "dXBkYXRlLXRva2VuLXYy",  // Original update token
      "softwareVersion": 2         // Current version number after update
    }
  }]
}
// This command has no response (one-way notification)

Common Scenarios