OTA 更新提供者 Cluster（OtaSoftwareUpdateProvider）

Cluster ID: 0x0029  |  所在 Endpoint: 固定在 Endpoint 0（Root Endpoint） |  角色: Client Cluster（由 Provider 节点实现）

OtaSoftwareUpdateProvider 是 Matter OTA（Over-The-Air）固件更新机制的服务端 Cluster —— 它运行在提供固件镜像的节点上（通常是 Hub、网关或云端代理），负责响应其他设备的固件查询请求、 管控更新节奏、以及接收更新完成通知。

在 Matter 的 OTA 架构中，需要更新的设备叫做 Requestor（请求者）， 提供固件的节点叫做 Provider（提供者）。Requestor 主动向 Provider 发起查询， Provider 告诉它有没有新版本、从哪里下载、是否需要用户同意。整个流程是「拉取」模式，不是推送。

命令（Commands）

OtaSoftwareUpdateProvider Cluster 共有 3 个请求命令，其中 2 个有对应的响应命令，1 个是单向通知。 这三个命令构成了完整的 OTA 更新生命周期：查询 → 确认安装 → 通知完成。 点击下方表格中的命令 ID 可跳转到对应的详细说明。

Requestor → Provider（请求命令）

Provider → Requestor（响应命令）

QueryImage —— 查询固件更新（0x00）

Requestor 发送此命令询问 Provider：「我是这个型号、这个版本的设备，你那有没有更新给我？」 这是整个 OTA 流程的第一步。Provider 根据 Requestor 提供的厂商 ID、产品 ID、 当前版本号等信息，判断是否有适用的固件镜像。

QueryImageResponse 响应字段

↑ 返回命令列表

ApplyUpdateRequest —— 请求安装更新（0x02）

Requestor 下载完固件镜像并校验通过后，发送此命令询问 Provider：「我准备好安装了，可以继续吗？」 Provider 可以在此刻做最后的决策 —— 批准安装、要求等待、或者取消更新。 这一步的存在让 Provider 对整个更新流程拥有最终控制权。

ApplyUpdateResponse 响应字段

↑ 返回命令列表

NotifyUpdateApplied —— 通知更新已完成（0x04）

Requestor 成功安装固件并重启后，发送此命令告知 Provider 更新已完成。 这是整个 OTA 流程的最后一步 —— 一个单向通知，没有响应命令。 Provider 收到后可以更新自己的记录（如标记该设备已更新到新版本）。

↑ 返回命令列表

枚举定义

StatusEnum（查询结果状态）

QueryImageResponse 的 Status 字段使用此枚举，表示 Provider 对固件查询的回答。

ApplyUpdateActionEnum（安装决策）

ApplyUpdateResponse 的 Action 字段使用此枚举，表示 Provider 对安装请求的决策。

DownloadProtocolEnum（下载协议）

QueryImage 的 ProtocolsSupported 参数使用此枚举，声明 Requestor 支持哪些固件下载方式。

示例数据

QueryImage 交互示例

Requestor 向 Provider 查询可用更新 —— Provider 回复「有新版本可用」：

// Requestor → Provider：查询是否有可用固件
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0029",
      "commandId": "0x00"          // QueryImage
    },
    "commandFields": {
      "vendorID": 65521,           // 厂商 ID（0xFFF1 = 测试厂商）
      "productID": 32769,          // 产品 ID
      "softwareVersion": 1,        // 当前固件版本号
      "protocolsSupported": [0],   // 支持的下载协议：BDXSynchronous
      "hardwareVersion": 0,        // 可选：硬件版本
      "location": "CN",            // 可选：ISO 3166-1 国家代码
      "requestorCanConsent": true, // 可选：Requestor 能否向用户展示同意确认
      "metadataForProvider": null  // 可选：厂商自定义数据
    }
  }]
}

// Provider → Requestor：有可用更新
{
  "status": 0,                     // UpdateAvailable
  "delayedActionTime": 0,         // 无需等待，立即可下载
  "imageURI": "bdx://provider-node-id/firmware-v2.ota",
  "softwareVersion": 2,           // 新固件版本号
  "softwareVersionString": "2.0.0",
  "updateToken": "dXBkYXRlLXRva2VuLXYy", // Base64 编码的更新令牌
  "userConsentNeeded": false,      // 无需用户额外确认
  "metadataForRequestor": null     // 无厂商自定义数据
}

ApplyUpdateRequest 交互示例

Requestor 下载完成，向 Provider 确认是否可以安装：

// Requestor → Provider：下载完成，请求应用更新
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0029",
      "commandId": "0x02"          // ApplyUpdateRequest
    },
    "commandFields": {
      "updateToken": "dXBkYXRlLXRva2VuLXYy",  // QueryImageResponse 中的令牌
      "newVersion": 2              // 即将安装的版本号
    }
  }]
}

// Provider → Requestor：确认继续安装
{
  "action": 0,                     // Proceed（允许安装）
  "delayedActionTime": 0           // 无需等待
}

NotifyUpdateApplied 示例

Requestor 安装成功并重启后，通知 Provider 更新已完成：

// Requestor → Provider：已成功安装并重启
{
  "invokeRequests": [{
    "commandPath": {
      "endpointId": 0,
      "clusterId": "0x0029",
      "commandId": "0x04"          // NotifyUpdateApplied
    },
    "commandFields": {
      "updateToken": "dXBkYXRlLXRva2VuLXYy",  // 原始更新令牌
      "softwareVersion": 2         // 更新后的当前版本号
    }
  }]
}
// 此命令无响应（单向通知）

常见场景