FanControl Cluster

Cluster ID: 0x0202  |  Endpoint: Typically on Endpoint 1 (functional endpoint)

FanControl is the core Cluster for controlling fan devices in Matter, applicable to HVAC system fans, ceiling fans, standalone fans, and more. It defines all capabilities including fan mode switching, speed control, oscillation, wind sensation modes, and airflow direction. Fan device development fundamentally revolves around this Cluster.

Feature-Driven Capability Differences

FanControl capability varies widely — a simple HVAC fan may only support percentage speed control, while a high-end ceiling fan may support multi-speed, auto mode, oscillation, natural wind, and forward/reverse. Before development, read FeatureMap (0xFFFC) to confirm which Features the device supports, then decide the UI layout.

Feature Bitmap

FanControl Cluster declares device capabilities through FeatureMap (0xFFFC). Features directly determine which attributes and commands are available:

Bit 0
SPD（MultiSpeed） Multi-speed — supports SpeedMax / SpeedSetting / SpeedCurrent speed level attributes
Bit 1
AUT（Auto） Auto mode — FanMode can be set to Auto, device adjusts speed autonomously
Bit 2
RCK（Rocking） Rocking — supports RockSupport / RockSetting, controls fan oscillation direction
Bit 3
WND（Wind） Wind mode — supports WindSupport / WindSetting, provides sleep wind, natural wind, and other modes
Bit 4
STEP（Step） Step speed — supports Step command for incremental speed adjustment
Bit 5
AIRDIR（AirDirection） Air direction — supports AirflowDirection attribute, controls forward/reverse rotation
Feature Combination Examples

A basic HVAC fan: FeatureMap = 0x00 (no extra Features, percentage speed only).
A high-end ceiling fan: FeatureMap = 0x3F (all 6 Features), supports multi-speed, auto mode, oscillation, wind sensing, step, and forward/reverse.
Standalone pedestal fan: FeatureMap = 0x0F (SPD + AUT + RCK + WND), has speed levels, auto, oscillation and wind sensing, but no step or reverse.

Commands

FanControl Cluster has only one command — Step, for incremental speed adjustment. Most fan control is done through direct attribute writes (such as writing FanMode, PercentSetting, SpeedSetting, etc.). The Step command provides a convenient way to increase or decrease speed without needing to know the current state. Click a command ID in the table below to jump to its detailed description.

ID Name Description Feature Required
0x00 Step Step speed (increase or decrease by one level) STEP

Step — Incremental Speed Adjustment (0x00)

Send an incremental speed adjustment command to the fan, increasing or decreasing speed by one level. The specific increment is determined by the device (typically corresponding to one percentage point or one speed level). If the current speed is already at maximum or minimum, further adjustments in the same direction are ignored (no error).

ParameterTypeRequiredDescription
Direction StepDirectionEnum Yes Step direction (see enum values below)
Wrap bool No Whether to wrap around. true means Increase at maximum wraps to minimum (and vice versa)
LowestOff bool No Whether the lowest level in wrap mode is Off. true means decreasing below minimum turns off the fan

StepDirection Enum Values

0
Increase Increase speed (up one level)
1
Decrease Decrease speed (down one level)
Usage Scenarios & Parameters

Ideal for physical remote "Speed +" / "Speed -" buttons — each press sends a Step command without needing to read the current speed first. If Wrap = true, users can continuously press "Speed +" to cycle through levels (e.g.: Low → Medium → High → Off → Low ...).

↑ Back to Commands

Attributes

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

ID Name Type Group Description
0x00 FanMode enum8 Fan Mode Current operating mode
0x01 FanModeSequence enum8 Fan Mode Supported mode sequence
0x02 PercentSetting uint8 / null Percentage Control Target speed percentage
0x03 PercentCurrent uint8 Percentage Control Actual speed percentage
0x04 SpeedMax uint8 Multi-Speed Control Maximum speed levels
0x05 SpeedSetting uint8 / null Multi-Speed Control Target speed level
0x06 SpeedCurrent uint8 Multi-Speed Control Actual speed level
0x07 RockSupport bitmap8 Oscillation Supported oscillation directions
0x08 RockSetting bitmap8 Oscillation Current oscillation setting
0x09 WindSupport bitmap8 Wind Mode Supported wind modes
0x0A WindSetting bitmap8 Wind Mode Current wind setting
0x0B AirflowDirection enum8 Airflow Direction Airflow direction (forward/reverse)

Fan Mode (0x00, 0x01)

Controls the fan's operating mode and mode switching range. FanMode is the most essential control attribute — most App UI mode buttons correspond directly to it.

ID Name Type Description
0x00 FanMode
Fan Mode		 enum8 Current fan operating mode. Write a new value to switch modes. In Auto and Smart modes, the device adjusts speed autonomously. See enum values below
0x01 FanModeSequence
Mode Sequence		 enum8 Declares the supported mode combinations. Determines which values can be written to FanMode — if Auto is not in the sequence, Auto cannot be written. See enum values below

FanMode Enum Values

