Fixed Label Cluster

Cluster ID: 0x0040 | Endpoint: Endpoint 0 (Root) or functional Endpoints

Fixed Label stores labels (key-value pairs) written to the device at manufacturing time, describing physical attributes or preset categories. These labels are read-only — neither users nor Apps can modify them. Label content is determined by the manufacturer during production, such as preset room, floor, orientation, etc.

Relationship with UserLabel

Fixed Label (0x0040) contains read-only factory labels; UserLabel (0x0041) contains user-writable custom labels. Both share the exact same structure (using LabelStruct); the only difference is who can modify them — Fixed Label is written and locked by the manufacturer at the factory; UserLabel can be modified by users at any time. Apps typically merge both, using factory labels as defaults and user labels as overrides.

Attribute Overview

Fixed Label has only one attribute — very simple.

ID	Name	Type	Access	Description
`0x00`	LabelList	list<LabelStruct>	Read-only	Factory label list (key-value pair array)

LabelList (Factory Label List)

A LabelStruct array where each element is a key-value pair. The list can be empty (device has no preset labels), or contain multiple entries. Label keys should not be duplicated within the same list.

This attribute is read-only; content is fixed after device startup. For writable labels, use the UserLabel Cluster (0x0041).

An Empty List Is Valid

Not all devices have factory labels. Many devices return an empty array [] for LabelList; this is perfectly normal. Apps should handle the empty list case and not assume label data is always present.

↑ Back to Attributes

LabelStruct Structure

LabelStruct is the shared data structure for Fixed Label and UserLabel, defining a label's key and value.

Field	Type	Max Length	Description
`Label`	string	16 chars	Label key, describing what the label means (e.g. "room", "floor")
`Value`	string	16 chars	Label value, the specific content for the key (e.g. "kitchen", "2")

Common Factory Label Examples

room

Room e.g. "kitchen", "bedroom", "living room"

floor

Floor e.g. "1", "2", "B1"

orientation

Orientation e.g. "N", "S", "NE"

position

Position e.g. "left", "right", "top"

zone

Zone e.g. "A", "B", "public"

Label Keys Are Not Strictly Standardized

The Matter specification does not define a fixed list of label keys; the above are just common usages. Manufacturers can use any string as a key, as long as it doesn't exceed 16 characters. Apps should not hardcode dependencies on specific keys; instead, they should gracefully display any key-value pair.

Commands

Fixed Label Cluster has no commands. This is a pure data Cluster — it only provides read-only attributes for Apps to read, accepting no write or action commands. To modify labels, use the UserLabel Cluster (0x0041).

Example Data

Reading Fixed Label attributes of a kitchen sensor device:

{
  // --- Attributes ---
  "0x0": [                    // LabelList — Factory label list
    {
      "Label": "room",        // Label key: room
      "Value": "kitchen"      // Label value: kitchen
    },
    {
      "Label": "floor",       // Label key: floor
      "Value": "2"            // Label value: 2nd floor
    },
    {
      "Label": "orientation", // Label key: orientation
      "Value": "N"            // Label value: north
    }
  ]
}

Usage Scenarios

Scenario 1: Automatically Assign Device to Room

After commissioning, the App reads the device's factory labels. If the labels contain a room key, the App can automatically categorize the device to the corresponding room, saving the user from manual selection.

// Scenario: App reads factory labels and auto-assigns to room
{
  "readRequests": [{
    "attributePath": {
      "endpointId": 0,
      "clusterId": "0x0040",
      "attributeId": "0x00"     // LabelList
    }
  }]
}

// Response
{
  "attributeReports": [{
    "attributeData": {
      "dataVersion": 1,
      "data": [
        { "Label": "room", "Value": "kitchen" },
        { "Label": "floor", "Value": "2" }
      ]
    }
  }]
}

Developer Advice

Automatically read Fixed Label after commissioning. Use known keys (room, floor) for initial grouping suggestions, but always let users confirm or modify. Factory labels are just a reference; the actual installation location may differ.

Scenario 2: Distinguishing Sub-functions in Multi-Endpoint Devices

A dual-switch has two Endpoints, each with Fixed Labels marking the physical position (left/right). After reading labels, the App can directly label them as "Left Switch" and "Right Switch" in the UI, instead of showing meaningless Endpoint numbers.

// Scenario: Multi-Endpoint device, each Endpoint with different factory labels
// Endpoint 1 — Left Switch
{
  "readRequests": [{
    "attributePath": {
      "endpointId": 1,
      "clusterId": "0x0040",
      "attributeId": "0x00"
    }
  }]
}
// Returns: [{ "Label": "position", "Value": "left" }]

// Endpoint 2 — Right Switch
{
  "readRequests": [{
    "attributePath": {
      "endpointId": 2,
      "clusterId": "0x0040",
      "attributeId": "0x00"
    }
  }]
}
// Returns: [{ "Label": "position", "Value": "right" }]

Developer Advice

For multi-Endpoint devices, read Fixed Labels from each Endpoint individually. If a position key exists in the labels, use it to label the sub-device name in the UI, providing users with a more intuitive control interface.