风扇 Cluster（FanControl）

Cluster ID: 0x0202  |  所在 Endpoint: 通常在 Endpoint 1（功能端点）

FanControl 是 Matter 中控制风扇设备的核心 Cluster，适用于 HVAC 系统风扇、吊扇、独立风扇等场景。 它定义了风扇模式切换、转速控制、摇头、风感模式、送风方向等全部能力。 风扇类设备的日常开发基本都围绕这个 Cluster 展开。

Feature 位图

FanControl Cluster 通过 FeatureMap（0xFFFC）声明设备支持哪些能力。Feature 直接决定了哪些属性和命令可用：

命令（Commands）

FanControl Cluster 只有一个命令 —— Step，用于步进式调整风速。 大部分风扇控制通过直接写属性完成（如写入 FanMode、PercentSetting、SpeedSetting 等）， Step 命令提供了一种不需要知道当前状态就能增减风速的便捷方式。 点击下方表格中的命令 ID 可跳转到详细说明。

Step —— 步进调速（0x00）

向风扇发送步进调速指令，逐级增大或减小风速。 具体增减的幅度由设备自行决定（通常对应一个百分比或一个档位）。 如果当前风速已到最大或最小值，再向同方向调整时设备会忽略（不报错）。

StepDirection 枚举值

↑ 返回命令列表

属性详解

FanControl Cluster 的属性按功能分为五组。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。

风扇模式（0x00, 0x01）

控制风扇的工作模式和模式切换范围。FanMode 是最核心的控制属性 —— 大部分 App 界面上的模式按钮直接对应它。

FanMode 枚举值

FanModeSequence 枚举值

↑ 返回属性列表

百分比控制（0x02, 0x03）

所有风扇都支持百分比控制 —— 这是最通用的调速方式，不依赖任何 Feature。

↑ 返回属性列表

多档位控制（0x04, 0x05, 0x06）

需要 SPD（MultiSpeed） Feature。百分比是连续值，档位是离散值 —— 对于有物理挡位的风扇（如 3 挡吊扇），用 SpeedSetting 比百分比更自然。

↑ 返回属性列表

摇头功能（0x07, 0x08）

需要 RCK（Rocking） Feature。控制风扇的物理摆动方向 —— 常见于独立风扇和部分吊扇。

Rock 位图定义

↑ 返回属性列表

风感模式（0x09, 0x0A）

需要 WND（Wind） Feature。提供模拟自然风、睡眠风等非匀速送风模式，让体感更舒适。

Wind 位图定义

↑ 返回属性列表

送风方向（0x0B）

需要 AIRDIR（AirDirection） Feature。控制风扇叶片的旋转方向 —— 主要用于吊扇的夏/冬模式切换。

AirflowDirection 枚举值

↑ 返回属性列表

示例数据

一台支持全部 Feature 的智能吊扇在运转中的 FanControl Cluster 读取结果：

{
  // --- 风扇模式 ---
  "0x00": 5,              // FanMode = Auto（自动模式）
  "0x01": 2,              // FanModeSequence = OffLowMedHighAuto

  // --- 百分比控制 ---
  "0x02": 60,             // PercentSetting = 60（目标风速 60%）
  "0x03": 58,             // PercentCurrent = 58（实际风速 58%）

  // --- 多档位控制（SPD Feature）---
  "0x04": 10,             // SpeedMax = 10（最多 10 档）
  "0x05": 6,              // SpeedSetting = 6（目标档位 6）
  "0x06": 6,              // SpeedCurrent = 6（实际档位 6）

  // --- 摇头功能（RCK Feature）---
  "0x07": 0x03,           // RockSupport = 0x03（支持左右 + 上下）
  "0x08": 0x01,           // RockSetting = 0x01（当前左右摇头）

  // --- 风感模式（WND Feature）---
  "0x09": 0x03,           // WindSupport = 0x03（支持睡眠风 + 自然风）
  "0x0A": 0x02,           // WindSetting = 0x02（当前自然风）

  // --- 送风方向（AIRDIR Feature）---
  "0x0B": 0               // AirflowDirection = Forward（正转送风）
}

常见场景

场景 1：基础风扇控制

场景 2：多档位风扇界面

场景 3：吊扇完整控制面板

场景 4：HVAC 系统联动