0
Off Off, fan stopped
1
Low Low speed
2
Medium Medium speed
3
High High speed
4
On On (specific speed determined by device, typically resumes last speed)
5
Auto Auto mode — device adjusts speed automatically based on environment. Requires AUT Feature
6
Smart Smart mode — deprecated, equivalent to Auto. Retained for backward compatibility
FanMode Write Linkage with PercentSetting / SpeedSetting

When writing FanMode, the device automatically updates PercentSetting and SpeedSetting (if SPD Feature is supported). For example, after writing FanMode = High, PercentSetting may automatically become 100. Conversely, writing PercentSetting or SpeedSetting directly may also cause FanMode to change. When reading status, use PercentCurrent / SpeedCurrent as the source of truth, not the Setting values.

FanModeSequence Enum Values

0
OffLowMedHigh Off / Low / Medium / High
1
OffLowHigh Off / Low / High (no medium speed)
2
OffLowMedHighAuto Off / Low / Medium / High / Auto
3
OffLowHighAuto Off / Low / High / Auto (no medium speed)
4
OffHighAuto Off / High / Auto (only two speeds + auto)
5
OffHigh Off / High (on/off only, no intermediate speeds)

↑ Back to Attributes

Percentage Control (0x02, 0x03)

All fans support percentage control — this is the most universal speed control method, independent of any Feature.

ID Name Type Description
0x02 PercentSetting
Target Speed %		 uint8 / null Target speed percentage, range 0~100. Writing 0 is equivalent to FanMode = Off. Nullable — null indicates the device is in auto/smart mode, speed managed by the device
0x03 PercentCurrent
Actual Speed %		 uint8 Actual current fan speed percentage, range 0~100. This is a read-only attribute reflecting the real physical state. UI display should use this value
Setting vs. Current

PercentSetting is the "target value" (what you want), PercentCurrent is the "actual value" (what the fan is actually doing). They may differ — for example, after writing PercentSetting = 60, due to motor characteristics or speed level quantization, the actual speed may be 58% or 65%. The App UI should use PercentCurrent for speed display.

↑ Back to Attributes

Multi-Speed Control (0x04, 0x05, 0x06)

Requires SPD (MultiSpeed) Feature. Percentage is continuous, speed level is discrete — for fans with physical speed levels (like a 3-speed ceiling fan), SpeedSetting is more natural than percentage.

ID Name Type Description
0x04 SpeedMax
Max Speed Level		 uint8 Maximum speed levels supported by the device, range 1~100. Read-only. For example, SpeedMax = 3 means the fan has 3 speed levels (1, 2, 3)
0x05 SpeedSetting
Target Speed Level		 uint8 / null Target speed level, range 0~SpeedMax. Writing 0 is equivalent to off. Nullable — null means the device decides in auto mode. Requires SPD Feature
0x06 SpeedCurrent
Actual Speed Level		 uint8 Actual current speed level, range 0~SpeedMax. Read-only. Requires SPD Feature
Automatic Conversion Between Percentage and Speed Level

The device automatically converts between percentage and speed level internally. For example, a fan with SpeedMax = 4: after writing SpeedSetting = 2, PercentCurrent is approximately 50%; after writing PercentSetting = 75, SpeedCurrent is approximately 3. The exact conversion logic is determined by device firmware and may not be a precise linear mapping.

↑ Back to Attributes

Oscillation (0x07, 0x08)

Requires RCK (Rocking) Feature. Controls the fan's physical oscillation direction — common in standalone fans and some ceiling fans.

ID Name Type Description
0x07 RockSupport
Oscillation Support		 bitmap8 Oscillation directions supported by the device (read-only). See bitmap below
0x08 RockSetting
Oscillation Setting		 bitmap8 Currently enabled oscillation directions. Read/write, written value must be a subset of RockSupport. All zeros means stop oscillation

Rock Bitmap Definition

Bit 0
RockLeftRight Left-right oscillation
Bit 1
RockUpDown Up-down oscillation
Bit 2
RockRound Round oscillation (360° rotation)
Oscillation Combinations

RockSetting is a bitmap that can enable multiple directions simultaneously. For example, RockSetting = 0x03 (Bit 0 + Bit 1) means simultaneous left-right + up-down oscillation. However, the corresponding bits in RockSupport must also be 1 — writing unsupported directions will be rejected by the device.

↑ Back to Attributes

Wind Mode (0x09, 0x0A)

Requires WND (Wind) Feature. Provides non-uniform airflow modes like natural wind and sleep wind for improved comfort.

ID Name Type Description
0x09 WindSupport
Wind Support		 bitmap8 Wind modes supported by the device (read-only). See bitmap below
0x0A WindSetting
Wind Setting		 bitmap8 Currently enabled wind mode. Read/write, written value must be a subset of WindSupport. All zeros means constant-speed airflow

Wind Bitmap Definition

Bit 0
SleepWind Sleep wind — speed gradually decreases over time, suitable for falling asleep
Bit 1
NaturalWind Natural wind — speed fluctuates randomly, simulating outdoor breeze
Wind Modes Are Mutually Exclusive

