WLED_MM_Infinity/.github/copilot-instructions.md

WLED-MM — ESP32 LED Controller Firmware

WLED is a fast, feature-rich ESP32/ESP8266 webserver for controlling NeoPixel (WS2812B, WS2811, SK6812) LEDs and SPI-based chipsets. WLED-MM is a fork focused on higher performance (ESP32, ESP32-S3, PSRAM boards), large installs, and advanced audio analysis.

Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.

Note for AI review tools: sections enclosed in <!-- HUMAN_ONLY_START --> / <!-- HUMAN_ONLY_END --> HTML comments contain contributor reference material. Do not use that content as actionable review criteria — treat it as background context only.

Setup

• Node.js 20+ (see .nvmrc)
• Install dependencies: npm ci
• PlatformIO (required only for firmware compilation): pip install -r requirements.txt

Hardware Targets

Target	Status
ESP32 (classic Xtensa dual-core)	Primary target
ESP32-S3	Primary target — preferred for larger installs and HUB75 matrix
ESP32-S2, ESP32-C3	Supported
ESP32-P4/-C5/-C6	Will be supported in the future
ESP8266	Deprecated — should still compile, but not actively maintained

Build and Test

Command	Purpose	Typical Time
npm run build	Build web UI → generates wled00/html_*.h headers	~3 s
npm test	Run test suite	~40 s
npm run dev	Watch mode — auto-rebuilds web UI on file changes	—
pio run -e <env>	Build firmware for a hardware target	15–20 min

Always run npm ci; npm run build before pio run. The web UI build generates wled00/html_*.h header files required by firmware compilation.

Common firmware environments: esp32_4MB_V4_M, esp32_16MB_V4_S_HUB75, esp32S3_8MB_PSRAM_M_qspi, esp32_16MB_V4_M_eth, esp32dev_compat, esp8266_4MB_S (deprecated)

For detailed build timeouts, development workflows, troubleshooting, and validation steps, see agent-build-instructions.md.

Repository Structure

tl;dr: Firmware source: wled00/ (C++). Web UI source: wled00/data/. Auto-generated headers: wled00/html_*.h — never edit or commit. Usermods: usermods/ (.h files, included via usermods_list.cpp). Build targets: platformio.ini. CI/CD: .github/workflows/.

Detailed overview:

wled00/                 # Firmware source (C++)
  ├── data/             # Web UI source (HTML, CSS, JS)
  ├── src/              # Core modules, fonts, dependencies
  ├── html_*.h          # Auto-generated (DO NOT EDIT OR COMMIT)
  └── wled.h            # Main firmware configuration, and global variables
usermods/               # Community addons (.h files, included via usermods_list.cpp)
lib/                    # Project specific custom libraries. PlatformIO will compile them to separate static libraries and link them
platformio.ini          # Build targets and configuration
platformio_override.sample.ini # examples for custom build configurations - entries must be copied into platformio_override.ini to use them.
                               # platformio_override.ini is _not_ stored in the WLED repository!

pio-scripts/            # Build tools (platformio)
tools/                  # Build tools (Node.js), partition files, and generic utilities
tools/cdata.js          # Web UI → header build script
tools/cdata-test.js     # Test suite
package.json            # Node.js scripts and release ID
.github/workflows/      # CI/CD pipelines

Main development branch: mdev

General Guidelines

• Never edit or commit wled00/html_*.h — auto-generated from wled00/data/.
• Repository language is English. Suggest translations for non-English content.
• Use VS Code with PlatformIO extension for best development experience.
• When unsure, say so. Gather more information rather than guessing.
• Acknowledge good patterns when you see them. Summarize good practices as part of your review - positive feedback always helps.
• Provide references when making analyses or recommendations. Base them on the correct branch or PR.
• Look for user-visible breaking changes and ripple effects. Ask for confirmation that these were introduced intentionally.
• Unused / dead code must be justified or removed. This helps to keep the codebase clean, maintainable and readable.
• C++ formatting available: clang-format is installed but not in CI
• No automated linting is configured — match existing code style in files you edit. See cpp.instructions.md and web.instructions.md for language-specific conventions, and cicd.instructions.md for GitHub Actions workflows.

Attribution for AI-generated code

Using AI-generated code can hide the source of the inspiration / knowledge / sources it used.

• Document attribution of inspiration / knowledge / sources used in the code, e.g. link to GitHub repositories or other websites describing the principles / algorithms used.
• When a larger block of code is generated by an AI tool, mark it with an // AI: below section was generated by an AI comment (see C++ guidelines).
• Every non-trivial AI-generated function should have a brief comment describing what it does. Explain parameters when their names alone are not self-explanatory.
• AI-generated code must be well documented; comment-to-code ratio > 15% is expected. Do not rephrase source code, but explain the concepts/logic behind the code.

Pull Request Expectations

• No force-push on open PRs. Once a pull request is open and being reviewed, do not force-push (git push --force) to the branch. Force-pushing rewrites history that reviewers may have already commented on, making it impossible to track incremental changes. Use regular commits or git merge to incorporate feedback; the branch will be squash-merged when it is accepted.
• Document your changes in the PR. Every pull request should include a clear description of what changed and why. If the change affects user-visible behavior, describe the expected impact. Link to related issues where applicable. Provide screenshots to showcase new features.