占用感应 Cluster（OccupancySensing）

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

OccupancySensing 用于报告设备所在区域是否有人（或物体）存在。 传感器类型包括 被动红外（PIR）、超声波、物理接触和雷达。 这个 Cluster 是纯只读的 —— 只有属性，没有命令。App 通过订阅属性变化来获取占用状态的实时更新。

传感器类型决定行为

不同传感器类型的工作原理差异很大：PIR 靠检测人体热辐射变化，超声波通过反射波检测运动，物理接触依赖压力传感器，雷达则用微波信号穿墙检测。 OccupancySensorType 属性决定了设备支持哪组延迟/阈值参数，App 应根据传感器类型展示不同的配置界面。

属性总览

属性按功能分为四组：核心状态、PIR 传感器参数、超声波传感器参数、物理接触传感器参数。点击属性 ID 可跳转到详细说明。

ID 名称 类型 分组 说明
0x00 Occupancy bitmap8 核心状态 当前占用状态位图
0x01 OccupancySensorType enum8 核心状态 传感器类型
0x02 OccupancySensorTypeBitmap bitmap8 核心状态 传感器类型位图（支持多种类型）
0x03 HoldTime uint16 核心状态 占用状态保持时间（秒）
0x04 HoldTimeLimits struct 核心状态 HoldTime 的可调范围
0x10 PIROccupiedToUnoccupiedDelay uint16 PIR 传感器 PIR 占用→未占用延迟（秒）
0x11 PIRUnoccupiedToOccupiedDelay uint16 PIR 传感器 PIR 未占用→占用延迟（秒）
0x12 PIRUnoccupiedToOccupiedThreshold uint8 PIR 传感器 PIR 触发次数阈值
0x20 UltrasonicOccupiedToUnoccupiedDelay uint16 超声波传感器 超声波 占用→未占用延迟（秒）
0x21 UltrasonicUnoccupiedToOccupiedDelay uint16 超声波传感器 超声波 未占用→占用延迟（秒）
0x22 UltrasonicUnoccupiedToOccupiedThreshold uint8 超声波传感器 超声波触发次数阈值
0x30 PhysicalContactOccupiedToUnoccupiedDelay uint16 物理接触传感器 物理接触 占用→未占用延迟（秒）
0x31 PhysicalContactUnoccupiedToOccupiedDelay uint16 物理接触传感器 物理接触 未占用→占用延迟（秒）
0x32 PhysicalContactUnoccupiedToOccupiedThreshold uint8 物理接触传感器 物理接触触发次数阈值

核心状态（0x00 - 0x04）

所有 OccupancySensing 设备必须支持的属性，描述当前占用状态和传感器类型。

ID 名称 类型 读写 说明
0x00 Occupancy（占用状态） bitmap8 只读 bit 0（SensedOccupancy）：1 = 已占用，0 = 未占用。其余 bit 保留
0x01 OccupancySensorType（传感器类型） enum8 只读 设备使用的主要传感器类型（见下方枚举）
0x02 OccupancySensorTypeBitmap（传感器类型位图） bitmap8 只读 设备支持的所有传感器类型的位图（见下方位定义）
0x03 HoldTime（保持时间） uint16 读写 最后一次检测到占用后，状态保持「已占用」的秒数。防止状态在短暂离开时频繁翻转
0x04 HoldTimeLimits（保持时间范围） struct 只读 包含 HoldTimeMin、HoldTimeMax、HoldTimeDefault 三个字段，描述 HoldTime 的可调范围
Occupancy 是位图，不是布尔值

Occupancy 的类型是 bitmap8，不是 bool。只有 bit 0（SensedOccupancy）表示占用状态，其余 bit 保留供未来使用。 读取时应做位运算：isOccupied = (Occupancy & 0x01) != 0，不要直接判断是否等于 1。

OccupancySensorTypeEnum 枚举值

