Matter Cluster 8 — Level Control Cluster

Documentation for Matter Cluster 8, including attributes, commands, payload examples, shadow paths, and backend interpretation.

Matter Cluster 8 — Level Control Cluster

Matter Cluster 8, also written as 0x0008, is the Level Control Cluster.

It is used for endpoints that support level-based control.

For lighting devices, Cluster 8 usually represents brightness / dimming level.

For other device types, it may represent another adjustable level.

Cluster Identity

Field	Value
Cluster ID decimal	`8`
Cluster ID hex	`0x0008`
Cluster name	`Level Control`
Full cluster name	`Level Control Cluster`
Matter version	`1.5`
Cluster revision	`6`
Scope	`Endpoint`
Role	`Application`
Hierarchy	`Base`
PICS code	`LVL`

Shadow Path Format

Cluster 8 values in the device shadow usually use this format:

endpoint_id / cluster_id / attribute_id

For Cluster 8:

endpoint_id / 8 / attribute_id

Example:

{
  "1/8/0": 113
}

Meaning:

Part	Meaning
`1`	Endpoint ID
`8`	Level Control Cluster
`0`	CurrentLevel attribute
`113`	Current level value

Main State Attribute

Attribute `0` — `CurrentLevel`

Path example:

1/8/0

This attribute stores the current level of the endpoint.

For a dimmable light, this usually means current brightness level.

Value	Meaning
`0`	Lowest level / OFF-related level depending on device behavior
`1`	Minimum lighting level for many Matter lighting devices
`254`	Maximum standard level
`null`	Current level is unknown or unavailable

Example:

{
  "1/8/0": 113
}

Meaning:

Endpoint 1 current level is 113.

Recommended UI mapping for brightness:

brightness_percent = round(CurrentLevel / 254 * 100)

Example:

113 / 254 * 100 = 44.5%

Recommended UI value:

45%

Important:

CurrentLevel is not the same thing as ON/OFF state.

Use Cluster 6 together with Cluster 8:

1/6/0 = OnOff state
1/8/0 = Current level / brightness

Cluster 8 Features

Cluster 8 can expose feature bits through the global FeatureMap attribute.

FeatureMap path:

endpoint_id / 8 / 65532

Example:

{
  "1/8/65532": 3
}

Meaning:

Feature bits 0 and 1 are enabled.

Feature Bits

Bit	Code	Name	Description
`0`	`OO`	`OnOff`	Dependency with the On/Off cluster
`1`	`LT`	`Lighting`	Behavior that supports lighting applications
`2`	`FQ`	`Frequency`	Supports frequency attributes and behavior

Common FeatureMap Values

FeatureMap value	Enabled features	Meaning
`0`	none	Basic level control
`1`	`OO`	Level control depends on On/Off cluster
`2`	`LT`	Lighting behavior
`3`	`OO + LT`	Common dimmable light behavior
`4`	`FQ`	Frequency-capable device

Most dimmable Matter lights usually support:

OO + LT

That usually means:

{
  "1/8/65532": 3
}

Data Types

`MoveModeEnum`

Used by:

Move
MoveWithOnOff

Value	Name	Description
`0`	`Up`	Increase the level
`1`	`Down`	Decrease the level

`StepModeEnum`

Used by:

Step
StepWithOnOff

Value	Name	Description
`0`	`Up`	Step level upward
`1`	`Down`	Step level downward

`OptionsBitmap`

Used by:

Options attribute
OptionsMask command field
OptionsOverride command field

Bit	Name	Description
`0`	`ExecuteIfOff`	Allows level commands to execute when the endpoint is OFF
`1`	`CoupleColorTempToLevel`	Couples color temperature behavior to level changes

Main Level Attributes

Attribute `0` / `0x0000` — `CurrentLevel`

Path example:

1/8/0

Description:

Current level of the endpoint.

For lighting:

CurrentLevel usually means brightness.

Value range:

MinLevel <= CurrentLevel <= MaxLevel

Typical lighting range:

1..254

Example:

{
  "1/8/0": 113
}

Meaning:

Endpoint 1 brightness level is 113.

Recommended UI mapping:

113 -> about 45%

Attribute `1` / `0x0001` — `RemainingTime`

Path example:

1/8/1

Description:

Remaining transition time while the endpoint is moving from one level to another.

This is mainly useful when a command uses non-zero transition time.

Example command:

{
  "level": 200,
  "transitionTime": 50
}

Meaning:

Move to level 200 over a transition period.

During transition, the device may report:

{
  "1/8/1": 30
}

Meaning:

There is still transition time remaining.

For instant transitions:

{
  "transitionTime": 0
}

RemainingTime is usually 0 or not important.

Attribute `2` / `0x0002` — `MinLevel`

Path example:

1/8/2

Description:

Minimum supported level for this endpoint.

For lighting devices, this is commonly:

For non-lighting level-control devices, it can be:

Example:

{
  "1/8/2": 1
}

Meaning:

Endpoint 1 minimum supported level is 1.

Important practical behavior:

Some lights do not report CurrentLevel = 0.
They may turn OFF through Cluster 6 but keep CurrentLevel at MinLevel = 1.

Example:

{
  "1/6/0": false,
  "1/8/0": 1
}

Meaning:

Light is OFF.
Stored/current brightness level is minimum level 1.

This is normal behavior for many Matter lights.

Attribute `3` / `0x0003` — `MaxLevel`

Path example:

1/8/3

Description:

Maximum supported level for this endpoint.

Default / common value:

Example:

{
  "1/8/3": 254
}

Meaning:

Endpoint 1 maximum level is 254.

Recommended UI mapping:

CurrentLevel / MaxLevel * 100

Example:

127 / 254 * 100 = 50%

Frequency Attributes

Frequency attributes are used only when the FQ feature is supported.

Most regular dimmable lights do not use these attributes.

Attribute `4` / `0x0004` — `CurrentFrequency`

Path example:

1/8/4

Description:

Current frequency value of a frequency-capable endpoint.

Only used when FeatureMap includes:

FQ

Example:

{
  "1/8/4": 60
}

Meaning:

Current frequency is 60.

Attribute `5` / `0x0005` — `MinFrequency`

Path example:

1/8/5

Description:

Minimum supported frequency value.

Only used when FeatureMap includes:

FQ

Example:

{
  "1/8/5": 20
}

Meaning:

Minimum supported frequency is 20.

Attribute `6` / `0x0006` — `MaxFrequency`

Path example:

1/8/6

Description:

Maximum supported frequency value.

Only used when FeatureMap includes:

FQ

Example:

{
  "1/8/6": 100
}

Meaning:

Maximum supported frequency is 100.

Options Attribute

Attribute `15` / `0x000F` — `Options`

Path example:

1/8/15

Description:

Default options controlling how Level Control commands behave.

Options is a bitmap.

Bit	Name	Description
`0`	`ExecuteIfOff`	Allows level commands to execute while endpoint is OFF
`1`	`CoupleColorTempToLevel`	Couples color temperature to level changes

Example:

{
  "1/8/15": 1
}

Meaning:

ExecuteIfOff is enabled.

Example:

{
  "1/8/15": 0
}

Meaning:

No option bits are enabled.

Command-level override fields:

OptionsMask
OptionsOverride

These allow one command to override the default Options behavior.

For most simple bridge commands, use:

{
  "optionsMask": 0,
  "optionsOverride": 0
}

Or omit them if python-matter-server accepts defaults.

On/Off Related Level Attributes

These attributes are normally useful for lighting devices and endpoints that combine Cluster 8 with Cluster 6.

Attribute `16` / `0x0010` — `OnOffTransitionTime`

Path example:

1/8/16

Description:

Default transition time used when changing between ON and OFF level states.

Example:

{
  "1/8/16": 0
}

Meaning:

Use immediate transition.

Attribute `17` / `0x0011` — `OnLevel`

Path example:

1/8/17

Description:

Level value used when the endpoint is turned ON.

Example:

{
  "1/8/17": 113
}

Meaning:

When endpoint turns ON, it should use level 113.

If OnLevel is null:

{
  "1/8/17": null
}

Meaning:

Device may restore previous level or use its own default.

Attribute `18` / `0x0012` — `OnTransitionTime`

Path example:

1/8/18

Description:

Transition time used when moving to ON level.

Example:

{
  "1/8/18": 20
}

Meaning:

Use transition time 20 when turning ON.

If value is null:

{
  "1/8/18": null
}

Meaning:

No specific ON transition time is configured.

Attribute `19` / `0x0013` — `OffTransitionTime`

Path example:

1/8/19

Description:

Transition time used when moving to OFF.

Example:

{
  "1/8/19": 20
}

Meaning:

Use transition time 20 when turning OFF.

If value is null:

{
  "1/8/19": null
}

Meaning:

No specific OFF transition time is configured.

Attribute `20` / `0x0014` — `DefaultMoveRate`

Path example:

1/8/20

Description:

Default rate used for Move commands when no command-specific rate is provided.

Example:

{
  "1/8/20": 10
}

Meaning:

Default continuous move rate is 10.

This is related to commands like:

Move
MoveWithOnOff

Startup Attribute

Attribute `16384` / `0x4000` — `StartUpCurrentLevel`

Path example:

1/8/16384

Description:

Defines what CurrentLevel should be after power cycle, reboot, or restart.

Usually used by lighting devices.

Example:

{
  "1/8/16384": 254
}

Meaning:

After startup, endpoint should restore level 254.

Example:

{
  "1/8/16384": 113
}

Meaning:

After startup, endpoint should restore level 113.

Example:

{
  "1/8/16384": null
}

Meaning:

Device uses its own startup/default behavior.

Cluster 8 Commands

Cluster 8 has 9 standard Matter commands.

Decimal ID	Hex ID	Command name	Description
`0`	`0x00`	`MoveToLevel`	Move to a specific level
`1`	`0x01`	`Move`	Move level continuously up or down
`2`	`0x02`	`Step`	Change level by a fixed step
`3`	`0x03`	`Stop`	Stop an active level movement
`4`	`0x04`	`MoveToLevelWithOnOff`	Move to level and update On/Off state
`5`	`0x05`	`MoveWithOnOff`	Move continuously and update On/Off behavior
`6`	`0x06`	`StepWithOnOff`	Step level and update On/Off behavior
`7`	`0x07`	`StopWithOnOff`	Stop movement with On/Off behavior
`8`	`0x08`	`MoveToClosestFrequency`	Move to closest supported frequency

AcceptedCommandList

Cluster 8 exposes a metadata attribute called AcceptedCommandList.

In the shadow, it appears as:

endpoint_id / 8 / 65529

Example:

{
  "1/8/65529": [0, 1, 2, 3, 4, 5, 6, 7]
}

This means endpoint 1 supports the common Level Control commands except frequency command 8.

Example with frequency support:

{
  "1/8/65529": [0, 1, 2, 3, 4, 5, 6, 7, 8]
}

This means endpoint 1 supports all standard Cluster 8 commands, including MoveToClosestFrequency.

ID	Command
`0`	`MoveToLevel`
`1`	`Move`
`2`	`Step`
`3`	`Stop`
`4`	`MoveToLevelWithOnOff`
`5`	`MoveWithOnOff`
`6`	`StepWithOnOff`
`7`	`StopWithOnOff`
`8`	`MoveToClosestFrequency`

Before sending a Cluster 8 command, check that the command ID exists in:

endpoint/8/65529

Bridge Command Payload Format

Your bridge uses this structure:

{
  "message_id": "501",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "MoveToLevelWithOnOff",
    "payload": {
      "level": 113,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

For Cluster 8, always use:

{
  "cluster_id": 8
}

For direct Matter devices, use:

{
  "endpoint_id": 1,
  "cluster_id": 8,
  "command_name": "MoveToLevelWithOnOff",
  "payload": {
    "level": 113,
    "transitionTime": 0
  }
}

For bridged Zigbee devices through your Matter bridge, the backend may omit node_id and sometimes omit endpoint_id depending on how the MatterBridge resolves the device.

Command: `MoveToLevel`

Purpose

Moves the endpoint to a specific level.

This command changes the level but does not necessarily update the On/Off state.

For user-facing light brightness control, MoveToLevelWithOnOff is usually better.

Command Identity

Field	Value
Command ID	`0`
Command hex	`0x00`
Command name	`MoveToLevel`

Payload Fields

Field	Description
`level`	Target level, usually `0..254`
`transitionTime`	Time used to move to target level
`optionsMask`	Selects which option bits to override
`optionsOverride`	Override values for selected option bits

Bridge Command Example

{
  "message_id": "801",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "MoveToLevel",
    "payload": {
      "level": 113,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

Expected State

{
  "1/8/0": 113
}

Important:

This command may not turn the light ON if the endpoint is currently OFF.

Use MoveToLevelWithOnOff if ON/OFF state should follow the level.

Command: `Move`

Purpose

Starts moving the level continuously up or down.

The movement continues until the endpoint reaches the minimum/maximum level or receives a stop command.

Command Identity

Field	Value
Command ID	`1`
Command hex	`0x01`
Command name	`Move`

Payload Fields

Field	Description
`moveMode`	Direction: `0` = Up, `1` = Down
`rate`	Rate of level movement
`optionsMask`	Selects which option bits to override
`optionsOverride`	Override values for selected option bits

Move Modes

Value	Name	Description
`0`	`Up`	Increase the level
`1`	`Down`	Decrease the level

Bridge Command Example: Move Up

{
  "message_id": "802",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "Move",
    "payload": {
      "moveMode": 0,
      "rate": 10
    },
    "timed_request_timeout_ms": 1000
  }
}

Bridge Command Example: Move Down

{
  "message_id": "803",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "Move",
    "payload": {
      "moveMode": 1,
      "rate": 10
    },
    "timed_request_timeout_ms": 1000
  }
}

Expected State

While moving, the device should report changing level values:

{
  "1/8/0": 120
}

Then:

{
  "1/8/0": 130
}

To stop movement, send:

Stop

Command: `Step`

Purpose

Changes the endpoint level by a fixed step amount.

This is useful for brightness up / brightness down buttons.

Command Identity

Field	Value
Command ID	`2`
Command hex	`0x02`
Command name	`Step`

Payload Fields

Field	Description
`stepMode`	Direction: `0` = Up, `1` = Down
`stepSize`	Amount to increase or decrease
`transitionTime`	Time used for this step
`optionsMask`	Selects which option bits to override
`optionsOverride`	Override values for selected option bits

Step Modes

Value	Name	Description
`0`	`Up`	Increase level by `stepSize`
`1`	`Down`	Decrease level by `stepSize`

Bridge Command Example: Step Up

{
  "message_id": "804",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "Step",
    "payload": {
      "stepMode": 0,
      "stepSize": 20,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

If current level is:

{
  "1/8/0": 113
}

Expected new level:

{
  "1/8/0": 133
}

Bridge Command Example: Step Down

{
  "message_id": "805",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "Step",
    "payload": {
      "stepMode": 1,
      "stepSize": 20,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

If current level is:

{
  "1/8/0": 113
}

Expected new level:

{
  "1/8/0": 93
}

Command: `Stop`

Purpose

Stops an active level movement.

This is usually used after Move.

Command Identity

Field	Value
Command ID	`3`
Command hex	`0x03`
Command name	`Stop`

Payload Fields

Field	Description
`optionsMask`	Selects which option bits to override
`optionsOverride`	Override values for selected option bits

Bridge Command Example

{
  "message_id": "806",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "Stop",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

Expected State

The level remains at the current value when movement stops.

Example:

{
  "1/8/0": 147
}

Command: `MoveToLevelWithOnOff`

Purpose

Moves the endpoint to a specific level and updates the On/Off state.

This is the recommended command for user-facing dimmable light control.

Command Identity

Field	Value
Command ID	`4`
Command hex	`0x04`
Command name	`MoveToLevelWithOnOff`

Payload Fields

This command uses the same base payload behavior as MoveToLevel.

Field	Description
`level`	Target level, usually `0..254`
`transitionTime`	Time used to move to target level
`optionsMask`	Optional options mask if supported by bridge/server
`optionsOverride`	Optional options override if supported by bridge/server

Bridge Command Example: Turn OFF by Level

{
  "message_id": "807",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "MoveToLevelWithOnOff",
    "payload": {
      "level": 0,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

Expected State

{
  "1/6/0": false
}

Cluster 8 may report:

{
  "1/8/0": 0
}

or:

{
  "1/8/0": 1
}

Both can be normal depending on MinLevel and device behavior.

Bridge Command Example: Turn ON to 45%

{
  "message_id": "808",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "MoveToLevelWithOnOff",
    "payload": {
      "level": 113,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

Expected State

{
  "1/6/0": true,
  "1/8/0": 113
}

Meaning:

Endpoint is ON.
Brightness level is 113.
Approximate UI brightness is 45%.

Command: `MoveWithOnOff`

Purpose

Starts moving the level continuously and updates On/Off behavior.

Use this when a brightness button is pressed and held.

Command Identity

Field	Value
Command ID	`5`
Command hex	`0x05`
Command name	`MoveWithOnOff`

Payload Fields

This command uses the same base payload behavior as Move.

Field	Description
`moveMode`	Direction: `0` = Up, `1` = Down
`rate`	Rate of level movement
`optionsMask`	Optional options mask
`optionsOverride`	Optional options override

Bridge Command Example: Hold Brightness Up

{
  "message_id": "809",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "MoveWithOnOff",
    "payload": {
      "moveMode": 0,
      "rate": 10
    },
    "timed_request_timeout_ms": 1000
  }
}

Bridge Command Example: Hold Brightness Down

{
  "message_id": "810",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "MoveWithOnOff",
    "payload": {
      "moveMode": 1,
      "rate": 10
    },
    "timed_request_timeout_ms": 1000
  }
}

Expected State

The endpoint reports changing values:

{
  "1/8/0": 140
}

When moving up, the endpoint should usually be ON:

{
  "1/6/0": true
}

Command: `StepWithOnOff`

Purpose

Changes level by a fixed step and updates On/Off behavior.

This is recommended for brightness up/down buttons.

Command Identity

Field	Value
Command ID	`6`
Command hex	`0x06`
Command name	`StepWithOnOff`

Payload Fields

This command uses the same base payload behavior as Step.

Field	Description
`stepMode`	Direction: `0` = Up, `1` = Down
`stepSize`	Amount to increase or decrease
`transitionTime`	Time used for the step
`optionsMask`	Optional options mask
`optionsOverride`	Optional options override

Bridge Command Example: Brightness Up

{
  "message_id": "811",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "StepWithOnOff",
    "payload": {
      "stepMode": 0,
      "stepSize": 25,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

Bridge Command Example: Brightness Down

{
  "message_id": "812",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "StepWithOnOff",
    "payload": {
      "stepMode": 1,
      "stepSize": 25,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

Expected State

Example before:

{
  "1/6/0": true,
  "1/8/0": 113
}

After StepWithOnOff up by 25:

{
  "1/6/0": true,
  "1/8/0": 138
}

After StepWithOnOff down by 25:

{
  "1/6/0": true,
  "1/8/0": 88
}

If stepping down reaches the minimum/off behavior, the endpoint may report:

{
  "1/6/0": false,
  "1/8/0": 1
}

Command: `StopWithOnOff`

Purpose

Stops active level movement while preserving On/Off-coupled behavior.

Usually used after MoveWithOnOff.

Command Identity

Field	Value
Command ID	`7`
Command hex	`0x07`
Command name	`StopWithOnOff`

Payload Fields

This command uses the same base payload behavior as Stop.

Field	Description
`optionsMask`	Optional options mask
`optionsOverride`	Optional options override

Bridge Command Example

{
  "message_id": "813",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "StopWithOnOff",
    "payload": {},
    "timed_request_timeout_ms": 1000
  }
}

Expected State

The endpoint stops at the current level.

Example:

{
  "1/6/0": true,
  "1/8/0": 147
}

Command: `MoveToClosestFrequency`

Purpose

Moves the endpoint to the closest supported frequency.

This command is only used when the endpoint supports the FQ feature.

Most standard dimmable lights do not support this command.

Command Identity

Field	Value
Command ID	`8`
Command hex	`0x08`
Command name	`MoveToClosestFrequency`

Payload Fields

Field	Description
`frequency`	Requested target frequency

Bridge Command Example

{
  "message_id": "814",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "MoveToClosestFrequency",
    "payload": {
      "frequency": 60
    },
    "timed_request_timeout_ms": 1000
  }
}

Expected State

If supported, endpoint may report:

{
  "1/8/4": 60
}

Meaning:

CurrentFrequency is 60.

If the exact requested frequency is not supported, the device should move to the closest supported value.

Other Cluster 8 Attributes

Attribute `65528` / `0xFFF8` — `GeneratedCommandList`

Path example:

1/8/65528

Description:

Commands this cluster may generate/send.

Example:

{
  "1/8/65528": []
}

Attribute `65529` / `0xFFF9` — `AcceptedCommandList`

Path example:

1/8/65529

Description:

Commands this cluster accepts.

Example:

{
  "1/8/65529": [0, 1, 2, 3, 4, 5, 6, 7]
}

Meaning:

Endpoint 1 accepts standard Level Control commands except frequency command.

Attribute `65531` / `0xFFFB` — `AttributeList`

Path example:

1/8/65531

Description:

Attributes available on this cluster for this endpoint.

Example:

{
  "1/8/65531": [0, 1, 2, 3, 15, 17, 65528, 65529, 65531, 65532, 65533]
}

Meaning:

Endpoint 1 exposes CurrentLevel, RemainingTime, MinLevel, MaxLevel, Options, OnLevel, and global metadata attributes.

Attribute `65532` / `0xFFFC` — `FeatureMap`

Path example:

1/8/65532

Description:

Enabled feature bits for Cluster 8.

Example:

{
  "1/8/65532": 3
}

Meaning:

OO + LT features are enabled.

Feature bits:

Bit	Code	Name
`0`	`OO`	`OnOff`
`1`	`LT`	`Lighting`
`2`	`FQ`	`Frequency`

Attribute `65533` / `0xFFFD` — `ClusterRevision`

Path example:

1/8/65533

Description:

Cluster revision/version.

For Matter 1.5 Level Control:

{
  "1/8/65533": 6
}

Meaning:

Endpoint 1 implements Level Control cluster revision 6.

Backend Interpretation

Recommended State Mapping

When shadow contains:

{
  "1/6/0": true,
  "1/8/0": 113
}

Backend/UI should interpret:

Device is ON.
Brightness level is 113.
Brightness percent is about 45%.

Recommended normalized state:

{
  "available": true,
  "on": true,
  "level": 113,
  "brightness": 45
}

OFF State with Stored Level

When shadow contains:

{
  "1/6/0": false,
  "1/8/0": 113
}

Backend/UI should interpret:

Device is OFF.
Previous/stored brightness level is 113.

Recommended normalized state:

{
  "available": true,
  "on": false,
  "level": 113,
  "brightness": 45
}

UI should show:

OFF

not:

45% ON

because Cluster 6 OnOff state is false.

OFF State with Minimum Level

When shadow contains:

{
  "1/6/0": false,
  "1/8/0": 1
}

Backend/UI should interpret:

Device is OFF.
Level value is at minimum level.

Recommended normalized state:

{
  "available": true,
  "on": false,
  "level": 1,
  "brightness": 0
}

For UI, when 1/6/0 is false, show brightness as OFF even if 1/8/0 is 1.

Practical Examples From MatterBridge Logs

Example command:

{
  "cluster_id": 8,
  "command_name": "MoveToLevelWithOnOff",
  "payload": {
    "level": 0,
    "transitionTime": 0
  }
}

Expected Matter attribute updates:

{
  "1/6/0": false,
  "1/8/0": 1
}

Meaning:

Endpoint turned OFF.
CurrentLevel reported as minimum level 1.

Example command:

{
  "cluster_id": 8,
  "command_name": "MoveToLevelWithOnOff",
  "payload": {
    "level": 113,
    "transitionTime": 0
  }
}

Expected Matter attribute updates:

{
  "1/6/0": true,
  "1/8/0": 113
}

Meaning:

Endpoint turned ON.
Brightness level changed to 113.

Recommended UI Rules

Rule 1 — Use Cluster 6 for ON/OFF

endpoint/6/0

Values:

true  = ON
false = OFF

Rule 2 — Use Cluster 8 for Brightness / Level

endpoint/8/0

Values:

0..254

Rule 3 — Convert Level to Percent

Recommended formula:

brightness_percent = round(CurrentLevel / 254 * 100)

Examples:

CurrentLevel	Approx UI brightness
`1`	`0%` or minimum
`64`	`25%`
`113`	`45%`
`127`	`50%`
`191`	`75%`
`254`	`100%`

Rule 4 — OFF Overrides Brightness Display

If:

{
  "1/6/0": false,
  "1/8/0": 113
}

UI should show:

OFF

Brightness level can still be stored internally as:

Recommended Commands for UI

Turn OFF

Use:

{
  "message_id": "901",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "MoveToLevelWithOnOff",
    "payload": {
      "level": 0,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

Expected final state:

{
  "1/6/0": false
}

Turn ON to Brightness

Use:

{
  "message_id": "902",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "MoveToLevelWithOnOff",
    "payload": {
      "level": 113,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

Expected final state:

{
  "1/6/0": true,
  "1/8/0": 113
}

Brightness Slider

When user moves slider to 45%:

level = round(45 / 100 * 254)
level = 114

Send:

{
  "message_id": "903",
  "command": "device_command",
  "args": {
    "endpoint_id": 1,
    "cluster_id": 8,
    "command_name": "MoveToLevelWithOnOff",
    "payload": {
      "level": 114,
      "transitionTime": 0
    },
    "timed_request_timeout_ms": 1000
  }
}

Expected state:

{
  "1/6/0": true,
  "1/8/0": 114
}

Cluster 8 Metadata Attributes

These are global Matter metadata attributes for Cluster 8.

They describe the cluster itself.

Attribute ID	Name	Description
`65528`	`GeneratedCommandList`	Commands this cluster may generate/send
`65529`	`AcceptedCommandList`	Commands this cluster accepts
`65531`	`AttributeList`	Attributes available on this cluster
`65532`	`FeatureMap`	Enabled feature bits
`65533`	`ClusterRevision`	Cluster revision/version

Example:

{
  "1/8/65529": [0, 1, 2, 3, 4, 5, 6, 7]
}

Meaning:

Endpoint 1 accepts common Level Control commands.

Example:

{
  "1/8/65532": 3
}

Meaning:

Endpoint 1 supports OnOff + Lighting features.

Example:

{
  "1/8/65533": 6
}

Meaning:

Endpoint 1 implements Cluster 8 revision 6.

Final Summary

Cluster 8 is the Matter Level Control Cluster.

Main state:

endpoint/8/0

Main meaning:

CurrentLevel / brightness / dimming level

Common level range:

0..254

For most lighting devices:

1   = minimum level
254 = maximum level

Most important command:

MoveToLevelWithOnOff

Recommended command for brightness control:

{
  "cluster_id": 8,
  "command_name": "MoveToLevelWithOnOff",
  "payload": {
    "level": 113,
    "transitionTime": 0
  }
}

Supported command list:

endpoint/8/65529

All standard Cluster 8 commands:

0 = MoveToLevel
1 = Move
2 = Step
3 = Stop
4 = MoveToLevelWithOnOff
5 = MoveWithOnOff
6 = StepWithOnOff
7 = StopWithOnOff
8 = MoveToClosestFrequency

If the shadow has:

{
  "1/8/65529": [0, 1, 2, 3, 4, 5, 6, 7]
}

Then endpoint 1 supports common Level Control commands.

If the shadow has:

{
  "1/8/65529": [0, 1, 2, 3, 4, 5, 6, 7, 8]
}

Then endpoint 1 supports all standard Cluster 8 commands, including frequency control.

For UI, always combine:

endpoint/6/0 = ON/OFF state
endpoint/8/0 = brightness/level state

Recommended interpretation:

If endpoint/6/0 is false, show OFF.
If endpoint/6/0 is true, show brightness from endpoint/8/0.

FilesExpand file tree

matter_cluster_8_level_control.mdx

Latest commit

History

matter_cluster_8_level_control.mdx

File metadata and controls

Matter Cluster 8 — Level Control Cluster

Matter Cluster 8 — Level Control Cluster

Cluster Identity

Shadow Path Format

Main State Attribute

Attribute 0 — CurrentLevel

Cluster 8 Features

Feature Bits

Common FeatureMap Values

Data Types

MoveModeEnum

StepModeEnum

OptionsBitmap

Main Level Attributes

Attribute 0 / 0x0000 — CurrentLevel

Attribute 1 / 0x0001 — RemainingTime

Attribute 2 / 0x0002 — MinLevel

Attribute 3 / 0x0003 — MaxLevel

Frequency Attributes

Attribute 4 / 0x0004 — CurrentFrequency

Attribute 5 / 0x0005 — MinFrequency

Attribute 6 / 0x0006 — MaxFrequency

Options Attribute

Attribute 15 / 0x000F — Options

On/Off Related Level Attributes

Attribute 16 / 0x0010 — OnOffTransitionTime

Attribute 17 / 0x0011 — OnLevel

Attribute 18 / 0x0012 — OnTransitionTime

Attribute 19 / 0x0013 — OffTransitionTime

Attribute 20 / 0x0014 — DefaultMoveRate

Startup Attribute

Attribute 16384 / 0x4000 — StartUpCurrentLevel

Cluster 8 Commands

AcceptedCommandList

Bridge Command Payload Format

Command: MoveToLevel

Purpose

Command Identity

Payload Fields

Bridge Command Example

Expected State

Command: Move

Purpose

Command Identity

Payload Fields

Move Modes

Bridge Command Example: Move Up

Bridge Command Example: Move Down

Expected State

Command: Step

Purpose

Command Identity

Payload Fields

Step Modes

Bridge Command Example: Step Up

Bridge Command Example: Step Down

Command: Stop

Purpose

Command Identity

Payload Fields

Bridge Command Example

Expected State

Command: MoveToLevelWithOnOff

Purpose

Command Identity

Payload Fields

Bridge Command Example: Turn OFF by Level

Expected State

Bridge Command Example: Turn ON to 45%

Expected State

Command: MoveWithOnOff

Purpose

Command Identity

Payload Fields

Attribute `0` — `CurrentLevel`

`MoveModeEnum`

`StepModeEnum`

`OptionsBitmap`

Attribute `0` / `0x0000` — `CurrentLevel`

Attribute `1` / `0x0001` — `RemainingTime`

Attribute `2` / `0x0002` — `MinLevel`

Attribute `3` / `0x0003` — `MaxLevel`

Attribute `4` / `0x0004` — `CurrentFrequency`

Attribute `5` / `0x0005` — `MinFrequency`

Attribute `6` / `0x0006` — `MaxFrequency`

Attribute `15` / `0x000F` — `Options`

Attribute `16` / `0x0010` — `OnOffTransitionTime`

Attribute `17` / `0x0011` — `OnLevel`

Attribute `18` / `0x0012` — `OnTransitionTime`

Attribute `19` / `0x0013` — `OffTransitionTime`

Attribute `20` / `0x0014` — `DefaultMoveRate`

Attribute `16384` / `0x4000` — `StartUpCurrentLevel`

Command: `MoveToLevel`

Command: `Move`

Command: `Step`

Command: `Stop`

Command: `MoveToLevelWithOnOff`

Command: `MoveWithOnOff`

Command: `StepWithOnOff`

Command: `StopWithOnOff`

Command: `MoveToClosestFrequency`

Attribute `65528` / `0xFFF8` — `GeneratedCommandList`

Attribute `65529` / `0xFFF9` — `AcceptedCommandList`

Attribute `65531` / `0xFFFB` — `AttributeList`

Attribute `65532` / `0xFFFC` — `FeatureMap`

Attribute `65533` / `0xFFFD` — `ClusterRevision`