ValveConfigurationAndControl Cluster

Cluster ID: 0x0081 | Endpoint: Typically on the Valve Endpoint (valve function endpoint)

ValveConfigurationAndControl is the core Cluster in Matter for controlling valve devices, applicable to water valves, gas valves, irrigation valves, and other scenarios requiring "open/close/timed/level control" capabilities. It defines valve open/close commands, duration control, current/target state, opening percentage, fault detection, and event reporting. Unlike a simple OnOff switch, the Valve Cluster has built-in timed auto-close and precise level control, making it more suitable for fluid control scenarios that require safety protection.

Feature-Driven Capability Differences

ValveConfigurationAndControl capabilities depend on two Features: TimeSync (TS) enables UTC timestamp-based auto-close capability, and Level (LVL) enables percentage opening control (0~100%). A simple water valve may only support fully open/fully closed, while an irrigation control valve may support both timed and level adjustment. Before development, read FeatureMap (0xFFFC) to determine what capabilities the device supports, then decide on the UI layout.

Commands

The ValveConfigurationAndControl Cluster has 2 commands: Open and Close. The Open command supports optional duration and target level parameters; the Close command takes no parameters and directly closes the valve. Click on a command ID in the table below to jump to its detailed description.

ID	Name	Description	Required Feature
`0x00`	Open	Open the valve (optionally specify duration and level)	None
`0x01`	Close	Close the valve	None

Open — Open Valve (0x00)

Opens the valve. Optional parameters can specify the open duration and target level. If no parameters are provided, the valve opens fully for the duration specified by DefaultOpenDuration. If the valve is already open, sending another Open command updates the duration and target level.

Parameter	Type	Required	Description
OpenDuration	elapsed-s / null	Optional	Open duration in seconds. `null` means use the DefaultOpenDuration value. Omitting also uses the default
TargetLevel	percent	Optional (requires LVL)	Target opening percentage, 1~100. Omitting means fully open (100%). Requires LVL Feature

Safety Note: DefaultOpenDuration

If DefaultOpenDuration is null and the Open command also does not specify OpenDuration, the valve will remain open indefinitely until a Close command is received. For water and gas valves, it is recommended to always set a DefaultOpenDuration as a safety fallback to prevent the valve from remaining open long-term after a network disconnection, which could cause flooding or gas leaks.

Usage Scenarios

User taps "Open Water Valve" in the app, sending the Open command to open the valve. A garden irrigation system sends Open(OpenDuration=1800), opening the valve for 30 minutes before auto-closing. A smart HVAC system sends Open(TargetLevel=50), opening the valve to 50% to precisely control hot water flow.

↑ Back to Commands

Close — Close Valve (0x01)

Closes the valve. Takes no parameters. On successful execution, TargetState changes to Closed (0), and the valve begins its closing action. If the valve is currently in a timed open state, the Close command cancels the timer and closes the valve immediately.

Usage Scenarios

User manually closes the water valve; a water leak sensor detects a leak and an automation rule triggers an emergency valve close; a gas alarm triggers a linked gas valve closure.

↑ Back to Commands

Attributes

ValveConfigurationAndControl Cluster attributes are organized into four functional groups. Click on an attribute ID in the summary table below to jump to its detailed description.

ID	Name	Type	Group	Description
`0x0000`	OpenDuration	elapsed-s / null	Timing Parameters	Current open duration (seconds)
`0x0001`	DefaultOpenDuration	elapsed-s / null	Timing Parameters	Default open duration (seconds)
`0x0002`	AutoCloseTime	epoch-us / null	Timing Parameters	UTC timestamp for auto-close
`0x0003`	RemainingDuration	elapsed-s / null	Timing Parameters	Remaining open time (seconds)
`0x0004`	CurrentState	ValveStateEnum / null	Valve State	Current valve state
`0x0005`	TargetState	ValveStateEnum / null	Valve State	Target valve state
`0x0006`	CurrentLevel	percent / null	Level Control	Current opening percentage
`0x0007`	TargetLevel	percent / null	Level Control	Target opening percentage
`0x0008`	DefaultOpenLevel	percent	Level Control	Default opening used when Open has no TargetLevel
`0x000A`	LevelStep	uint8	Level Control	Opening adjustment step size
`0x0009`	ValveFault	ValveFaultBitmap	Fault Status	Valve fault bitmap

Timing Parameters (0x0000 ~ 0x0003)

Controls the valve's open duration and auto-close mechanism. This is the key capability that distinguishes the Valve Cluster from a simple OnOff switch — built-in timed protection prevents the valve from accidentally remaining open for extended periods.

