ColorControl Cluster

Cluster ID: 0x0300  |  Endpoint: Typically on Endpoint 1 (application endpoint, same endpoint as OnOff / LevelControl)

ColorControl is the core color control Cluster for Matter lighting devices, supporting three color models: Hue/Saturation, XY Chromaticity (CIE 1931), and Color Temperature (in Mireds). It also supports advanced features like Enhanced Hue (16-bit high-precision hue) and Color Loop (automatic color cycling).

Features (Feature Map)

ColorControl uses the Feature Map to declare which color control capabilities the device supports. Different capabilities determine the available command and attribute sets. Read ColorCapabilities (0x400A) to get the device's capability bitmap.

Commands

ColorControl defines 19 commands, organized into five groups by color model: Hue/Saturation control, XY chromaticity control, Color Temperature control, Enhanced Hue control, and Color Loop control. Click a command ID in the table below to jump to its detailed description.

All commands support OptionsMask and OptionsOverride parameters for temporarily overriding the ExecuteIfOff flag in the Options (0x000F) attribute.

MoveToHue (0x00)

Smoothly transitions the light's hue to a target value. Hue ranges from 0~254, mapping to the 0°~360° color wheel. The Direction parameter controls the transition direction on the color wheel.

↑ Back to Commands

MoveHue (0x01)

Continuously moves the hue at a constant rate until a StopMoveStep command is received or the hue reaches its natural boundary.

↑ Back to Commands

StepHue (0x02)

Increases or decreases the hue by a specified step value.

↑ Back to Commands

MoveToSaturation (0x03)

Smoothly transitions the light's saturation to a target value. Saturation ranges from 0~254, where 0 is colorless (white light) and 254 is maximum saturation.

↑ Back to Commands

MoveSaturation (0x04)

Continuously moves the saturation at a constant rate until a StopMoveStep is received. Parameter structure is the same as MoveHue.

↑ Back to Commands

StepSaturation (0x05)

Increases or decreases saturation by a specified step value. Parameter structure is the same as StepHue.

↑ Back to Commands

MoveToHueAndSaturation (0x06)

Sets both hue and saturation in a single command, more efficient and smoother than sending two separate commands.

↑ Back to Commands

MoveToColor (0x07)

Transitions the light's color to specified CIE 1931 XY chromaticity coordinates. X and Y range from 0~0xFEFF, mapping to 0.0~1.0 chromaticity values.

↑ Back to Commands

MoveColor (0x08)

Continuously moves at a constant rate on the XY chromaticity plane.

↑ Back to Commands

StepColor (0x09)

Increases/decreases both X and Y coordinates by a step value.

↑ Back to Commands

MoveToColorTemperature (0x0A)

Smoothly transitions the light's color temperature to a target value. The target is clamped to the [ColorTempPhysicalMinMireds, ColorTempPhysicalMaxMireds] range. This is the most commonly used command for color temperature lights.

↑ Back to Commands

MoveColorTemperature (0x4B)

Continuously moves the color temperature at a constant rate, with configurable upper and lower bounds.

↑ Back to Commands

StepColorTemperature (0x4C)

Increases or decreases the color temperature by a specified step value, with configurable upper and lower bounds.

↑ Back to Commands

EnhancedMoveToHue (0x40)

Similar to MoveToHue, but uses 16-bit Enhanced Hue (0~0xFFFF) with 256 times the precision of standard Hue. Suitable for scenarios requiring fine-grained color control.

↑ Back to Commands

EnhancedMoveHue (0x41)

Continuously moves the Enhanced Hue at a constant rate. Parameter structure is similar to MoveHue, but Rate is uint16.

↑ Back to Commands

EnhancedStepHue (0x42)

Increases or decreases Enhanced Hue by a specified step value. Parameter structure is similar to StepHue, but StepSize is uint16.

↑ Back to Commands

EnhancedMoveToHueAndSaturation (0x43)

Sets 16-bit Enhanced Hue and 8-bit Saturation in a single command.

↑ Back to Commands

ColorLoopSet (0x44)

Configures and activates/deactivates the Color Loop (automatic color cycling). The UpdateFlags bitmap controls which parameters this command updates. Once activated, the light automatically cycles through the color wheel at the configured time period.

↑ Back to Commands

StopMoveStep (0x47)

Immediately stops any ongoing Move or Step color transition. The light remains at its current color state. Applies to all color models (HS, XY, CT).

↑ Back to Commands

Attributes

The ColorControl Cluster has 52 attributes organized into six groups. Click an attribute ID in the summary table below to jump to its detailed description.

Current Color State

Reflects the light's current color parameters and serves as the core data source for app UI display and state synchronization.

↑ Back to Attributes

Color Mode & Options

Identifies the color control model currently in use and command execution options.

ColorMode Enum Values

EnhancedColorMode Enum Values

↑ Back to Attributes

Enhanced Hue & Color Loop

State attributes for high-precision hue control and automatic color cycling.

↑ Back to Attributes

Capabilities & Color Temperature Range

Describes the device's supported color control capabilities and the physical color temperature range. These attributes must be read during development to determine the available control modes.

ColorCapabilities Bitmap

↑ Back to Attributes

Drift Compensation & Fixture Info

