Skip to content

Add bidirectional ESP-NOW API - #5737

Closed
figamore wants to merge 18 commits into
wled:mainfrom
figamore:feature/bidirectional-espnow
Closed

figamore wants to merge 18 commits into
wled:mainfrom
figamore:feature/bidirectional-espnow

Conversation

@figamore

@figamore figamore commented Jul 15, 2026

Copy link
Copy Markdown

This PR adds a bidirectional ESP-NOW API for remote controllers while preserving the existing WiZ remote and WLED-to-WLED ESP-NOW sync behavior.

Linked remotes can leverage this API to:

  • Send WLED JSON state commands with /json/state-compatible behavior
  • Request full or compact state responses
  • Receive state updates when WLED changes
  • Discover multiple WLED instances and identify their capabilities
  • Request effect, palette, and preset catalogs
  • Subscribe to binary live LED preview frames

A compatible remote implementation is available at:
https://github.com/figamore/wled-touch-remote

Implementation

  • Adds a versioned ESP-NOW wire protocol with request, response, push, discovery, announce, and live-preview message types.
  • Fragments and reassembles messages larger than ESP-NOW's 250-byte frame limit.
  • Processes ESP-NOW callbacks through bounded queues so JSON parsing, filesystem access, and state changes remain in the main loop.
  • Uses the existing deserializeState() path for parity with the HTTP and WebSocket JSON APIs.
  • Adds compact state polling and unsolicited state pushes for lower-overhead remote synchronization.
  • Adds retry deduplication so repeated mutation requests do not apply non-idempotent changes twice.
  • Supports discovery of multiple WLED instances using their link-layer MAC addresses.
  • Keeps the fallback AP and ESP-NOW channel stable while an API remote is active.

Pairing UI

The ESP-NOW section of the WiFi settings page has been enhanced:

  • Recently detected ESP-NOW remotes, including type (Wizmote or bidirectional ESP-NOW) and last-seen time
  • Add/remove controls for linked remotes
  • Manual MAC-address entry with validation
  • Clear guidance that pairing changes require Save & Connect

Firmware-side validation also rejects malformed and duplicate MAC entries.

Compatibility and limitations

  • Existing Wizmote support and WLED-to-WLED ESP-NOW sync remain supported.
  • Full verbose responses are limited to 2048 bytes on ESP8266 and 8192 bytes on ESP32. Compact polling remains available when a full response is too large.
  • State pushes and live-preview frames are best-effort.
  • Only one live-preview subscriber is served at a time.
  • Live preview is limited in resolution and frame rate to avoid starving control traffic.

The complete protocol and remote implementation guidance are documented in docs/espnow-json-protocol.md.

Tests performed

  • npm test
  • Web UI build: npm run build
  • ESP32 firmware build
  • ESP8266 firmware build
  • Tested state requests and responses on hardware
  • Tested unsolicited state updates
  • Tested discovery and multi-device pairing
  • Tested live LED preview
  • Confirmed existing WiZ Mote behavior
  • Tested STA and fallback AP operation
  • Tested across host/remote reconnects

Documentation

  • Adds docs/espnow-json-protocol.md covering framing, fragmentation, discovery, catalogs, reliability, security assumptions, limits, and example messages.

Summary by CodeRabbit

  • New Features

    • Added bidirectional ESP-NOW control for supported ESP32 devices, including JSON state requests, responses, discovery, live LED previews, and state updates.
    • Added catalog queries for effects, palettes, and playlists.
    • Improved ESP-NOW synchronization and connection handling across Wi-Fi and access-point modes.
  • Bug Fixes

    • Strengthened packet validation, sender authorization, duplicate handling, and linked-remote MAC validation.
  • Documentation

    • Added comprehensive ESP-NOW JSON protocol documentation.

Loading
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AI Partly generated by an AI. Make sure that the contributor fully understands the code! enhancement

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants