Skip to content

Feature: WiFi-only Matter (CHIP) integration for WLED without requiring BLE/Bluetooth #350

@netmindz

Description

@netmindz

Is your feature request related to a problem? Please describe.
WLED-MM currently has no support for the Matter (CHIP) smart home protocol. Existing Matter implementations typically assume BLE is available for initial device commissioning, which adds significant RAM and flash overhead (~60–100KB RAM, ~200KB+ flash for the BT stack) and creates friction on hardware or network environments where Bluetooth is unavailable or undesirable. This makes Matter adoption out of reach for users on classic ESP32 boards, constrained builds, or BLE-restricted network policies.

Describe the solution you'd like
Add WiFi-only Matter (Project CHIP) support to WLED-MM as an opt-in build target or usermod, with the following characteristics:

  • No Bluetooth/BLE required: Commissioning via WiFi Soft-AP rendezvous (as supported by the Matter/CHIP spec and the ESP32 CHIP SDK). CONFIG_BT_ENABLED=n in the ESP32 build — the BLE stack is never compiled in.
  • Rendezvous mode: WiFi Soft-AP: The device creates a Soft-AP (CHIP-XXXX) on first boot. The commissioner (phone/hub) connects to that AP to complete onboarding. A QR code or manual setup code encodes the gateway IP + setup PIN.
  • Standard Matter Light device type: Expose WLED as a Matter Extended Color Light (0x0102) with:
    • On/Off cluster
    • Level Control cluster (brightness)
    • Color Control cluster (HSV, XY, Color Temperature) — driven by WLED's existing colPri[] and bri state
  • CONFIG_RENDEZVOUS_MODE_WIFI=y by default (maps to RendezvousInformationFlags::kWiFi, value 1), so BLE is explicitly disabled in CHIPDeviceManager via SetBLEAdvertisingEnabled(kCHIPoBLEServiceMode_Disabled).
  • Implemented as a WLED-MM usermod (usermod_matter.h) or as a dedicated PlatformIO build environment (esp32_matter_wifi), enabled with -D USERMOD_MATTER or similar build flag.
  • The existing WLED color/brightness state machine drives the Matter Color Control cluster callbacks (emberAfPluginColorControlServerComputePwmFromHsvCallback, etc.).

Describe alternatives you've considered

  • BLE-assisted commissioning: The standard Matter approach, but requires CONFIG_BT_ENABLED=y, consuming ~60–100KB extra RAM on ESP32 classic — leaving very little headroom alongside WLED's WiFi + LED DMA + effects stack.
  • Bypass mode (kNone): Skips commissioning entirely and uses a hardcoded test secret, fine for development but not suitable for production deployment.
  • MQTT / HTTP / Alexa: Already present in WLED-MM but not Matter-compatible — won't appear natively in Apple Home, Google Home, or Amazon Alexa Matter ecosystems.

Additional context

  • The Matter SDK (Project CHIP) for ESP32 already supports WiFi Soft-AP commissioning with no BLE, controlled via RENDEZVOUS_MODE Kconfig in the ESP32 examples. The relevant transport is fully guarded by #if CONFIG_NETWORK_LAYER_BLE, so it compiles out cleanly when BLE is disabled.
  • The color-control-server cluster implementation (src/app/clusters/color-control-server/color-control-server.c) in the CHIP SDK handles HSV, XY, and Color Temperature transitions — the WLED integration only needs to implement the PWM callback (emberAfPluginColorControlServerComputePwmFromHsvCallback) to bridge into WLED's colour state.
  • Memory on classic ESP32 is tight; disabling BLE reclaims the budget needed to run the CHIP stack + WiFi + WLED effects simultaneously.
  • Reference implementation: Project CHIP ESP32 wifi-echo example demonstrates WiFi Soft-AP commissioning with CONFIG_BT_ENABLED=n.

Thank you for your ideas for making WLED better!

Metadata

Metadata

Labels

No labels
No labels

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions