OccupancySensing Cluster

Cluster ID: 0x0406  |  Endpoint: Typically on Endpoint 1 (application endpoint)

OccupancySensing reports whether a person (or object) is present in the area where the device is located. Sensor types include Passive Infrared (PIR), Ultrasonic, Physical Contact, and Radar. This cluster is purely read-only — it has attributes only, no commands. Apps receive real-time occupancy updates by subscribing to attribute changes.

Sensor Type Determines Behavior

Different sensor types work very differently: PIR detects changes in body heat radiation, ultrasonic detects motion via reflected sound waves, physical contact relies on pressure sensors, and radar uses microwave signals that can penetrate walls. The OccupancySensorType attribute determines which set of delay/threshold parameters the device supports, and apps should present different configuration interfaces based on the sensor type.

Attribute Overview

Attributes are organized into four groups: Core State, PIR Sensor Parameters, Ultrasonic Sensor Parameters, and Physical Contact Sensor Parameters. Click an attribute ID to jump to its detailed description.

ID Name Type Group Description
0x00 Occupancy bitmap8 Core State Current occupancy status bitmap
0x01 OccupancySensorType enum8 Core State Sensor type
0x02 OccupancySensorTypeBitmap bitmap8 Core State Sensor type bitmap (supports multiple types)
0x03 HoldTime uint16 Core State Occupancy state hold time (seconds)
0x04 HoldTimeLimits struct Core State Adjustable range for HoldTime
0x10 PIROccupiedToUnoccupiedDelay uint16 PIR Sensor PIR occupied-to-unoccupied delay (seconds)
0x11 PIRUnoccupiedToOccupiedDelay uint16 PIR Sensor PIR unoccupied-to-occupied delay (seconds)
0x12 PIRUnoccupiedToOccupiedThreshold uint8 PIR Sensor PIR trigger count threshold
0x20 UltrasonicOccupiedToUnoccupiedDelay uint16 Ultrasonic Sensor Ultrasonic occupied-to-unoccupied delay (seconds)
0x21 UltrasonicUnoccupiedToOccupiedDelay uint16 Ultrasonic Sensor Ultrasonic unoccupied-to-occupied delay (seconds)
0x22 UltrasonicUnoccupiedToOccupiedThreshold uint8 Ultrasonic Sensor Ultrasonic trigger count threshold
0x30 PhysicalContactOccupiedToUnoccupiedDelay uint16 Physical Contact Sensor Physical contact occupied-to-unoccupied delay (seconds)
0x31 PhysicalContactUnoccupiedToOccupiedDelay uint16 Physical Contact Sensor Physical contact unoccupied-to-occupied delay (seconds)
0x32 PhysicalContactUnoccupiedToOccupiedThreshold uint8 Physical Contact Sensor Physical contact trigger count threshold

Core State (0x00 - 0x04)

Attributes that all OccupancySensing devices must support, describing the current occupancy state and sensor type.

ID Name Type Access Description
0x00 Occupancy bitmap8 Read-only Bit 0 (SensedOccupancy): 1 = occupied, 0 = unoccupied. Remaining bits are reserved
0x01 OccupancySensorType enum8 Read-only Primary sensor type used by the device (see enum below)
0x02 OccupancySensorTypeBitmap bitmap8 Read-only Bitmap of all sensor types supported by the device (see bit definitions below)
0x03 HoldTime uint16 Read/Write Number of seconds to maintain the "occupied" state after the last occupancy detection. Prevents frequent state toggling during brief absences
0x04 HoldTimeLimits struct Read-only Contains HoldTimeMin, HoldTimeMax, and HoldTimeDefault fields, describing the adjustable range of HoldTime
Occupancy Is a Bitmap, Not a Boolean

The type of Occupancy is bitmap8, not bool. Only bit 0 (SensedOccupancy) indicates occupancy state; the remaining bits are reserved for future use. When reading, use bitwise operations: isOccupied = (Occupancy & 0x01) != 0 — do not compare directly against 1.

OccupancySensorTypeEnum Enum Values