Although WindSetting is in bitmap format, SleepWind and NaturalWind are typically mutually exclusive — both should not be enabled simultaneously. The specification does not explicitly prohibit simultaneous setting, but actual device behavior is undefined. It is recommended to design the App UI as radio buttons.

↑ Back to Attributes

Airflow Direction (0x0B)

Requires AIRDIR (AirDirection) Feature. Controls the fan blade rotation direction — primarily used for ceiling fan summer/winter mode switching.

ID Name Type Description
0x0B AirflowDirection
Airflow Direction		 enum8 Fan blade rotation direction. For ceiling fans, forward blows air downward (summer), reverse circulates air upward (winter). See enum values below

AirflowDirection Enum Values

0
Forward Forward — blows air downward (ceiling fan summer mode)
1
Reverse Reverse — blows air upward, uses ceiling reflection to promote air circulation (ceiling fan winter mode)
Practical Uses of Ceiling Fan Forward/Reverse

Summer (Forward): Blades rotate counterclockwise, creating a downward airflow; people standing beneath feel a cool breeze.
Winter (Reverse): Blades rotate clockwise, pushing warm air along the ceiling downward. People do not feel a direct draft, but room temperature is more even and heating efficiency improves.
Many users are unaware of this feature — the App can proactively suggest switching direction when seasons change.

↑ Back to Attributes

Example Data

FanControl Cluster read results from a smart ceiling fan supporting all Features while running:

{
  // --- Fan Mode ---
  "0x00": 5,              // FanMode = Auto
  "0x01": 2,              // FanModeSequence = OffLowMedHighAuto

  // --- Percentage Control ---
  "0x02": 60,             // PercentSetting = 60 (target speed 60%)
  "0x03": 58,             // PercentCurrent = 58 (actual speed 58%)

  // --- Multi-Speed Control (SPD Feature) ---
  "0x04": 10,             // SpeedMax = 10 (max 10 levels)
  "0x05": 6,              // SpeedSetting = 6 (target level 6)
  "0x06": 6,              // SpeedCurrent = 6 (actual level 6)

  // --- Oscillation (RCK Feature) ---
  "0x07": 0x03,           // RockSupport = 0x03 (supports left-right + up-down)
  "0x08": 0x01,           // RockSetting = 0x01 (currently left-right oscillation)

  // --- Wind Mode (WND Feature) ---
  "0x09": 0x03,           // WindSupport = 0x03 (supports sleep wind + natural wind)
  "0x0A": 0x02,           // WindSetting = 0x02 (currently natural wind)

  // --- Airflow Direction (AIRDIR Feature) ---
  "0x0B": 0               // AirflowDirection = Forward
}
Developer Tip

The simplest fan may only have FanMode (0x00), FanModeSequence (0x01), PercentSetting (0x02), and PercentCurrent (0x03) — four attributes. All other attributes depend on Features. Check FeatureMap (0xFFFC) before reading; reading an unsupported attribute returns UNSUPPORTED_ATTRIBUTE.

Common Scenarios

Scenario 1: Basic Fan Control

View Steps
  1. Read FanModeSequence (0x01) to determine which modes the device supports
  2. Write FanMode (0x00) to switch modes (Off / Low / Medium / High)
  3. Or write PercentSetting (0x02) to directly set percentage speed
  4. Subscribe to PercentCurrent (0x03) for real-time speed display sync in the App UI

Scenario 2: Multi-Speed Fan Interface

View Steps
  1. Confirm FeatureMap includes SPD (Bit 0), read SpeedMax (0x04) to get maximum speed levels
  2. Dynamically generate speed level buttons based on SpeedMax (e.g., SpeedMax = 5 shows buttons 1~5)
  3. Write SpeedSetting (0x05) to switch speed levels
  4. Subscribe to SpeedCurrent (0x06) to update the current speed level highlight in the UI
  5. If STEP Feature is also supported, use the Step command with remote +/- buttons

Scenario 3: Complete Ceiling Fan Control Panel

View Steps
  1. Read FeatureMap to show/hide corresponding UI modules based on supported Features
  2. Speed area: show speed level slider if SPD is available, otherwise show percentage slider
  3. Oscillation area (RCK): read RockSupport (0x07), only show supported direction options. Write RockSetting (0x08) to control oscillation
  4. Wind area (WND): read WindSupport (0x09), show supported modes (sleep wind/natural wind). Write WindSetting (0x0A) to switch wind mode
  5. Direction area (AIRDIR): show forward/reverse toggle button, write AirflowDirection (0x0B)
  6. Tip: Before switching airflow direction, it is recommended to stop the fan first (FanMode = Off), then restart after the direction switch is complete

Scenario 4: HVAC System Integration

View Steps
  1. FanControl is typically used alongside Thermostat Cluster (0x0201) on the same Endpoint
  2. When the Thermostat's SystemMode switches to FanOnly, the corresponding FanControl begins operating
  3. If the fan supports AUT Feature, set FanMode = Auto to let the fan automatically adjust speed based on thermostat demand
  4. Read the FanState bit in the Thermostat's ThermostatRunningState (0x29) to confirm whether the fan is running