ID	Name	Type	Description
`0x0000`	OpenDuration Open Duration	elapsed-s / null	Duration of the current valve open session, in seconds. Set by the Open command. `null` means the valve remains open indefinitely (until a Close command is received). Becomes `null` after the valve closes
`0x0001`	DefaultOpenDuration Default Open Duration	elapsed-s / null	Default value used when the Open command does not specify OpenDuration, in seconds. Read/Write. `null` means no default time (Open without parameters will keep the valve open indefinitely). It is recommended to set a reasonable safety value
`0x0002`	AutoCloseTime Auto Close Time	epoch-us / null	UTC timestamp when the valve will auto-close, in microseconds. Automatically calculated by the device based on OpenDuration and the time the valve was opened. `null` means no auto-close scheduled. Requires TS Feature
`0x0003`	RemainingDuration Remaining Duration	elapsed-s / null	Seconds remaining until auto-close. Automatically maintained by the device; when the countdown reaches zero, the valve closes. `null` means no timer is set or the valve is already closed

Relationship Between Timing Parameters

DefaultOpenDuration is the preset value, OpenDuration is the value in effect for the current session, RemainingDuration is the real-time countdown, and AutoCloseTime is the absolute time point. When the Open command is sent without parameters, OpenDuration = DefaultOpenDuration; when sent with parameters, OpenDuration = the command parameter value. The app UI typically displays RemainingDuration as the countdown.

↑ Back to Attributes

Valve State (0x0004 ~ 0x0005)

Describes the valve's current open/close state and target state. Valve actions take time (motor-driven), so CurrentState and TargetState may differ — while the valve is in motion, CurrentState is Transitioning.

ID	Name	Type	Description
`0x0004`	CurrentState Current State	ValveStateEnum / null	Actual current state of the valve. Nullable — `null` means the device cannot determine the current state (e.g., just powered up, no position sensor)
`0x0005`	TargetState Target State	ValveStateEnum / null	Target state of the valve. Changes to `Open (1)` after an Open command, and to `Closed (0)` after a Close command. Nullable — `null` means no pending target

State Transition Flow

After sending an Open command: TargetState immediately changes to Open, CurrentState changes to Transitioning, and the valve motor begins operating. Once the target position is reached, CurrentState changes to Open. The Close command works the same way. The app UI should display real-time status based on CurrentState, and can show a loading animation when the value is Transitioning.

↑ Back to Attributes

Level Control (0x0006 ~ 0x0008, 0x000A)

Controls the valve's precise opening percentage. Requires the device to support the Level (LVL) Feature. Valves without LVL support only have fully open/fully closed states.

ID	Name	Type	Description
`0x0006`	CurrentLevel Current Level	percent / null	Current actual opening percentage of the valve, 0~100. `0` = fully closed, `100` = fully open. Nullable — `null` means the current level cannot be determined. Requires LVL Feature
`0x0007`	TargetLevel Target Level	percent / null	Target opening percentage of the valve, 1~100. Set by the Open command's TargetLevel parameter. Nullable — `null` means no pending target level. Requires LVL Feature
`0x0008`	DefaultOpenLevel Default Open Level	percent	Default target opening, 1~100, used when the Open command is sent without a TargetLevel field. Default: `100` (fully open). Requires LVL Feature, optional
`0x000A`	LevelStep Level Step	uint8	Smallest step the valve opening can be adjusted by, 1~50. For example, with `10` only 10%, 20%, … can be set. Default: `1`. Requires LVL Feature, optional

Relationship Between Level and State

CurrentLevel = 0 is equivalent to CurrentState = Closed, and CurrentLevel > 0 is equivalent to CurrentState = Open. For devices that support LVL, the app can use a slider control to let users set the precise opening level; the Open command's TargetLevel parameter value corresponds directly to the slider position.

↑ Back to Attributes

Fault Status (0x0009)

Records valve fault information. ValveFault is a bitmap attribute; multiple faults can exist simultaneously.

ID	Name	Type	Description
`0x0009`	ValveFault Valve Fault	ValveFaultBitmap	Valve fault bitmap; each bit represents a fault type. `0` = no fault. See the ValveFaultBitmap section below

↑ Back to Attributes

Enums & Bitmaps

ValveStateEnum (Valve State Enum)

Used by the CurrentState and TargetState attributes to describe the valve's open/close state.

Closed Closed — valve is fully closed, no fluid passes through

Open Open — valve is open (fully or partially)

Transitioning Transitioning — valve is executing an open or close action (motor running)

ValveFaultBitmap (Valve Fault Bitmap)

Bitmap definition for the ValveFault (0x0009) attribute. Each bit represents a fault type; multiple bits can be set simultaneously. When any bit changes from 0 to 1, the device reports a ValveFault event.

Bit 0

GeneralFault General fault — uncategorized general hardware or software issue

Bit 1

Blocked Blocked — valve is mechanically stuck and cannot open or close normally

Bit 2

Leaking Leaking — fluid flow detected while the valve is in the closed state

Bit 3

NotConnected Not connected — communication between the valve actuator and controller is lost

Bit 4

ShortCircuit Short circuit — short circuit in the valve motor or driver circuit

Bit 5

CurrentExceeded Current exceeded — valve motor current exceeds the safe range

Fault Bitmap Reading Examples