0
PIR Passive Infrared — detects changes in body heat radiation; the most common type
1
Ultrasonic Ultrasonic — emits ultrasonic waves and detects reflection changes; suitable for detecting subtle movements
2
PIRAndUltrasonic PIR + Ultrasonic dual detection; higher accuracy with fewer false positives
3
PhysicalContact Physical Contact — pressure sensors, seat occupancy sensors, etc.

OccupancySensorTypeBitmap Bit Definitions

bit 0
PIR Supports passive infrared sensing
bit 1
Ultrasonic Supports ultrasonic sensing
bit 2
PhysicalContact Supports physical contact sensing
What HoldTime Does

Imagine a meeting room occupancy sensor: someone briefly steps out to get water, and you don't want the lights to turn off immediately. HoldTime is this "grace period" — setting it to 30 seconds means the device will maintain the "occupied" state for 30 seconds after the last detection, before switching to "unoccupied." Apps can let users adjust this value within the HoldTimeLimits range.

↑ Back to Attributes

PIR Sensor Parameters (0x10 - 0x12)

Only relevant when OccupancySensorType is PIR (0) or PIRAndUltrasonic (2). Controls the delay and sensitivity of PIR sensor state transitions.

ID Name Type Access Description
0x10 PIROccupiedToUnoccupiedDelay uint16 Read/Write Delay in seconds before switching to "unoccupied" after PIR no longer detects occupancy. Default 0 (immediate transition)
0x11 PIRUnoccupiedToOccupiedDelay uint16 Read/Write Delay in seconds before switching to "occupied" after PIR detects occupancy. Used to filter momentary false triggers
0x12 PIRUnoccupiedToOccupiedThreshold uint8 Read/Write Number of occupancy events required within the delay period to trigger a state transition. Range 1~254, default 1
Using Delay and Threshold Together

For example, with PIRUnoccupiedToOccupiedDelay = 10 and PIRUnoccupiedToOccupiedThreshold = 3: the sensor must detect 3 occupancy events within 10 seconds before transitioning from "unoccupied" to "occupied." This combination effectively filters false triggers from pets passing by, curtains moving, etc.

↑ Back to Attributes

Ultrasonic Sensor Parameters (0x20 - 0x22)

Only relevant when OccupancySensorType is Ultrasonic (1) or PIRAndUltrasonic (2). Parameter semantics are fully symmetric with the PIR group.

ID Name Type Access Description
0x20 UltrasonicOccupiedToUnoccupiedDelay uint16 Read/Write Delay in seconds before switching to "unoccupied" after ultrasonic sensor no longer detects occupancy. Default 0
0x21 UltrasonicUnoccupiedToOccupiedDelay uint16 Read/Write Delay in seconds before switching to "occupied" after ultrasonic sensor detects occupancy
0x22 UltrasonicUnoccupiedToOccupiedThreshold uint8 Read/Write Number of occupancy events required within the delay period to trigger a state transition. Range 1~254, default 1

↑ Back to Attributes

Physical Contact Sensor Parameters (0x30 - 0x32)

Only relevant when OccupancySensorType is PhysicalContact (3). Parameter semantics are fully symmetric with the PIR group.

ID Name Type Access Description
0x30 PhysicalContactOccupiedToUnoccupiedDelay uint16 Read/Write Delay in seconds before switching to "unoccupied" after physical contact sensor no longer detects occupancy. Default 0
0x31 PhysicalContactUnoccupiedToOccupiedDelay uint16 Read/Write Delay in seconds before switching to "occupied" after physical contact sensor detects occupancy
0x32 PhysicalContactUnoccupiedToOccupiedThreshold uint8 Read/Write Number of occupancy events required within the delay period to trigger a state transition. Range 1~254, default 1

↑ Back to Attributes

Example Data

A typical read result from an OccupancySensing Cluster on a PIR occupancy sensor:

