温控 Cluster(Thermostat)
Cluster ID: 0x0201 |
所在 Endpoint: 通常在 Endpoint 1(功能端点)
Thermostat 是 Matter HVAC(暖通空调)设备的核心 Cluster,定义了温度读取、制冷/制热设定点管理、系统模式切换、周计划调度等全部能力。 所有温控类设备的日常开发都围绕这个 Cluster 展开。
Thermostat Cluster 中所有温度属性的单位都是 0.01°C。例如 LocalTemperature = 2150 表示实际温度 21.50°C。
读写温度属性时务必做好单位换算,否则设定点会偏离预期 100 倍。
Thermostat 的能力由 Feature Map 决定。Bit 0 = HEAT、Bit 1 = COOL、Bit 5 = AUTO、Bit 6 = LTNE(Local Temperature Not Exposed)。
很多属性有 Feature 门控 —— 例如只有支持 COOL 的设备才有 OccupiedCoolingSetpoint。读取不支持的属性会返回 UNSUPPORTED_ATTRIBUTE。
命令(Commands)
Thermostat 的命令主要用于调整设定点和管理周计划。与门锁不同,温控命令不要求 Timed Interaction(定时交互),可以直接发送。 点击下方表格中的命令 ID 可跳转到对应的详细说明。
| ID | 名称 | 说明 | Feature 要求 |
|---|---|---|---|
0x00 |
SetpointRaiseLower | 升高或降低温度设定点 | 无 |
0x01 |
SetWeeklySchedule | 设置一周的温度调度计划 | SCH |
0x02 |
GetWeeklySchedule | 查询已设置的周计划 | SCH |
0x03 |
ClearWeeklySchedule | 清除所有周计划 | SCH |
当设定值超出限制范围时,SetpointRaiseLower 会静默钳位(Clamp)到最近的合法值,而不是返回错误。
这与直接写属性不同 —— 直接给 OccupiedHeatingSetpoint 写入一个超范围值会返回 CONSTRAINT_ERROR。
这个不对称行为是 Matter 规范有意设计的。
SetpointRaiseLower —— 调整设定点(0x00)
升高或降低温度设定点。这是温控设备最常用的命令 —— 用户在 App 上点击"温度+"或"温度-"按钮时调用。
根据 Mode 参数,可以只调整制热设定点、只调整制冷设定点、或同时调整两者。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| Mode | enum8 | 是 | 调整目标:0 = Heat(制热),1 = Cool(制冷),2 = Both(两者同时) |
| Amount | int8 | 是 | 调整量,单位 0.1°C。正值升高、负值降低。例如 10 表示升高 1.0°C |
使用场景与参数
用户在 App 上点「温度 +1°C」时,发送 SetpointRaiseLower(Mode=2, Amount=10),同时升高制热和制冷设定点各 1°C。
如果当前 SystemMode 是 Heat,可以只发 Mode=0。
超出 MinHeatSetpointLimit / MaxCoolSetpointLimit 范围时会自动钳位,不会报错。
SetWeeklySchedule —— 设置周计划(0x01)
为指定的星期几设置温度切换时间表。可以一次设置多天、多个时间点的温度计划。 需要设备支持 SCH(Schedule)Feature。
| 参数 | 类型 | 说明 |
|---|---|---|
| NumberOfTransitionsForSequence | uint8 | 本次设置包含的时间切换点数量 |
| DayOfWeekForSequence | bitmap8 | 适用的星期几(位图:Bit 0 = 周日,Bit 1 = 周一 ... Bit 6 = 周六) |
| ModeForSequence | bitmap8 | 模式位图:Bit 0 = 包含制热设定点,Bit 1 = 包含制冷设定点 |
| Transitions | list | 时间切换点列表。每个包含 TransitionTime(距当天 0:00 的分钟数)和对应的设定点温度 |
使用场景与参数
设置"工作日早上 7:00 升温到 22°C,晚上 22:00 降到 18°C"的计划。
DayOfWeekForSequence = 0b0111110(周一到周五),Transitions 包含两个切换点。
计划容量可通过 NumberOfWeeklyTransitions (0x21) 和 NumberOfDailyTransitions (0x22) 查询。
GetWeeklySchedule —— 查询周计划(0x02)
查询已设置的周计划。指定想查询的星期几和模式,设备返回对应的时间切换表。
| 参数 | 类型 | 说明 |
|---|---|---|
| DaysToReturn | bitmap8 | 要查询的星期几(位图格式同 SetWeeklySchedule) |
| ModeToReturn | bitmap8 | 要查询的模式(Bit 0 = 制热,Bit 1 = 制冷) |
ClearWeeklySchedule —— 清除周计划(0x03)
清除设备上所有已设置的周计划。无参数,执行后设备恢复为无计划状态。
属性详解
Thermostat Cluster 的属性按功能分为五组。点击下方汇总表中的属性 ID 可跳转到对应的详细说明。
| ID | 名称 | 类型 | 分组 | 说明 |
|---|---|---|---|---|
0x00 |
LocalTemperature | int16s / null | 温度信息 | 本地测量温度 |
0x01 |
OutdoorTemperature | int16s / null | 温度信息 | 室外温度 |
0x02 |
Occupancy | bitmap8 | 温度信息 | 空间占用状态 |
0x03 |
AbsMinHeatSetpointLimit | int16s | 温度信息 | 制热设定点绝对最小值 |
0x04 |
AbsMaxHeatSetpointLimit | int16s | 温度信息 | 制热设定点绝对最大值 |
0x05 |
AbsMinCoolSetpointLimit | int16s | 温度信息 | 制冷设定点绝对最小值 |
0x06 |
AbsMaxCoolSetpointLimit | int16s | 温度信息 | 制冷设定点绝对最大值 |
0x07 |
PICoolingDemand | uint8 | 温度信息 | 制冷需求百分比(0-100) |
0x08 |
PIHeatingDemand | uint8 | 温度信息 | 制热需求百分比(0-100) |
0x09 |
HVACSystemTypeConfiguration | bitmap8 | 温度信息 | HVAC 系统类型配置 |
0x10 |
LocalTemperatureCalibration | int8 | 设定点 | 本地温度校准偏移量 |
0x11 |
OccupiedCoolingSetpoint | int16s | 设定点 | 有人时制冷设定温度 |
0x12 |
OccupiedHeatingSetpoint | int16s | 设定点 | 有人时制热设定温度 |
0x13 |
UnoccupiedCoolingSetpoint | int16s | 设定点 | 无人时制冷设定温度 |
0x14 |
UnoccupiedHeatingSetpoint | int16s | 设定点 | 无人时制热设定温度 |
0x15 |
MinHeatSetpointLimit | int16s | 设定点 | 制热设定点用户可调最小值 |
0x16 |
MaxHeatSetpointLimit | int16s | 设定点 | 制热设定点用户可调最大值 |
0x17 |
MinCoolSetpointLimit | int16s | 设定点 | 制冷设定点用户可调最小值 |
0x18 |
MaxCoolSetpointLimit | int16s | 设定点 | 制冷设定点用户可调最大值 |
0x19 |
MinSetpointDeadBand | int8 | 设定点 | 制热与制冷设定点之间的最小间隔 |
0x1A |
RemoteSensing | bitmap8 | 模式与状态 | 远程传感器使用标记 |
0x1B |
ControlSequenceOfOperation | enum8 | 模式与状态 | 控制运行序列 |
0x1C |
SystemMode | enum8 | 模式与状态 | 系统运行模式 |
0x1E |
ThermostatRunningMode | enum8 | 模式与状态 | 实际运行模式 |
0x20 |
StartOfWeek | enum8 | 模式与状态 | 一周起始日 |
0x21 |
NumberOfWeeklyTransitions | uint8 | 模式与状态 | 每周最大切换点数 |
0x22 |
NumberOfDailyTransitions | uint8 | 模式与状态 | 每天最大切换点数 |
0x23 |
TemperatureSetpointHold | enum8 | 模式与状态 | 设定点保持开关 |
0x24 |
TemperatureSetpointHoldDuration | uint16 / null | 模式与状态 | 设定点保持持续时间(分钟) |
0x25 |
ThermostatProgrammingOperationMode | bitmap8 | 模式与状态 | 编程运行模式 |
0x29 |
ThermostatRunningState | bitmap16 | 模式与状态 | 当前运行状态位图 |
0x30 |
SetpointChangeSource | enum8 | 变更追踪 | 最近一次设定点变更来源 |
0x31 |
SetpointChangeAmount | int16s / null | 变更追踪 | 最近一次设定点变更量 |
0x32 |
SetpointChangeSourceTimestamp | epoch-s | 变更追踪 | 最近一次设定点变更时间戳 |
0x34 |
OccupiedSetback | uint8 / null | 变更追踪 | 有人时的节能回退温度 |
0x35 |
OccupiedSetbackMin | uint8 / null | 变更追踪 | 有人回退最小值 |
0x36 |
OccupiedSetbackMax | uint8 / null | 变更追踪 | 有人回退最大值 |
0x37 |
UnoccupiedSetback | uint8 / null | 变更追踪 | 无人时的节能回退温度 |
0x38 |
UnoccupiedSetbackMin | uint8 / null | 变更追踪 | 无人回退最小值 |
0x39 |
UnoccupiedSetbackMax | uint8 / null | 变更追踪 | 无人回退最大值 |
0x3A |
EmergencyHeatDelta | uint8 | 变更追踪 | 紧急制热启动偏差 |
0x40 |
ACType | enum8 | AC 能力 | 空调类型 |
0x41 |
ACCapacity | uint16 | AC 能力 | 空调制冷/制热容量 |
0x42 |
ACRefrigerantType | enum8 | AC 能力 | 制冷剂类型 |
0x43 |
ACCompressorType | enum8 | AC 能力 | 压缩机类型 |
0x44 |
ACErrorCode | bitmap32 | AC 能力 | 空调错误码位图 |
0x45 |
ACLouverPosition | enum8 | AC 能力 | 百叶窗/导风板位置 |
0x46 |
ACCoilTemperature | int16s / null | AC 能力 | 盘管温度 |
0x47 |
ACCapacityFormat | enum8 | AC 能力 | 容量单位格式 |
温度信息(0x00-0x09)
温控设备的基础测量值、绝对限制和系统需求信息。
| ID | 名称 | 类型 | 说明 |
|---|---|---|---|
0x00 |
LocalTemperature 本地温度 |
int16s / null | 温控器测量到的当前温度,单位 0.01°C。null 表示温度不可用 |
0x01 |
OutdoorTemperature 室外温度 |
int16s / null | 室外温度,由外部传感器或远程数据源提供 |
0x02 |
Occupancy 占用状态 |
bitmap8 | Bit 0 = 1 表示空间有人占用,设备使用 Occupied 设定点;= 0 使用 Unoccupied 设定点 |
0x03 |
AbsMinHeatSetpointLimit 制热绝对最小值 |
int16s | 设备硬件支持的制热设定点绝对最小值,出厂固定 |
0x04 |
AbsMaxHeatSetpointLimit 制热绝对最大值 |
int16s | 设备硬件支持的制热设定点绝对最大值,出厂固定 |
0x05 |
AbsMinCoolSetpointLimit 制冷绝对最小值 |
int16s | 设备硬件支持的制冷设定点绝对最小值 |
0x06 |
AbsMaxCoolSetpointLimit 制冷绝对最大值 |
int16s | 设备硬件支持的制冷设定点绝对最大值 |
0x07 |
PICoolingDemand 制冷需求 |
uint8 | 当前制冷需求百分比(0-100%),由 PI 算法计算 |
0x08 |
PIHeatingDemand 制热需求 |
uint8 | 当前制热需求百分比(0-100%),由 PI 算法计算 |
0x09 |
HVACSystemTypeConfiguration HVAC 系统类型 |
bitmap8 | 系统类型位图 —— 制冷系统阶段数、制热系统阶段数、制热类型(燃气/电热)、制热燃料来源 |
LocalTemperature 是 Nullable 类型 —— 设备传感器故障或尚未就绪时值为 null。
如果启用了 LTNE(Local Temperature Not Exposed)Feature,这个属性也会返回 null。
App 端展示温度时需要处理空值情况。
AbsMin/MaxHeatSetpointLimit(0x03-0x06)是设备硬件决定的绝对范围,只读不可改。
MinHeatSetpointLimit(0x15-0x18)是用户可调的范围,必须在绝对限制以内。
设定点写入校验链:AbsMin ≤ UserMin ≤ Setpoint ≤ UserMax ≤ AbsMax。
设定点(0x10-0x19)
温度设定点是温控的核心 —— 设备根据设定点与当前温度的差值来决定制热/制冷动作。
| ID | 名称 | 类型 | 说明 |
|---|---|---|---|
0x10 |
LocalTemperatureCalibration 温度校准 |
int8 | 本地温度传感器的校准偏移量,单位 0.1°C。例如 -5 表示实际温度比传感器读数低 0.5°C |
0x11 |
OccupiedCoolingSetpoint 有人制冷设定 |
int16s | 有人占用时的制冷目标温度。当 LocalTemperature 高于此值时启动制冷 |
0x12 |
OccupiedHeatingSetpoint 有人制热设定 |
int16s | 有人占用时的制热目标温度。当 LocalTemperature 低于此值时启动制热 |
0x13 |
UnoccupiedCoolingSetpoint 无人制冷设定 |
int16s | 无人时的制冷目标温度(通常比有人时高,节能) |
0x14 |
UnoccupiedHeatingSetpoint 无人制热设定 |
int16s | 无人时的制热目标温度(通常比有人时低,节能) |
0x15 |
MinHeatSetpointLimit 制热最小限制 |
int16s | 用户可设定的制热温度下限(可写,但不能低于 AbsMinHeatSetpointLimit) |
0x16 |
MaxHeatSetpointLimit 制热最大限制 |
int16s | 用户可设定的制热温度上限 |
0x17 |
MinCoolSetpointLimit 制冷最小限制 |
int16s | 用户可设定的制冷温度下限 |
0x18 |
MaxCoolSetpointLimit 制冷最大限制 |
int16s | 用户可设定的制冷温度上限 |
0x19 |
MinSetpointDeadBand 死区间隔 |
int8 | 制热与制冷设定点之间的最小温差,单位 0.1°C。防止制热和制冷同时工作。例如 25 表示 2.5°C |
设定点写入时,设备会校验完整的限制链(Matter 规范 4.3.6 节):
AbsMin ≤ MinLimit ≤ Setpoint ≤ MaxLimit ≤ AbsMax
并且在 Auto 模式下:HeatingSetpoint + MinSetpointDeadBand ≤ CoolingSetpoint。
直接写入超范围值会返回 CONSTRAINT_ERROR;通过 SetpointRaiseLower 则静默钳位。
模式与状态(0x1A-0x29)
定义温控系统的运行模式、调度能力和当前运行状态。
| ID | 名称 | 类型 | 说明 |
|---|---|---|---|
0x1A |
RemoteSensing 远程传感标记 |
bitmap8 | 标记哪些温度/占用数据来自远程传感器。Bit 0 = 本地温度, Bit 1 = 室外温度, Bit 2 = 占用状态 |
0x1B |
ControlSequenceOfOperation 控制运行序列 |
enum8 | 设备支持的运行组合方式(仅制冷 / 仅制热 / 冷热兼备 等)。见下方枚举 |
0x1C |
SystemMode 系统模式 |
enum8 | 用户设定的系统运行模式。见下方枚举 |
0x1E |
ThermostatRunningMode 实际运行模式 |
enum8 | 系统当前实际的运行模式。仅 AUTO Feature 下可用,值为 Off/Cool/Heat 三选一 |
0x20 |
StartOfWeek 一周起始日 |
enum8 | 周计划的第一天。见下方枚举 |
0x21 |
NumberOfWeeklyTransitions 每周切换点数 |
uint8 | 设备支持的每周最大时间切换点数量 |
0x22 |
NumberOfDailyTransitions 每天切换点数 |
uint8 | 设备支持的每天最大时间切换点数量 |
0x23 |
TemperatureSetpointHold 设定点保持 |
enum8 | 是否暂时锁定当前设定点、不跟随计划变化。见下方枚举 |
0x24 |
TemperatureSetpointHoldDuration 保持持续时间 |
uint16 / null | 设定点保持的持续时间,单位分钟(0-1440)。null 或 0xFFFF 表示无限期保持 |
0x25 |
ThermostatProgrammingOperationMode 编程运行模式 |
bitmap8 | 编程模式位图。见下方定义 |
0x29 |
ThermostatRunningState 运行状态位图 |
bitmap16 | 当前正在运行的子系统(制热/制冷/风扇的各阶段)。见下方位图 |
SystemMode 枚举值
SystemMode 枚举中 没有值 2(从 1=Auto 直接跳到 3=Cool)。解析时不要假设连续,直接做 map 映射。
ControlSequenceOfOperation 枚举值
ThermostatRunningMode 枚举值
仅在 AUTO Feature 下可用,表示系统当前实际选择的运行方向:
ThermostatRunningState 位图
TemperatureSetpointHold 枚举值
ThermostatProgrammingOperationMode 位图
StartOfWeek 枚举值
三个容易混淆的属性:
SystemMode(0x1C)= 用户设定的目标模式,可读可写(如"自动")
ThermostatRunningMode(0x1E)= Auto 模式下设备实际选择的方向(只读,Off/Cool/Heat 三选一)
ThermostatRunningState(0x29)= 当前各子系统(制热/制冷/风扇)的实时开关状态(只读位图)
变更追踪与节能(0x30-0x3A)
追踪设定点的变更来源和历史,以及节能回退(Setback)配置。
| ID | 名称 | 类型 | 说明 |
|---|---|---|---|
0x30 |
SetpointChangeSource 变更来源 |
enum8 | 最近一次设定点变更的来源。见下方枚举 |
0x31 |
SetpointChangeAmount 变更量 |
int16s / null | 最近一次设定点变更的幅度,单位 0.01°C。null 表示无变更记录 |
0x32 |
SetpointChangeSourceTimestamp 变更时间戳 |
epoch-s | 最近一次设定点变更的 UTC 时间戳 |
0x34 |
OccupiedSetback 有人节能回退 |
uint8 / null | 有人时的节能温度回退量,单位 0.1°C。用于在占用状态下适度降低能耗 |
0x35 |
OccupiedSetbackMin 有人回退最小值 |
uint8 / null | OccupiedSetback 的允许最小值 |
0x36 |
OccupiedSetbackMax 有人回退最大值 |
uint8 / null | OccupiedSetback 的允许最大值 |
0x37 |
UnoccupiedSetback 无人节能回退 |
uint8 / null | 无人时的节能温度回退量,单位 0.1°C。通常大于有人回退 |
0x38 |
UnoccupiedSetbackMin 无人回退最小值 |
uint8 / null | UnoccupiedSetback 的允许最小值 |
0x39 |
UnoccupiedSetbackMax 无人回退最大值 |
uint8 / null | UnoccupiedSetback 的允许最大值 |
0x3A |
EmergencyHeatDelta 紧急制热偏差 |
uint8 | 触发紧急制热的温度偏差阈值,单位 0.1°C |
SetpointChangeSource 枚举值
AC 能力(0x40-0x47)
空调设备的硬件能力和运行参数。这组属性主要用于分体空调(Mini Split AC)设备。
| ID | 名称 | 类型 | 说明 |
|---|---|---|---|
0x40 |
ACType 空调类型 |
enum8 | 空调的类型和驱动方式。见下方枚举 |
0x41 |
ACCapacity 空调容量 |
uint16 | 制冷/制热容量,单位由 ACCapacityFormat 决定(通常为 BTU/h) |
0x42 |
ACRefrigerantType 制冷剂类型 |
enum8 | 使用的制冷剂种类。见下方枚举 |
0x43 |
ACCompressorType 压缩机类型 |
enum8 | 压缩机的温度等级。见下方枚举 |
0x44 |
ACErrorCode 空调错误码 |
bitmap32 | 空调故障状态位图 —— Bit 0: 压缩机故障, Bit 1: 室温传感器故障, Bit 2: 室外温度传感器故障, Bit 3: 盘管传感器故障, Bit 4: 风扇故障 |
0x45 |
ACLouverPosition 导风板位置 |
enum8 | 百叶窗/导风板的开合位置。见下方枚举 |
0x46 |
ACCoilTemperature 盘管温度 |
int16s / null | 蒸发器/冷凝器盘管的实时温度,单位 0.01°C |
0x47 |
ACCapacityFormat 容量格式 |
enum8 | ACCapacity 的单位格式。0 = BTU/h |
ACType 枚举值
ACRefrigerantType 枚举值
ACCompressorType 枚举值
ACLouverPosition 枚举值
标准示例
以下是 Matter 温控器的典型属性数据示例(JSON 格式),逐字段标注含义:
{
// --- 温度信息 ---
"0x00": 2150, // LocalTemperature = 2150 → 实际 21.50°C
"0x01": 3200, // OutdoorTemperature = 3200 → 实际 32.00°C
"0x02": 1, // Occupancy = 1(有人占用)
// --- 设定点 ---
"0x11": 2400, // OccupiedCoolingSetpoint = 2400 → 24.00°C
"0x12": 2000, // OccupiedHeatingSetpoint = 2000 → 20.00°C
"0x15": 700, // MinHeatSetpointLimit = 700 → 7.00°C
"0x16": 3000, // MaxHeatSetpointLimit = 3000 → 30.00°C
"0x17": 1600, // MinCoolSetpointLimit = 1600 → 16.00°C
"0x18": 3200, // MaxCoolSetpointLimit = 3200 → 32.00°C
"0x19": 25, // MinSetpointDeadBand = 25 → 2.5°C
// --- 模式与状态 ---
"0x1B": 4, // ControlSequenceOfOperation = CoolingAndHeating
"0x1C": 1, // SystemMode = Auto
"0x1E": 3, // ThermostatRunningMode = Cool
"0x29": 0x0006, // ThermostatRunningState = CoolStateOn + FanStateOn
// --- AC 能力 ---
"0x40": 3, // ACType = CoolingAndInverter
"0x41": 12000, // ACCapacity = 12000(BTU/h)
"0x42": 2, // ACRefrigerantType = R410a
"0x45": 4 // ACLouverPosition = HalfOpen
}
所有温度属性的值都是 0.01°C 为单位的整数。将设备返回的 2150 显示给用户时,需要除以 100 得到 21.50°C。
ThermostatRunningState = 0x0006 表示 Bit 1(CoolStateOn)和 Bit 2(FanStateOn)同时为 1,即制冷和风扇都在运行。
常见场景
场景 1:读取当前温度和系统状态
- 读取
LocalTemperature (0x00)—— 注意处理null值 - 读取
SystemMode (0x1C)获取当前模式(Off/Auto/Cool/Heat 等) - 读取
ThermostatRunningState (0x29)判断哪些子系统正在运行 - 展示时做好单位换算 —— 所有温度值除以 100 才是实际摄氏度
场景 2:调整温度设定点
- 先读取
MinHeatSetpointLimit (0x15)到MaxCoolSetpointLimit (0x18)确定可调范围 - 使用
SetpointRaiseLower命令逐步调整,或直接写入OccupiedCoolingSetpoint (0x11)/OccupiedHeatingSetpoint (0x12) - Auto 模式下注意
MinSetpointDeadBand (0x19)约束 —— 制热和制冷设定点之间必须保持足够间距 - 订阅设定点属性的变化,确认修改生效
场景 3:切换系统模式
- 读取
ControlSequenceOfOperation (0x1B)确定设备支持哪些模式组合 - 仅制冷设备(值 0-1)不要显示 Heat 选项;仅制热设备(值 2-3)不要显示 Cool 选项
- 写入
SystemMode (0x1C)切换模式 - 切换后读取
ThermostatRunningMode (0x1E)(Auto 模式下)确认设备实际运行方向
场景 4:设置周计划
- 先确认设备支持 SCH Feature(检查 Feature Map)
- 读取
NumberOfWeeklyTransitions (0x21)和NumberOfDailyTransitions (0x22)了解容量限制 - 读取
StartOfWeek (0x20)确定一周起始日 - 发送
SetWeeklySchedule (0x01)设置计划 - 可通过
GetWeeklySchedule (0x02)回读验证
场景 5:App 首页展示温控卡片
- 订阅
LocalTemperature (0x00)+SystemMode (0x1C)+ThermostatRunningState (0x29) - 展示当前温度、目标温度(根据 SystemMode 选取对应设定点)
- 用 ThermostatRunningState 位图显示运行动画 —— 制热中 / 制冷中 / 风扇运转中
- 配合 PowerSource Cluster 显示电池电量(电池供电的温控器)