OnOff Cluster

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

OnOff is the most fundamental control Cluster in Matter, responsible for turning devices on, off, and toggling their state. All device types that need on/off capability (lights, outlets, switches, etc.) depend on this Cluster. It is also the first Cluster you encounter when getting started with Matter development.

Lighting Feature (LT)

The OnOff Cluster defines a Lighting (LT) Feature. When LT is enabled, the Cluster provides four additional attributes: GlobalSceneControl, OnTime, OffWaitTime, and StartUpOnOff, as well as three advanced commands: OffWithEffect, OnWithRecallGlobalScene, and OnWithTimedOff. Lighting devices typically enable this feature, while basic switches may not need it.

Commands

The OnOff Cluster defines 6 commands. The basic trio (Off / On / Toggle) is supported by all devices, while the three advanced commands require the device to support the Lighting (LT) feature. Click a command ID in the table below to jump to its detailed description.

ID	Name	Description	Required Feature
`0x00`	Off	Turn off the device	None
`0x01`	On	Turn on the device	None
`0x02`	Toggle	Toggle on/off state	None
`0x40`	OffWithEffect	Turn off with a transition effect	LT
`0x41`	OnWithRecallGlobalScene	Turn on and recall global scene	LT
`0x42`	OnWithTimedOff	Timed on (auto-off after timeout)	LT

Off (0x00)

Switches the device to the off state. On success, the OnOff attribute becomes false. This is the most basic command and requires no parameters.

Usage Scenarios

Called when a user taps the off button in the app, an automation rule triggers a turn-off, or a voice assistant executes a "turn off the light" command.

↑ Back to Commands

On (0x01)

Switches the device to the on state. On success, the OnOff attribute becomes true. Also requires no parameters.

Usage Scenarios

Called when a user taps the on button, or when an occupancy sensor detects presence and triggers a turn-on.

↑ Back to Commands

Toggle (0x02)

Toggles the device's current state: if currently on, it turns off; if currently off, it turns on. Ideal for scenarios where you don't care about the current state and just want to flip it. Requires no parameters.

Usage Scenarios

A physical wall switch press or a single-button remote control action. Unlike sending On or Off separately, Toggle does not require reading the current state first.

↑ Back to Commands

OffWithEffect (0x40)

Turns off the device while applying a visual transition effect (such as fade-out or delayed off). Before turning off, the device automatically saves the current scene to the global scene (GlobalScene), so it can later be restored via OnWithRecallGlobalScene.

Parameter	Type	Description
EffectIdentifier	EffectIdentifierEnum	Effect type (see enum values below)
EffectVariant	enum8	Effect variant (meaning depends on the EffectIdentifier value)

EffectIdentifier Enum Values

DelayedAllOff Delayed all off -- fade out then turn off

DyingLight Dying light effect -- simulates a bulb briefly brightening before fading out

EffectVariant for DelayedAllOff

DelayedOffFastFade Fast fade-out (default)

NoFade No fade, turns off immediately

DelayedOffSlowFade Slow fade-out

DyingLight EffectVariant

DyingLightFadeOff Brightens by 20% then slowly fades out (default and only variant)

Usage Scenarios

"Goodnight" scene for smart lights: the light gradually dims (DelayedAllOff + SlowFade) instead of turning off abruptly. The device saves the current brightness and color to GlobalScene before turning off, which can be restored later via OnWithRecallGlobalScene.

↑ Back to Commands

OnWithRecallGlobalScene (0x41)

Turns on the device and restores the global scene (GlobalScene) previously saved by OffWithEffect. No parameters. After execution, GlobalSceneControl returns to true.

Usage Scenarios

Used in tandem with OffWithEffect. For example: at night, use OffWithEffect to turn off the light (saving the 70% warm-light state). In the morning, call OnWithRecallGlobalScene and the light restores directly to 70% warm light instead of defaulting to 100% cool white.

↑ Back to Commands

OnWithTimedOff (0x42)

Turns on the device and starts an auto-off countdown timer. If the device is already on, the countdown is refreshed. Ideal for "turn on briefly" scenarios.

Parameter	Type	Description
OnOffControl	OnOffControlBitmap	Bit 0: AcceptOnlyWhenOn -- when set to 1, the command is accepted only if the device is already on
OnTime	uint16	On duration in 1/10 seconds. E.g. `300` = 30 seconds
OffWaitTime	uint16	Wait time after turning off (debounce), in 1/10 seconds

Usage Scenarios & Parameters

Hallway and corridor lights: when an occupancy sensor triggers, send OnWithTimedOff (OnTime=300, i.e. 30 seconds). If no further trigger occurs within 30 seconds, the light turns off automatically. A new detection simply sends OnWithTimedOff again to refresh the countdown.

AcceptOnlyWhenOn purpose: prevents the sensor from turning the light back on after the user manually turned it off. With AcceptOnlyWhenOn = 1, the timer is only extended when the light is already on; it won't re-open a light that has been turned off.

↑ Back to Commands

Attributes

The OnOff Cluster has 5 application attributes. Click an attribute ID in the summary table below to jump to its detailed description.

ID	Name	Type	Group	Description
`0x0000`	OnOff	bool	On/Off State	Current on/off state
`0x4000`	GlobalSceneControl	bool	On/Off State	Whether the global scene is valid
`0x4001`	OnTime	uint16	Timing Parameters	Remaining on time (1/10 seconds)
`0x4002`	OffWaitTime	uint16	Timing Parameters	Off wait time (1/10 seconds)
`0x4003`	StartUpOnOff	enum8 / null	Startup Behavior	Initial state when the device powers on

