用户标签 Cluster（UserLabel）

Cluster ID: 0x0041  |  所在 Endpoint: 通常在 Endpoint 0（Root）或功能端点  |  角色: Server（可读写，无命令）

UserLabel 允许用户或 App 为设备打上自定义的键值对标签，用于分类、分组、备注等用途。 这是一个极其简单的 Cluster —— 0 个命令、0 个事件， 只有 1 个可写属性 LabelList，通过直接写属性来管理标签。

属性

UserLabel 只有一个属性，且是必须支持的。

LabelList（标签列表）

一个 LabelStruct 的列表，每个元素是一对 Label（键）+ Value（值）字符串。 App 通过 Write Attribute 操作来增删改标签 —— 每次写入都是整体替换， 不是追加。如果想新增一个标签，需要先读取现有列表，追加后再整体写回。

↑ 返回属性列表

LabelStruct 结构体

LabelStruct 是 UserLabel 和 FixedLabel 共用的数据结构，表示一个键值对标签。

示例数据

读取一台智能灯的 UserLabel Cluster 属性：

{
  // --- 属性 ---
  "0x0": [                    // LabelList（标签列表）
    {
      "0": "zone",            // Label = "zone"
      "1": "living-room"      // Value = "living-room"
    },
    {
      "0": "owner",           // Label = "owner"
      "1": "alice"            // Value = "alice"
    },
    {
      "0": "floor",           // Label = "floor"
      "1": "2F"               // Value = "2F"
    }
  ]
}

写入标签（Write Attribute 请求）：

{
  "writeRequests": [{
    "attributePath": {
      "endpointId": 1,
      "clusterId": "0x0041",
      "attributeId": "0x00"       // LabelList
    },
    "data": [
      { "0": "zone",  "1": "living-room" },
      { "0": "owner", "1": "alice" },
      { "0": "floor", "1": "2F" }
    ]
  }]
}

常见场景