0
PIR 被动红外 —— 检测人体热辐射变化，最常见的类型
1
Ultrasonic 超声波 —— 发射超声波并检测反射变化，适合检测微小运动
2
PIRAndUltrasonic PIR + 超声波双重检测，精度更高，误报更少
3
PhysicalContact 物理接触 —— 压力传感器、座椅感应器等

OccupancySensorTypeBitmap 位定义

bit 0
PIR 支持被动红外传感
bit 1
Ultrasonic 支持超声波传感
bit 2
PhysicalContact 支持物理接触传感
HoldTime 的作用

想象一个会议室人体传感器：有人短暂离开去接水，不希望灯立即关闭。 HoldTime 就是这个「缓冲期」—— 设置为 30 秒意味着最后一次检测到人之后，设备会再保持 30 秒的「已占用」状态，然后才切换到「未占用」。 App 可以让用户在 HoldTimeLimits 范围内自行调整这个值。

↑ 返回属性列表

PIR 传感器参数（0x10 - 0x12）

仅当 OccupancySensorType 为 PIR（0）或 PIRAndUltrasonic（2）时才有意义。 控制 PIR 传感器状态切换的延迟和灵敏度。

ID 名称 类型 读写 说明
0x10 PIROccupiedToUnoccupiedDelay（占用→未占用延迟） uint16 读写 PIR 检测到占用消失后，延迟多少秒才切换到「未占用」。默认 0（立即切换）
0x11 PIRUnoccupiedToOccupiedDelay（未占用→占用延迟） uint16 读写 PIR 检测到占用出现后，延迟多少秒才切换到「已占用」。用于过滤瞬间误触发
0x12 PIRUnoccupiedToOccupiedThreshold（触发阈值） uint8 读写 在延迟时间内需要检测到多少次占用事件才触发切换。范围 1~254，默认 1
延迟与阈值配合使用

假设 PIRUnoccupiedToOccupiedDelay = 10，PIRUnoccupiedToOccupiedThreshold = 3： 传感器需要在 10 秒内检测到 3 次占用事件，才会从「未占用」切换到「已占用」。 这种组合能有效过滤宠物经过、窗帘飘动等误触发。

↑ 返回属性列表

超声波传感器参数（0x20 - 0x22）

仅当 OccupancySensorType 为 Ultrasonic（1）或 PIRAndUltrasonic（2）时才有意义。 参数含义与 PIR 组完全对称。

ID 名称 类型 读写 说明
0x20 UltrasonicOccupiedToUnoccupiedDelay（占用→未占用延迟） uint16 读写 超声波检测到占用消失后，延迟多少秒才切换到「未占用」。默认 0
0x21 UltrasonicUnoccupiedToOccupiedDelay（未占用→占用延迟） uint16 读写 超声波检测到占用出现后，延迟多少秒才切换到「已占用」
0x22 UltrasonicUnoccupiedToOccupiedThreshold（触发阈值） uint8 读写 延迟时间内需要检测到多少次占用事件才触发切换。范围 1~254，默认 1

↑ 返回属性列表

物理接触传感器参数（0x30 - 0x32）

仅当 OccupancySensorType 为 PhysicalContact（3）时才有意义。 参数含义与 PIR 组完全对称。

ID 名称 类型 读写 说明
0x30 PhysicalContactOccupiedToUnoccupiedDelay（占用→未占用延迟） uint16 读写 物理接触检测到占用消失后，延迟多少秒才切换到「未占用」。默认 0
0x31 PhysicalContactUnoccupiedToOccupiedDelay（未占用→占用延迟） uint16 读写 物理接触检测到占用出现后，延迟多少秒才切换到「已占用」
0x32 PhysicalContactUnoccupiedToOccupiedThreshold（触发阈值） uint8 读写 延迟时间内需要检测到多少次占用事件才触发切换。范围 1~254，默认 1

↑ 返回属性列表

示例数据

一个典型 PIR 人体传感器的 OccupancySensing Cluster 读取结果：

