SMART LIGHT

Device Type
Smart RGB Light — WiFi-connected LED controller with local button and Matter/MQTT cloud integration

Hardware
chip: ESP32 — board: ESP32-DevKitC — gpios: led_rgb: TBD — three GPIOs for RGB (PWM capable) — button_control: TBD — GPIO with pull-up — status_led: optional — GPIO for feedback — peripherals: RGB LED strip (common cathode or PWM-controlled) · Push button · Optional status LED

Inputs
kind: Button — label: Power/Toggle — hardware: Single push button with pull-up resistor — behavior: Press to toggle light on/off; hold 5+ seconds for factory reset

Outputs
kind: RGB LED — label: Main Light — hardware: RGB LED strip (PWM control on three ESP32 pins) — behavior: Displays color and brightness as set via Matter/MQTT

Connectivity
stack: Matter — transport: WiFi — purpose: Primary cloud control and commissioning · stack: MQTT — transport: WiFi — purpose: Home Assistant integration and secondary control

Commissioning
method: Matter commissioning — payload: QR code or manual pairing code (generated on first boot) — instructions: Device enters commissioning mode on boot or via button long-press; user scans QR code or enters manual code in Matter app to join network

Business Logic
powerOnBehavior: Light turns on to last known color/brightness — automationRules: Responds to Matter scenes and Home Assistant automations — dayToDayOperation: User controls via Matter app, Home Assistant dashboard, or local button; color/brightness adjusted via Matter/MQTT

Factory Reset
trigger: Button held for 5+ seconds — effect: Device resets to factory settings, clears WiFi and Matter credentials, enters commissioning mode

Failure Modes
scenario: WiFi offline — behavior: Local button still toggles light on/off; cloud commands ignored until WiFi returns · scenario: Matter controller unreachable — behavior: MQTT and local button control continue to work · scenario: Power loss — behavior: Light retains last state in flash memory; resumes on power return