LevelControl Cluster

Cluster ID: 0x0008  |  Endpoint: Typically on Endpoint 1 (application endpoint)

LevelControl provides full control over a device's adjustable level -- the most typical use case is light dimming, but it also applies to fan speed, curtain position, or any device whose "degree" can be represented numerically. It defines two groups of commands: one group does not affect the OnOff state, while the other group coordinates with the OnOff Cluster's on/off state.

Commands

LevelControl provides two groups of commands: the basic group (0x00~0x03) and the WithOnOff group (0x04~0x07). Both groups share the same parameters; the difference is that the WithOnOff group coordinates with the OnOff Cluster's on/off state. There is also a frequency control command (0x08), available only when the device supports the Frequency feature.

MoveToLevel (0x00)

Smoothly transitions CurrentLevel from its current value to a specified target level. This is the most commonly used command -- it is what gets sent when the user releases the brightness slider in the app. Does not affect the OnOff state; even if the target level is 0, it will not turn off the light.

↑ Back to Commands

Move (0x01)

Continuously changes CurrentLevel up or down at a specified rate until it reaches MinLevel/MaxLevel or a Stop command is received. Ideal for long-press dimming scenarios.

↑ Back to Commands

Step (0x02)

Adjusts CurrentLevel up or down by a specified step value. Ideal for short-press "one step brighter" or "one step dimmer" interactions.

↑ Back to Commands

Stop (0x03)

Stops an ongoing Move or Step transition. CurrentLevel remains at the value it held when the Stop command was received.

↑ Back to Commands

MoveToLevelWithOnOff (0x04)

Functions identically to MoveToLevel, except it also coordinates with the OnOff Cluster: the light automatically turns off (OnOff becomes Off) when the target level is 0, and turns on (OnOff becomes On) when the target level is above 0. This is the preferred command for app dimming, ensuring brightness and on/off state are always consistent.

↑ Back to Commands

MoveWithOnOff (0x05)

Same as Move, but coordinates with the OnOff state during the transition. Parameters are identical to Move.

↑ Back to Commands

StepWithOnOff (0x06)

Same as Step, but coordinates with the OnOff state during the step. Parameters are identical to Step.

↑ Back to Commands

StopWithOnOff (0x07)

Same as Stop, but coordinates with the OnOff state. Parameters are identical to Stop.

↑ Back to Commands

MoveToClosestFrequency (0x08)

Moves CurrentFrequency to the closest value supported by the device. Only available when the device supports the Frequency feature; rarely used in everyday lighting control development.

↑ Back to Commands

Attributes

LevelControl attributes are organized into four groups by function. Click an attribute ID in the summary table below to jump to its detailed description.

Current State (0x00 – 0x03)

Describes the device's current level and allowed range. This is the most direct data source for displaying brightness status in the app.

↑ Back to Attributes

Frequency Control (0x04 – 0x06)

Describes the device's frequency control capabilities. These attributes are only present when the device supports the Frequency feature (Feature Map Bit 2).

↑ Back to Attributes

Transition & OnOff Coordination (0x0F – 0x14)

Controls the transition behavior of level changes and how the OnOff Cluster affects brightness when turning on/off. These attributes directly impact user experience -- whether the light snaps on/off or transitions smoothly.

↑ Back to Attributes

Startup Behavior (0x4000)

Controls the initial brightness after the device powers on.

StartUpCurrentLevel Special Values

↑ Back to Attributes

Enums & Bitmaps

MoveModeEnum

The MoveMode parameter in the Move and MoveWithOnOff commands uses this enum to specify the direction of level change.

StepModeEnum

The StepMode parameter in the Step and StepWithOnOff commands uses this enum to specify the step direction.

OptionsBitmap

This bitmap is used by the Options attribute and the OptionsMask / OptionsOverride parameters in all commands. It controls whether commands execute under specific conditions.

Feature Map

LevelControl uses the Feature Map to declare the device's supported optional capabilities.

Example Data

Read result of a typical dimmable light fixture's LevelControl Cluster:

{
  // --- Current State ---
  "0x0": 127,                // CurrentLevel = 127 (approximately 50% brightness)
  "0x1": 0,                  // RemainingTime = 0 (no transition in progress)
  "0x2": 1,                  // MinLevel = 1 (minimum available level)
  "0x3": 254,                // MaxLevel = 254 (maximum available level)

  // --- Transition & OnOff Coordination ---
  "0xF": 0,                  // Options = 0 (no special options)
  "0x10": 10,                // OnOffTransitionTime = 10 (1-second transition)
  "0x11": null,              // OnLevel = null (restore previous brightness on turn-on)
  "0x12": null,              // OnTransitionTime = null (uses OnOffTransitionTime)
  "0x13": null,              // OffTransitionTime = null (uses OnOffTransitionTime)
  "0x14": 50,                // DefaultMoveRate = 50 (50 units of change per second)

  // --- Startup Behavior ---
  "0x4000": null              // StartUpCurrentLevel = null (restore level before power loss)
}

Common Scenarios

Scenario 1: App Dimming

1. Read MinLevel (0x02) and MaxLevel (0x03), map to slider 0%~100%
2. When the user drags the slider, convert the percentage to a target level value
3. Send MoveToLevelWithOnOff (0x04) (the WithOnOff variant is recommended to keep the on/off state consistent)
4. Subscribe to changes of CurrentLevel (0x00) to update the UI in real time

Scenario 2: Memory Brightness On/Off

1. Set OnLevel (0x11) to null -- lets the device remember the brightness before the last turn-off
2. User taps "Turn On" → OnOff Cluster sends On command → light automatically restores to the previous brightness
3. User taps "Turn Off" → OnOff Cluster sends Off command → brightness gradually fades to 0
4. Optional: set OnTransitionTime (0x12) and OffTransitionTime (0x13) to control transition speed

Scenario 3: Power Restore Configuration

1. Set StartUpCurrentLevel (0x4000): null = restore level before power loss, 0x00 = minimum brightness, specific value = fixed brightness
2. Also set StartUpOnOff in the OnOff Cluster to ensure the on/off state and brightness are correctly coordinated
3. Typical configuration: StartUpCurrentLevel=null + StartUpOnOff=RestorePrevious → fully restores the state before power loss

Scenario 4: Physical Button Dimming (Long Press + Short Press)

1. Short press → send StepWithOnOff (0x06), each press changes by a fixed step value (e.g. 25)
2. Long press down → send MoveWithOnOff (0x05), continuously changes
3. Long press release → send StopWithOnOff (0x07), stops at the current brightness