UserLabel Cluster

Cluster ID: 0x0041  |  Endpoint: Typically on Endpoint 0 (Root) or functional endpoints  |  Role: Server (read/write, no commands)

UserLabel allows users or Apps to tag devices with custom key-value pair labels for classification, grouping, notes, etc. This is an extremely simple Cluster — 0 commands, 0 events, with only 1 writable attribute LabelList, managing labels through direct attribute writes.

UserLabel vs FixedLabel

Matter has two label Clusters, differing in who can modify them:

  • FixedLabel (0x0040) — Labels written by the manufacturer at factory, read-only, Apps cannot modify. E.g. "room"/"factory-default", "model"/"v2"
  • UserLabel (0x0041) — User-defined labels, read/write, Apps can add/remove/modify at any time. E.g. "zone"/"living-room", "owner"/"alice"

Both share the same data structure (LabelStruct list); they differ only in read/write permissions. When reading device labels, merge results from both Clusters: FixedLabel provides vendor defaults, UserLabel provides user customizations.

Per-Fabric Isolation

UserLabel's labels are per-fabric (isolated by Fabric). Each Fabric can only see and modify its own labels; it cannot access other Fabrics' labels. For example, "zone"/"kitchen" written via Apple Home is not visible on Google Home.

Attributes

UserLabel has only one attribute, which is mandatory.

ID Name Type Access Description
0x00 LabelList list<LabelStruct> Read/Write User-defined label list

LabelList (Label List)

A list of LabelStruct, where each element is a Label (key) + Value (value) string pair. Apps add/remove/modify labels via Write Attribute operations — each write is a full replacement, not an append. To add a new label, first read the existing list, append, then write the entire list back.

No Commands, All Attribute Writes

UserLabel defines no commands. All operations (add, modify, delete labels) are done by writing the LabelList attribute. This is one of the few "purely attribute-driven" Clusters in Matter. Note the full-replacement semantics — omitting an existing label is equivalent to deleting it.

↑ Back to Attributes

LabelStruct Structure

LabelStruct is the shared data structure for UserLabel and FixedLabel, representing a key-value pair label.

Field ID Name Type Constraint Description
0x00 Label string Max 16 chars Label key name, e.g. "zone", "owner"
0x01 Value string Max 16 chars Label value, e.g. "living-room", "alice"
Length Limit

Both Label and Value have a hard limit of max 16 characters. Apps should validate before writing; exceeding the length limit will be rejected by the device (returning CONSTRAINT_ERROR). It is recommended to use short English abbreviations as key names. Values can use characters from any language, but note the character length (Matter counts by characters, not bytes, so 16 characters of any language are allowed).

Example Data

Reading UserLabel Cluster attributes of a smart light:

{
  // --- Attributes ---
  "0x0": [                    // LabelList (label list)
    {
      "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"
    }
  ]
}

Writing labels (Write Attribute request):

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

The write attribute flow is a three-step read → modify → write process:

  1. First Read Attribute to get the current LabelList
  2. Modify the list locally (add / remove / change a label)
  3. Write the complete list back to the device via Write Attribute

Writing a new list without reading first will lose labels previously written by other Apps. If multiple Apps may operate on labels simultaneously, consider adding optimistic locking logic (record version on read, verify before write).

Common Scenarios

Scenario 1: Group Devices by Zone

A user has multiple devices of the same type (e.g. 5 smart light bulbs) and needs to organize them by room, floor, etc. By tagging each device with location labels via UserLabel, the App can display them grouped by label.

  1. After commissioning, guide users to set zone labels for devices
  2. Write labels: {'{"zone": "living-room", "floor": "1F"}'}
  3. App home page groups devices by zone value
  4. After moving a device, users can modify the zone value in the App
  5. Supports custom zone names, not limited to preset lists

Unlike Matter's Groups Cluster, UserLabel is pure metadata tagging and does not affect device group control behavior. Suitable for App-level UI grouping, not device-level coordinated control.

Scenario 2: Device Ownership Tagging in Multi-user Households

A household has multiple members, with some devices belonging to specific members (e.g. children's room light, study desk lamp). By recording ownership information via UserLabel, the App can show different device views for different members.

  1. Write ownership labels for the device: {'{"owner": "alice", "usage": "reading"}'}
  2. App filters by the owner label based on the currently logged-in user's name
  3. The "My Devices" page only shows devices with matching owner
  4. Admin view can still see all devices

Note: UserLabel is per-fabric. If family members use different Fabrics (different brand Apps), their labels are invisible to each other. All Apps under the same Fabric share the same set of labels.