Describes the fixture's color drift compensation mechanism and the number of primaries. Most app development does not need these attributes.

DriftCompensation Enum Values

↑ Back to Attributes

Primary Coordinates (Primary 1~6)

A fixture can declare up to 6 primaries, each with CIE XY coordinates and an intensity value. These attributes describe the physical color gamut of the fixture's LEDs, typically set by firmware, and generally do not need to be read during app development.

↑ Back to Attributes

White Point & Color Points

Describes the fixture's white point and RGB color point coordinates for color calibration. These attributes are writable and typically used by advanced calibration tools; app development generally does not need them.

↑ Back to Attributes

Command Parameter Enum Quick Reference

The following enum types are reused across multiple command parameters.

DirectionEnum (Hue Transition Direction)

MoveModeEnum (Continuous Move Mode)

StepModeEnum (Step Direction)

ColorLoopActionEnum (Loop Action)

ColorLoopDirectionEnum (Loop Direction)

UpdateFlags Bitmap (ColorLoopSet Command Parameter)

Standard Example

Below is a typical attribute data example for a full-capability (HS + XY + CT + EHUE + CL) full-color light:

{
  // --- Current Color State ---
  "0x0000": 127,         // CurrentHue = 127 (approx. 180°, near cyan)
  "0x0001": 200,         // CurrentSaturation = 200 (high saturation)
  "0x0003": 24939,       // CurrentX = 24939 (CIE x ≈ 0.3805)
  "0x0004": 24701,       // CurrentY = 24701 (CIE y ≈ 0.3769)
  "0x0007": 370,         // ColorTemperatureMireds = 370 (approx. 2703K warm white)
  "0x0002": 0,           // RemainingTime = 0 (no transition in progress)

  // --- Color Mode ---
  "0x0008": 2,           // ColorMode = ColorTemperature (currently using CT control)
  "0x4001": 2,           // EnhancedColorMode = ColorTemperature
  "0x000F": 0,           // Options = 0 (ExecuteIfOff not enabled)

  // --- Enhanced Hue & Color Loop ---
  "0x4000": 0,           // EnhancedCurrentHue = 0
  "0x4002": 0,           // ColorLoopActive = 0 (loop not active)
  "0x4003": 0,           // ColorLoopDirection = Decrement
  "0x4004": 25,          // ColorLoopTime = 25 seconds
  "0x4005": 0,           // ColorLoopStartEnhancedHue = 0
  "0x4006": 0,           // ColorLoopStoredEnhancedHue = 0

  // --- Capabilities & CT Range ---
  "0x400A": 31,          // ColorCapabilities = 0x1F (all five capabilities supported)
  "0x400B": 153,         // ColorTempPhysicalMinMireds = 153 (approx. 6536K)
  "0x400C": 500,         // ColorTempPhysicalMaxMireds = 500 (approx. 2000K)
  "0x400D": 153,         // CoupleColorTempToLevelMinMireds = 153
  "0x4010": 370          // StartUpColorTemperatureMireds = 370 (warm white on power-on)
}

Common Scenarios

Scenario 1: Color Temperature Slider

1. Read ColorCapabilities (0x400A) and confirm Bit 4 (CT) is 1
2. Read ColorTempPhysicalMinMireds (0x400B) and ColorTempPhysicalMaxMireds (0x400C) to determine the slider range
3. When the user drags the slider, convert Kelvin to Mireds: mireds = 1000000 / kelvin
4. Send MoveToColorTemperature (0x0A) with TransitionTime set to 5 (0.5-second transition)
5. Subscribe to ColorTemperatureMireds (0x0007) to confirm the device has reached the target color temperature

Scenario 2: Color Wheel Picker (Hue/Saturation)

1. Read ColorCapabilities (0x400A) and confirm Bit 0 (HS) is 1
2. User selects a point on the color wheel, obtaining angle and radius
3. Angle to Hue: hue = angle * 254 / 360
4. Radius to Saturation: saturation = radius * 254 / maxRadius
5. Send MoveToHueAndSaturation (0x06) to set both values at once
6. Subscribe to CurrentHue (0x0000) and CurrentSaturation (0x0001) to confirm the result

Scenario 3: Light Control Page Initialization

1. Read ColorCapabilities (0x400A) -- determines which control components to show in the UI (color wheel, CT slider, etc.)
2. Read EnhancedColorMode (0x4001) -- determines the current color mode and highlights the corresponding UI tab
3. Read the corresponding attributes based on the mode: CT mode reads ColorTemperatureMireds, HS mode reads CurrentHue + CurrentSaturation
4. If CT is supported, read ColorTempPhysicalMinMireds / MaxMireds to set the slider range
5. Subscribe to all relevant attribute changes to keep the UI in sync with device state

Scenario 4: Ambient / Party Mode (Color Loop)

1. Read ColorCapabilities (0x400A) and confirm Bit 2 (CL) is 1
2. Send ColorLoopSet (0x44): UpdateFlags = 0x0F, Action = 2 (start from current color), Direction = 1 (increment), Time = 30 (30 seconds per cycle)
3. Read ColorLoopActive (0x4002) to confirm the loop is active
4. To stop, send ColorLoopSet again with Action = 0 (Deactivate)