PresencePixel

Device Type
Matter Occupancy Sensor

Description
Occupancy Sensor is a compact, Matter-native presence sensor for smart homes that uses a self-emitting reflective infrared beam to detect occupancy in a defined zone. It reports real-time occupancy state changes to Apple Home, Google Home, Alexa, or Home Assistant via Wi-Fi, with no cloud dependency or hub lock-in. Users can adjust detection sensitivity via the Matter app and toggle the sensor on/off locally for privacy or testing.

Hardware
chip: ESP32-C3 — board: ESP32-C3-DevKitM-1 v1.0 — gpios: GPIO1: IR sensor analog output (ADC input) — GPIO8: WS2812 RGB LED strip (built-in on devkit) — GPIO9: Control button (built-in BOOT button on devkit) — peripherals: name: M5Stack Unit Reflective IR (U175) — type: Analog IR proximity sensor — voltage: 5V — function: Detects objects/presence via self-emitting IR beam reflection · name: WS2812 RGB LED Strip — type: Addressable RGB LED — function: Status and fault indication · name: BOOT Button — type: Momentary pushbutton — function: Control and reset button — power: input: Micro-USB wall adapter — voltage: 5V DC — operation: Always-on (mains-powered)

Inputs
kind: Occupancy Sensor — label: IR Reflective Beam — hardware: M5Stack Unit Reflective IR (U175) on GPIO 1 (ADC) — behavior: Sampled every 50–100ms; hysteresis debounce with 2s default timeout (configurable 0.5–10s via Matter app); reflects IR off objects in front to detect presence; analog value processed and thresholded to binary occupancy state · kind: Control Button — label: BOOT Button (GPIO 9) — hardware: Built-in pushbutton on devkit — behavior: Short press (< 1s): toggle occupancy sensor on/off (privacy/test mode); Long press (≥5s): factory reset, clear Matter credentials, restore defaults; LED pulses during long press to confirm

Outputs
kind: RGB LED Strip — label: Status & Occupancy Indicator — hardware: WS2812 addressable LED on GPIO 8 — behavior: Off = idle/connected, no presence; Green = occupancy detected, present in zone; Blue breathing = Matter commissioning/pairing mode; Red pulse pattern = sensor fault detected (stuck or unreliable readings); LED also pulses during button long-press (factory reset confirmation) · kind: Matter Occupancy Cluster — label: Occupancy State Report — hardware: Wi-Fi Matter attribute — behavior: Reports binary occupancy state (occupied/not occupied) to Matter network; updates immediately on state change after debounce period; state persists locally during Wi-Fi outage

Connectivity
stack: Matter — transport: Wi-Fi (802.11b/g/n, 2.4 GHz) — purpose: Primary control, status reporting, and commissioning; no hub required; works with Apple Home, Google Home, Alexa, Home Assistant, and all Matter-compatible platforms

Commissioning
method: Matter QR code + manual pairing code — payload: QR code printed on device or in manual; manual 11-digit pairing code as fallback — instructions: 1. Power on Occupancy Sensor via Micro-USB. 2. RGB LED begins breathing blue. 3. Open Matter-compatible app (HomeKit, Google Home, Alexa, Home Assistant). 4. Scan QR code or enter manual pairing code. 5. Assign to room and name. 6. LED turns solid green when occupancy detected or off when idle. Done!

Business Logic
powerOnBehavior: Upon power-up, the sensor initializes: GPIO1 ADC begins sampling the IR sensor; RGB LED is off (idle state). If previously paired with Matter, it attempts to reconnect to Wi-Fi. No presence is assumed until first valid occupancy detection. — dayToDayOperation: User can adjust occupancy timeout (how long to wait before reporting 'not occupied') via the Matter app—default 2s, range 0.5–10s. Short press on the BOOT button toggles occupancy reporting on/off locally (e.g., for privacy during meetings or device testing). The device continuously samples the IR sensor and updates its Matter occupancy attribute as soon as a state change is detected (after debounce). LED provides real-time visual feedback: green when present, off when empty, red pulse if the sensor malfunctions. — automationRules: No on-device automation. All automation rules (e.g., 'turn on light when occupied', 'turn off fan after 5 minutes of no presence') are defined in the user's Matter platform (HomeKit, Home Assistant, etc.). The sensor simply reports state changes—the smart home platform takes action based on those reports.

Factory Reset
trigger: Long-press (≥5s) the BOOT button. RGB LED pulses to confirm the long-press action. — effect: All Matter credentials are cleared; the device returns to initial state (not paired, Wi-Fi disconnected). LED becomes solid blue (commissioning mode). User must re-pair the device with Matter as if it were new.

Failure Modes
scenario: Wi-Fi disconnected — behavior: Sensor continues to sample the IR input and update its internal occupancy state locally. When Wi-Fi reconnects, any pending state changes are synchronized to Matter (local persistence prevents 'gaps' in occupancy history). Device remains functional even if cloud services are unreachable. · scenario: Power loss and restoration — behavior: Upon power return, the device initializes with no stored presence state. It assumes 'not occupied' until the first occupancy event is detected. This ensures the device doesn't incorrectly report a stale occupancy state after a power outage. · scenario: Sensor stuck (ADC reading constant at min or max) — behavior: Internal watchdog detects a sensor reading that does not change for >30s. RGB LED shifts to red pulse pattern to indicate a fault. Device continues to operate but reports 'sensor fault' status to Matter (may be exposed via diagnostic cluster). User should check for obstructions (dust, condensation, direct sunlight) or reset the device. · scenario: Sensor noise / rapid fluctuations — behavior: Hysteresis debounce logic (2s timeout, default) prevents rapid occupancy state toggles. Even if the sensor reading oscillates around the threshold, the reported occupancy state remains stable, avoiding spurious updates to Matter. · scenario: Button held during power-up — behavior: If the BOOT button is held during power-on, the device enters bootloader mode. Release the button and the device initializes normally. This is not a customer-facing scenario but noted for development.

Power Management
batteryPowered: false — mains: Micro-USB 5V wall adapter, continuous operation

Custom Behavior
rangeTuning: Detection sensitivity/range is not adjustable via hardware (no manual potentiometer). Instead, the occupancy timeout is configurable via Matter app (0.5–10s, default 2s). A longer timeout makes the device 'stickier' (presence persists longer after an object leaves), effectively extending the detection range in perception. — privacyMode: Short-press the BOOT button to toggle the occupancy sensor on/off locally. When off, the sensor still samples the IR input internally but does not report state changes to Matter. This allows users to block occupancy detection during calls, private moments, or when the device should not trigger automations. LED remains off during privacy mode.