libraries/Matter/examples/MatterOccupancySensor/README.md
This example demonstrates how to create a Matter-compatible occupancy sensor device using an ESP32 SoC microcontroller.
The application showcases Matter commissioning, sensor data reporting to smart home ecosystems, and automatic simulation of occupancy state changes.
| SoC | Wi-Fi | Thread | BLE Commissioning | Status |
|---|---|---|---|---|
| ESP32 | ✅ | ❌ | ❌ | Fully supported |
| ESP32-S2 | ✅ | ❌ | ❌ | Fully supported |
| ESP32-S3 | ✅ | ❌ | ✅ | Fully supported |
| ESP32-C3 | ✅ | ❌ | ✅ | Fully supported |
| ESP32-C5 | ❌ | ✅ | ✅ | Supported (Thread only) |
| ESP32-C6 | ✅ | ❌ | ✅ | Fully supported |
| ESP32-H2 | ❌ | ✅ | ✅ | Supported (Thread only) |
BOOT_PIN by defaultMatterWi-Fi (only for ESP32 and ESP32-S2)Before uploading the sketch, configure the following:
Wi-Fi credentials (if not using BLE commissioning - mandatory for ESP32 | ESP32-S2):
const char *ssid = "your-ssid"; // Change to your Wi-Fi SSID
const char *password = "your-password"; // Change to your Wi-Fi password
Button pin configuration (optional):
By default, the BOOT button (GPIO 0) is used for factory reset. You can change this to a different pin if needed.
const uint8_t buttonPin = BOOT_PIN; // Set your button pin here
PIR sensor pin configuration (optional, if using a real PIR sensor):
const uint8_t pirPin = 4; // Set your PIR sensor pin here
See the "PIR Sensor Integration Example" section below for complete integration instructions.
MatterOccupancySensor.ino sketch in the Arduino IDE.Once the sketch is running, open the Serial Monitor at a baud rate of 115200. The Wi-Fi connection messages will be displayed only for ESP32 and ESP32-S2. Other targets will use Matter CHIPoBLE to automatically setup the IP Network. You should see output similar to the following, which provides the necessary information for commissioning:
Connecting to your-wifi-ssid
.......
Wi-Fi connected
IP address: 192.168.1.100
Matter Node is not commissioned yet.
Initiate the device discovery in your Matter environment.
Commission it to your Matter hub with the manual pairing code or QR code
Manual pairing code: 34970112332
QR code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=MT%3A6FCJ142C00KA0648G00
Matter Node not commissioned yet. Waiting for commissioning.
Matter Node not commissioned yet. Waiting for commissioning.
...
Matter Node is commissioned and connected to the network. Ready for use.
After commissioning, the occupancy sensor will automatically toggle between occupied and unoccupied states every 2 minutes, and the Matter controller will receive these state updates.
The user button (BOOT button by default) provides factory reset functionality:
The example includes a simulated occupancy sensor that:
To use a real occupancy sensor, replace the simulatedHWOccupancySensor() function with your sensor library code.
Here's a complete example for integrating a simple PIR (Passive Infrared) motion sensor:
Connect the PIR sensor to your ESP32:
Common PIR sensors (HC-SR501, AM312, etc.) typically have three pins: VCC, GND, and OUT (digital output).
// PIR sensor pin
const uint8_t pirPin = 4; // Change this to your PIR sensor pin
void setup() {
// ... existing code ...
pinMode(buttonPin, INPUT_PULLUP);
// Initialize PIR sensor pin
pinMode(pirPin, INPUT);
// ... rest of setup code ...
}
bool simulatedHWOccupancySensor() {
// Read PIR sensor digital input
// HIGH = motion detected (occupied), LOW = no motion (unoccupied)
return digitalRead(pirPin) == HIGH;
}
Here's the complete modified function with debouncing for more reliable readings:
bool simulatedHWOccupancySensor() {
// Read PIR sensor with debouncing
static bool lastState = false;
static uint32_t lastChangeTime = 0;
const uint32_t debounceTime = 100; // 100ms debounce
bool currentState = digitalRead(pirPin) == HIGH;
// Only update if state has changed and debounce time has passed
if (currentState != lastState) {
if (millis() - lastChangeTime > debounceTime) {
lastState = currentState;
lastChangeTime = millis();
Serial.printf("Occupancy state changed: %s\r\n", currentState ? "OCCUPIED" : "UNOCCUPIED");
}
}
return lastState;
}
After making these changes:
Use a Matter-compatible hub (like an Apple HomePod, Google Nest Hub, or Amazon Echo) to commission the device.
The MatterOccupancySensor example consists of the following main components:
setup(): Initializes hardware (button), configures Wi-Fi (if needed), sets up the Matter Occupancy Sensor endpoint with initial state (unoccupied), and waits for Matter commissioning.
loop(): Handles button input for factory reset, continuously checks the simulated occupancy sensor and updates the Matter attribute, and allows the Matter stack to process events.
simulatedHWOccupancySensor(): Simulates a hardware occupancy sensor by toggling the occupancy state every 2 minutes. Replace this function with your actual sensor reading code.
Arduino IDE Menu -> Tools -> Erase All Flash Before Sketch Upload: "Enabled" or directly with esptool.py --port <PORT> erase_flashThis example is licensed under the Apache License, Version 2.0.