OTA 更新请求者 Cluster（OtaSoftwareUpdateRequestor）

Cluster ID: 0x002A  |  所在 Endpoint: Endpoint 0（Root Endpoint） |  角色: Server（设备作为 OTA 客户端）

OtaSoftwareUpdateRequestor 是 Matter OTA 升级体系中的客户端侧 —— 即需要被升级的设备。 它负责向 OTA Provider（升级提供者，对应 Cluster 0x0029）查询是否有新版本、下载固件、应用更新。 所有支持 OTA 的 Matter 设备都必须实现这个 Cluster。

命令（Commands）

OtaSoftwareUpdateRequestor 只有 1 个命令。它不是由设备自己发起的，而是由外部节点 （通常是 OTA Provider 或管理节点）发送给设备，告知设备可以去某个 Provider 查询更新。

AnnounceOTAProvider —— 通告 OTA 提供者（0x00）

外部节点通过此命令告知设备：「有一个 OTA Provider 可以为你提供更新」。 收到此命令后，设备应尽快向指定的 Provider 发起更新查询（调用 Provider 的 QueryImage 命令）。 这是推送式 OTA 的核心触发机制 —— 让设备不必一直轮询，而是被动通知后再查询。

↑ 返回命令列表

属性详解

OtaSoftwareUpdateRequestor 有 4 个应用属性，分为「Provider 配置」和「更新状态」两组。

Provider 配置（0x0000）

配置设备应该向哪些 OTA Provider 查询更新。每个 Fabric 最多配置一个 Provider。

ProviderLocation 结构体

↑ 返回属性列表

更新状态（0x0001 - 0x0003）

反映设备当前的 OTA 更新状态。这些属性均为只读，App 端通过订阅这些属性来跟踪更新进度。

↑ 返回属性列表

枚举速查

UpdateStateEnum —— 更新状态

描述设备 OTA 状态机的完整生命周期，共 9 个状态：

AnnouncementReasonEnum —— 通告原因

AnnounceOTAProvider 命令中使用，告知设备此次通告的原因：

ChangeReasonEnum —— 状态变更原因

在 StateTransition 事件中使用，说明状态机发生状态转移的原因：

事件（Events）

OtaSoftwareUpdateRequestor 定义了 3 个事件，覆盖了 OTA 生命周期的关键节点。 订阅这些事件可以实时跟踪设备的更新流程，比轮询属性更及时。

StateTransition —— 状态转移事件（0x00）

每当 OTA 状态机从一个状态转移到另一个状态时触发。这是追踪更新流程最核心的事件 —— 通过监听它可以知道设备从空闲到查询、从下载到应用的每一步。

事件上报示例 —— 从 Idle 转入 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（查询成功，开始下载）
        "3": 5                     // TargetSoftwareVersion = 5
      }
    }
  }]
}

↑ 返回事件列表

VersionApplied —— 版本已应用事件（0x01）

新固件版本成功应用后触发（通常在设备重启后上报）。这个事件是确认「更新真正完成」的标志。 优先级为 Critical，确保即使在事件队列满时也不会被丢弃。

事件上报示例：

{
  "eventReports": [{
    "eventData": {
      "path": {
        "endpointId": 0,
        "clusterId": "0x002A",
        "eventId": "0x01"          // VersionApplied
      },
      "eventNumber": 18,
      "priority": "CRITICAL",
      "data": {
        "0": 5,                    // SoftwareVersion = 5（刚刚应用的版本号）
        "1": 4                     // ProductID = 4（产品 ID）
      }
    }
  }]
}

↑ 返回事件列表

DownloadError —— 下载错误事件（0x02）

固件下载过程中遇到错误时触发。此事件提供了出错时的上下文信息（已下载量、进度等）， 有助于诊断网络问题或 Provider 端故障。

事件上报示例 —— 下载到 75% 时出错：

{
  "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（下载到 75% 时出错）
        "3": -1                    // PlatformCode = -1（平台错误码，nullable）
      }
    }
  }]
}

↑ 返回事件列表

示例数据

一个处于空闲状态的设备的 OtaSoftwareUpdateRequestor Cluster 属性读取结果：

{
  // --- 默认 OTA 提供者 ---
  "0x0000": [                     // DefaultOTAProviders（可配置多个）
    {
      "providerNodeID": 12345,    // Provider 的 Node ID
      "endpoint": 0,              // Provider 上 OTA Provider Cluster 所在的 Endpoint
      "fabricIndex": 1            // 所属 Fabric 索引
    }
  ],

  // --- 更新能力 ---
  "0x0001": true,                 // UpdatePossible = true（设备当前可以接受更新）

  // --- 更新状态 ---
  "0x0002": 0,                    // UpdateState = Idle（当前空闲，未在更新流程中）
  "0x0003": null                  // UpdateStateProgress = null（无进度信息）
}

常见场景