{
  // --- 核心状态 ---
  "0x0": 1,              // Occupancy = 0b00000001（bit 0 = 1，检测到占用）
  "0x1": 0,              // OccupancySensorType = PIR（被动红外）
  "0x2": 1,              // OccupancySensorTypeBitmap = 0b00000001（PIR）

  // --- PIR 传感器参数 ---
  "0x10": 0,             // PIROccupiedToUnoccupiedDelay = 0 秒（立即切换）
  "0x11": 10,            // PIRUnoccupiedToOccupiedDelay = 10 秒（延迟切换）
  "0x12": 1,             // PIRUnoccupiedToOccupiedThreshold = 1（触发 1 次即切换）

  // --- 保持时间 ---
  "0x3": 30,             // HoldTime = 30 秒
  "0x4": {               // HoldTimeLimits
    "HoldTimeMin": 1,
    "HoldTimeMax": 600,
    "HoldTimeDefault": 10
  }
}

应用场景

OccupancySensing 是智能家居自动化的核心触发源之一，以下是三个典型集成场景。

场景 1：智能家居自动化（灯光联动）

最经典的用法 —— 人来灯亮，人走灯灭。

  1. 订阅 Occupancy (0x00) 属性变化
  2. 当 Occupancy bit 0 从 0 变为 1（有人进入），发送 OnOff Cluster 的 On 命令开灯
  3. 当 Occupancy bit 0 从 1 变为 0（无人），发送 Off 命令关灯
  4. 通过调整 HoldTime 控制关灯延迟 —— 会议室建议 300 秒（5 分钟），走廊建议 30 秒

进阶：结合 LevelControl Cluster，夜间检测到人时只开到 20% 亮度，白天开到 100%。 还可以结合多个传感器做区域联动 —— 走廊传感器触发后开启走廊灯和目标房间灯。

场景 2：HVAC 节能集成

将占用感应与 Thermostat Cluster 联动，实现「人在舒适、人走节能」。

  1. 订阅 Occupancy (0x00) 属性变化
  2. 检测到占用时，将 Thermostat 的 OccupiedCoolingSetpoint / OccupiedHeatingSetpoint 设为舒适温度（如 24°C / 22°C）
  3. 检测到无人后（经过 HoldTime 延迟），切换到 UnoccupiedCoolingSetpoint / UnoccupiedHeatingSetpoint 节能温度（如 28°C / 18°C）
  4. 建议 HoldTime 设置为 600~900 秒（10~15 分钟），避免短暂离开就切换温度

注意：Thermostat Cluster 本身有 Occupancy 属性（0x02），但它只是被动接收状态。 真正的占用检测数据来源是 OccupancySensing Cluster，通常由自动化规则桥接两者。

场景 3：安防与入侵检测

用户离家设防后，占用传感器检测到异常活动即触发报警。

  1. 用户通过 App 启用「离家模式」（设防）
  2. 订阅所有占用传感器的 Occupancy (0x00) 变化
  3. 设防状态下检测到 Occupancy bit 0 = 1，触发安防联动：
    • 推送报警通知到用户手机
    • 开启摄像头录像
    • 触发声光报警器
  4. 为减少误报，建议提高灵敏度要求：PIRUnoccupiedToOccupiedThreshold = 3，PIRUnoccupiedToOccupiedDelay = 5

提示：安防场景下建议使用 PIRAndUltrasonic 双模传感器，PIR 容易被宠物误触发，超声波可以做二次确认。 同时要注意区分设防区域和非设防区域的传感器。

开发建议

App 展示占用传感器状态时，典型的处理流程：

  1. 读取 OccupancySensorType (0x01)，在 UI 上显示传感器类型图标和名称
  2. 订阅 Occupancy (0x00)，用位运算 & 0x01 取 bit 0，展示「有人 / 无人」状态
  3. 根据传感器类型，仅展示对应的延迟/阈值配置项（PIR 设备不显示超声波参数）
  4. 让用户在 HoldTimeLimits 的范围内调整 HoldTime，用滑块控件更直观
  5. 提供事件历史记录 —— 记录每次占用状态变化的时间，帮助用户了解活动规律