ValveFault = 0x00 (decimal 0) = No fault, everything is normal.
ValveFault = 0x06 (decimal 6) = Bit 1 + Bit 2 = Valve is stuck and leaking — immediate repair needed.
ValveFault = 0x30 (decimal 48) = Bit 4 + Bit 5 = Short circuit and overcurrent — possible motor damage, power off and inspect.

Feature Bitmap

The ValveConfigurationAndControl Cluster declares supported advanced capabilities through FeatureMap (0xFFFC):

Bit 0

TS (TimeSync) Time synchronization — enables the AutoCloseTime attribute, allowing the device to precisely calculate auto-close timing based on UTC timestamps. Requires the device to be connected to the Time Synchronization Cluster

Bit 1

LVL (Level) Level control — enables CurrentLevel, TargetLevel attributes and the Open command's TargetLevel parameter, supporting 0~100% precise opening adjustment

Feature Combination Examples

A simple water valve (open/close): FeatureMap = 0x00, only supports fully open/fully closed and second-based timing.
An irrigation control valve: FeatureMap = 0x03 (TS + LVL), supports precise level adjustment and UTC timestamp-based auto-close.
A gas valve with time sync: FeatureMap = 0x01 (TS only), only fully open/fully closed, but supports precise timing via UTC timestamps.

Events

The ValveConfigurationAndControl Cluster defines 2 events, used for valve state change notifications and fault reporting.

ID	Name	Priority	Data Fields	Description
`0x00`	ValveStateChanged	INFO	ValveState (ValveStateEnum), ValveLevel (percent)	Triggered when valve state or opening level changes
`0x01`	ValveFault	WARNING	ValveFault (ValveFaultBitmap)	Triggered when the valve fault bitmap changes (fault added or cleared)

Event Subscription Advice

The ValveStateChanged event includes the post-change state and opening level; subscribing to it allows the app to update the interface in real time without polling CurrentState and CurrentLevel attributes. The ValveFault event triggers when faults appear or are cleared, carrying the latest complete fault bitmap. For water and gas valves, it is recommended to always subscribe to ValveFault events and immediately alert when a Leaking fault is received.

Example Data

A smart water valve with Level (LVL) feature running at 75% opening, ValveConfigurationAndControl Cluster read result:

{
  // --- Timing Parameters ---
  "0x0000": 1800,            // OpenDuration = 1800 seconds (this session open for 30 minutes)
  "0x0001": 3600,            // DefaultOpenDuration = 3600 seconds (default 1 hour per open)
  "0x0002": null,            // AutoCloseTime = null (no auto-close time set)
  "0x0003": 1200,            // RemainingDuration = 1200 seconds (20 minutes until close)

  // --- Valve State ---
  "0x0004": 1,               // CurrentState = Open (currently open)
  "0x0005": 1,               // TargetState = Open (target is also open)

  // --- Level Control (LVL Feature) ---
  "0x0006": 75,              // CurrentLevel = 75% (current opening 75%)
  "0x0007": 75,              // TargetLevel = 75% (target opening 75%)
  "0x0008": 100,             // DefaultOpenLevel = 100% (Open without a level opens fully)
  "0x000A": 1,               // LevelStep = 1% (opening step size)

  // --- Fault Status ---
  "0x0009": 0                // ValveFault = 0 (no fault)
}

Developer Tip

The simplest valves may only have the core attributes: OpenDuration, DefaultOpenDuration, RemainingDuration, CurrentState, TargetState, and ValveFault. CurrentLevel / TargetLevel requires the LVL Feature; AutoCloseTime requires the TS Feature. Check FeatureMap (0xFFFC) first; reading unsupported attributes will return UNSUPPORTED_ATTRIBUTE.

Common Scenarios

Scenario 1: Garden Irrigation Timed Watering

View Steps

Write DefaultOpenDuration (0x0001) = 1800 to preset 30 minutes of watering per session
An automation rule triggers at 6 AM, sending the Open (0x00) command (without parameters, using the default duration)
The valve opens, CurrentState changes to Open (1), and RemainingDuration begins counting down from 1800
The app subscribes to RemainingDuration (0x0003) and the interface displays "XX minutes until auto-close"
After 30 minutes the valve auto-closes, CurrentState changes to Closed (0)
If watering needs to be cancelled mid-session, send the Close (0x01) command to immediately close the valve
Subscribe to ValveFault events; when Blocked (Bit 1) is detected, remind the user to clean the valve

Scenario 2: Water Leak Sensor Linked Emergency Valve Close

View Steps

A water leak sensor (BooleanState Cluster) detects a leak, StateValue changes to true
An automation rule triggers, sending Close (0x01) to the water valve for an emergency close
Read CurrentState (0x0004) to confirm the valve is closed (Closed = 0)
If CurrentState is Transitioning (2), wait a few seconds and check again
Check the ValveFault (0x0009) bitmap for the Leaking (Bit 2) bit — if the valve is closed but leaking is still detected, the valve seal has failed and manual intervention is needed
Send an alert notification to the user: "Water leak detected. The water valve has been automatically closed. Please check the area."
After the leak is resolved, the user manually sends an Open command to restore water supply