86 lines
5.3 KiB
Markdown
86 lines
5.3 KiB
Markdown
# 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.
|
||
|
||
## 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](agent-build-instructions.md).
|
||
|
||
## Repository Structure
|
||
|
||
```text
|
||
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**. Ask for confirmation that these were made 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).
|
||
- Make sure AI-generated code is well documented.
|
||
|
||
### 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.
|