{
  // --- Core State ---
  "0x0": 1,              // Occupancy = 0b00000001 (bit 0 = 1, occupancy detected)
  "0x1": 0,              // OccupancySensorType = PIR (Passive Infrared)
  "0x2": 1,              // OccupancySensorTypeBitmap = 0b00000001 (PIR)

  // --- PIR Sensor Parameters ---
  "0x10": 0,             // PIROccupiedToUnoccupiedDelay = 0 seconds (immediate transition)
  "0x11": 10,            // PIRUnoccupiedToOccupiedDelay = 10 seconds (delayed transition)
  "0x12": 1,             // PIRUnoccupiedToOccupiedThreshold = 1 (triggers on 1 event)

  // --- Hold Time ---
  "0x3": 30,             // HoldTime = 30 seconds
  "0x4": {               // HoldTimeLimits
    "HoldTimeMin": 1,
    "HoldTimeMax": 600,
    "HoldTimeDefault": 10
  }
}

Usage Scenarios

OccupancySensing is one of the core trigger sources for smart home automation. Below are three typical integration scenarios.

Scenario 1: Smart Home Automation (Lighting Control)

The most classic use case — lights on when someone enters, lights off when they leave.

  1. Subscribe to Occupancy (0x00) attribute changes
  2. When Occupancy bit 0 changes from 0 to 1 (someone enters), send the OnOff Cluster On command to turn on the lights
  3. When Occupancy bit 0 changes from 1 to 0 (no one present), send the Off command to turn off the lights
  4. Adjust HoldTime to control the turn-off delay — 300 seconds (5 minutes) is recommended for meeting rooms, 30 seconds for hallways

Advanced: Combine with the LevelControl Cluster to set brightness to 20% at night and 100% during the day when occupancy is detected. You can also combine multiple sensors for zone-based automation — a hallway sensor triggers both the hallway lights and the destination room lights.

Scenario 2: HVAC Energy Saving Integration

Link occupancy sensing with the Thermostat Cluster to achieve "comfort when present, energy saving when away."

  1. Subscribe to Occupancy (0x00) attribute changes
  2. When occupancy is detected, set the Thermostat's OccupiedCoolingSetpoint / OccupiedHeatingSetpoint to comfort temperatures (e.g., 24°C / 22°C)
  3. When no occupancy is detected (after the HoldTime delay), switch to UnoccupiedCoolingSetpoint / UnoccupiedHeatingSetpoint energy-saving temperatures (e.g., 28°C / 18°C)
  4. Recommend setting HoldTime to 600~900 seconds (10~15 minutes) to avoid temperature changes during brief absences

Note: The Thermostat Cluster itself has an Occupancy attribute (0x02), but it only passively receives state. The actual occupancy detection data comes from the OccupancySensing Cluster, typically bridged via automation rules.

Scenario 3: Security and Intrusion Detection

After the user arms the system upon leaving home, occupancy sensors trigger alarms when abnormal activity is detected.

  1. The user enables "Away Mode" (armed) via the app
  2. Subscribe to Occupancy (0x00) changes from all occupancy sensors
  3. When Occupancy bit 0 = 1 is detected while armed, trigger security actions:
    • Push alarm notifications to the user's phone
    • Start camera recording
    • Activate sirens and strobe lights
  4. To reduce false alarms, increase sensitivity requirements: PIRUnoccupiedToOccupiedThreshold = 3, PIRUnoccupiedToOccupiedDelay = 5

Tip: For security scenarios, PIRAndUltrasonic dual-mode sensors are recommended. PIR alone is prone to false triggers from pets; ultrasonic provides secondary confirmation. Also be sure to distinguish between sensors in armed zones and those in unarmed zones.

Developer Advice

A typical workflow for displaying occupancy sensor state in an app:

  1. Read OccupancySensorType (0x01) and display the appropriate sensor type icon and name in the UI
  2. Subscribe to Occupancy (0x00), use bitwise & 0x01 to extract bit 0, and show "Occupied / Unoccupied" status
  3. Based on the sensor type, only show the relevant delay/threshold settings (e.g., don't show ultrasonic parameters for a PIR device)
  4. Allow users to adjust HoldTime within the HoldTimeLimits range — a slider control is more intuitive
  5. Provide event history — record the timestamp of each occupancy state change to help users understand activity patterns