On/Off State (0x0000, 0x4000)

Describes the device's current on/off state and global scene control flag.

ID	Name	Type	Description
`0x0000`	OnOff	bool	The device's current on/off state. `true` = on, `false` = off. This is the only mandatory attribute in the OnOff Cluster
`0x4000`	GlobalSceneControl	bool	Indicates whether the global scene is valid. Becomes `false` after calling OffWithEffect (scene saved for later recall), returns to `true` after calling OnWithRecallGlobalScene. Requires LT feature

↑ Back to Attributes

Timing Parameters (0x4001, 0x4002)

Countdown control for the OnWithTimedOff command. These two attributes are automatically maintained by the device and typically do not need to be written manually.

Time Unit Note

The unit for OnTime and OffWaitTime is 1/10 second (100 milliseconds), not seconds or milliseconds. For example, a value of 300 means 30 seconds, and 10 means 1 second.

ID	Name	Type	Description
`0x4001`	OnTime	uint16	Remaining on time for the device, in 1/10 seconds. Set by the OnWithTimedOff command; the device turns off automatically when the countdown reaches zero. A value of `0` means timed-on is not active. Requires LT feature
`0x4002`	OffWaitTime	uint16	Wait period after the device turns off, in 1/10 seconds. During this period, if OnWithTimedOff is received with AcceptOnlyWhenOn = 1, the command is ignored. Prevents sensors from accidentally turning the light back on. Requires LT feature

↑ Back to Attributes

Startup Behavior (0x4003)

Controls the initial on/off state after the device powers on (or restarts). This attribute significantly impacts user experience -- whether the light is on or off after a power outage depends on it.

ID	Name	Type	Description
`0x4003`	StartUpOnOff	enum8 / null	The on/off state after power-on (see enum values below). Nullable -- `null` means restore the state from before power loss. Writing requires manage privilege. Requires LT feature

StartUpOnOff Enum Values

Off Always off after power-on

On Always on after power-on

Toggle Toggles to the opposite of the state before power loss

null

Previous Restores the state from before power loss (most common)

null vs 0xFF

StartUpOnOff is a Nullable type. In Matter's over-the-wire encoding, null corresponds to 0xFF. So if you see 0xFF in raw protocol data, it actually means "restore the state before power loss", not a valid enum value.

↑ Back to Attributes

Feature Bitmap

The OnOff Cluster uses FeatureMap (0xFFFC) to declare which advanced capabilities the device supports:

Bit 0

LT（Lighting） Lighting feature -- enables scene save/recall, timed on/off, fade-off effect, and startup behavior

Bit 1

DF (DeadFrontBehavior) Cuts front-end power when off; the device enters a "dead front" state (unresponsive to interaction)

Bit 2

OO (OffOnly) Supports only the off operation (device is turned on by an external mechanism, such as a physical button)

Example Data

Read result of an OnOff Cluster from a smart light with the Lighting feature enabled, in the on state:

{
  // --- On/Off State ---
  "0x0000": true,           // OnOff = true (currently on)
  "0x4000": true,           // GlobalSceneControl = true (global scene valid)

  // --- Timing Parameters ---
  "0x4001": 0,              // OnTime = 0 (timed-on not active)
  "0x4002": 0,              // OffWaitTime = 0 (off-wait not active)

  // --- Startup Behavior ---
  "0x4003": null             // StartUpOnOff = null (restore state before power loss)
}

Developer Tip

For the simplest devices (such as basic switches or outlets), there may only be one attribute: OnOff (0x0000). Only devices that support the Lighting feature report the four attributes from 0x4000 to 0x4003. Check FeatureMap (0xFFFC) first to determine which features the device supports.

Common Scenarios

Scenario 1: Basic On/Off Control

Send On (0x01) or Off (0x00) command to control the device
Subscribe to OnOff (0x0000) attribute changes to keep the app UI in sync
If you don't care about the current state, use Toggle (0x02) directly

Scenario 2: Hallway / Motion-Sensor Auto-Off

When the sensor detects presence, send OnWithTimedOff (0x42) with OnTime set to 300 (30 seconds)
If no one is detected within 30 seconds, the light turns off automatically
If presence is detected again, send OnWithTimedOff again to refresh the countdown
Set AcceptOnlyWhenOn = 1 to prevent the sensor from turning the light back on after the user manually turned it off

Scenario 3: Configure Power-On Behavior

Read FeatureMap (0xFFFC) to confirm the device supports the Lighting (LT) feature
Write the desired value to StartUpOnOff (0x4003):
- 0 (Off) -- light stays off after power is restored
- 1 (On) -- light turns on automatically after power is restored
- null (Previous) -- restores the state before power loss (recommended)
Note: writing StartUpOnOff requires manage level privilege (Administrator role)

Scenario 4: Fade-Off + Scene Recall (Goodnight / Good Morning)

At bedtime: send OffWithEffect (0x40); the device saves current brightness and color to the global scene, then fades off
In the morning: send OnWithRecallGlobalScene (0x41); the device restores brightness and color from before bedtime
Note: calling On (0x01) directly will not recall the scene; the light turns on at default brightness