Skip to content

Commit dee581f

Browse files
netmindznetmindz
authored
Merge pull request #4858 from wled/copilot/fix-4857
Add comprehensive GitHub Copilot instructions for WLED development workflow
2 parents 3b5c6ca + 7943b00 commit dee581f

File tree

1 file changed

+138
-0
lines changed

1 file changed

+138
-0
lines changed

‎.github/copilot-instructions.md

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# WLED - ESP32/ESP8266 LED Controller Firmware
2+
3+
WLED is a fast and feature-rich implementation of an ESP32 and ESP8266 webserver to control NeoPixel (WS2812B, WS2811, SK6812) LEDs and SPI-based chipsets. The project consists of C++ firmware for microcontrollers and a modern web interface.
4+
5+
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.
6+
7+
## Working Effectively
8+
9+
### Initial Setup
10+
- Install Node.js 20+ (specified in `.nvmrc`): Check your version with `node --version`
11+
- Install dependencies: `npm install` (takes ~5 seconds)
12+
- Install PlatformIO for hardware builds: `pip install -r requirements.txt` (takes ~60 seconds)
13+
14+
### Build and Test Workflow
15+
- **ALWAYS build web UI first**: `npm run build` -- takes 3 seconds. NEVER CANCEL.
16+
- **Run tests**: `npm test` -- takes 40 seconds. NEVER CANCEL. Set timeout to 2+ minutes.
17+
- **Development mode**: `npm run dev` -- monitors file changes and auto-rebuilds web UI
18+
- **Hardware firmware build**: `pio run -e [environment]` -- takes 15+ minutes. NEVER CANCEL. Set timeout to 30+ minutes.
19+
20+
### Build Process Details
21+
The build has two main phases:
22+
1. **Web UI Generation** (`npm run build`):
23+
- Processes files in `wled00/data/` (HTML, CSS, JS)
24+
- Minifies and compresses web content
25+
- Generates `wled00/html_*.h` files with embedded web content
26+
- **CRITICAL**: Must be done before any hardware build
27+
28+
2. **Hardware Compilation** (`pio run`):
29+
- Compiles C++ firmware for various ESP32/ESP8266 targets
30+
- Common environments: `nodemcuv2`, `esp32dev`, `esp8266_2m`
31+
- List all targets: `pio run --list-targets`
32+
33+
## Validation and Testing
34+
35+
### Web UI Testing
36+
- **ALWAYS validate web UI changes manually**:
37+
- Start local server: `cd wled00/data && python3 -m http.server 8080`
38+
- Open `http://localhost:8080/index.htm` in browser
39+
- Test basic functionality: color picker, effects, settings pages
40+
- **Check for JavaScript errors** in browser console
41+
42+
### Code Validation
43+
- **No automated linting configured** - follow existing code style in files you edit
44+
- **Code style**: Use tabs for web files (.html/.css/.js), spaces (2 per level) for C++ files
45+
- **C++ formatting available**: `clang-format` is installed but not in CI
46+
- **Always run tests before finishing**: `npm test`
47+
48+
### Manual Testing Scenarios
49+
After making changes to web UI, always test:
50+
- **Load main interface**: Verify index.htm loads without errors
51+
- **Navigation**: Test switching between main page and settings pages
52+
- **Color controls**: Verify color picker and brightness controls work
53+
- **Effects**: Test effect selection and parameter changes
54+
- **Settings**: Test form submission and validation
55+
56+
## Common Tasks
57+
58+
### Repository Structure
59+
```
60+
wled00/ # Main firmware source (C++)
61+
├── data/ # Web interface files
62+
│ ├── index.htm # Main UI
63+
│ ├── settings*.htm # Settings pages
64+
│ └── *.js/*.css # Frontend resources
65+
├── *.cpp/*.h # Firmware source files
66+
└── html_*.h # Generated embedded web files (DO NOT EDIT)
67+
tools/ # Build tools (Node.js)
68+
├── cdata.js # Web UI build script
69+
└── cdata-test.js # Test suite
70+
platformio.ini # Hardware build configuration
71+
package.json # Node.js dependencies and scripts
72+
.github/workflows/ # CI/CD pipelines
73+
```
74+
75+
### Key Files and Their Purpose
76+
- `wled00/data/index.htm` - Main web interface
77+
- `wled00/data/settings*.htm` - Configuration pages
78+
- `tools/cdata.js` - Converts web files to C++ headers
79+
- `wled00/wled.h` - Main firmware configuration
80+
- `platformio.ini` - Hardware build targets and settings
81+
82+
### Development Workflow
83+
1. **For web UI changes**:
84+
- Edit files in `wled00/data/`
85+
- Run `npm run build` to regenerate headers
86+
- Test with local HTTP server
87+
- Run `npm test` to validate build system
88+
89+
2. **For firmware changes**:
90+
- Edit files in `wled00/` (but NOT `html_*.h` files)
91+
- Ensure web UI is built first (`npm run build`)
92+
- Build firmware: `pio run -e [target]`
93+
- Flash to device: `pio run -e [target] --target upload`
94+
95+
3. **For both web and firmware**:
96+
- Always build web UI first
97+
- Test web interface manually
98+
- Build and test firmware if making firmware changes
99+
100+
## Build Timing and Timeouts
101+
102+
- **Web UI build**: 3 seconds - Set timeout to 30 seconds minimum
103+
- **Test suite**: 40 seconds - Set timeout to 2 minutes minimum
104+
- **Hardware builds**: 15+ minutes - Set timeout to 30+ minutes minimum
105+
- **NEVER CANCEL long-running builds** - PlatformIO downloads and compilation can take significant time
106+
107+
## Troubleshooting
108+
109+
### Common Issues
110+
- **Build fails with missing html_*.h**: Run `npm run build` first
111+
- **Web UI looks broken**: Check browser console for JavaScript errors
112+
- **PlatformIO network errors**: Try again, downloads can be flaky
113+
- **Node.js version issues**: Ensure Node.js 20+ is installed (check `.nvmrc`)
114+
115+
### When Things Go Wrong
116+
- **Clear generated files**: `rm -f wled00/html_*.h` then rebuild
117+
- **Force web UI rebuild**: `npm run build -- --force` or `npm run build -- -f`
118+
- **Clean PlatformIO cache**: `pio run --target clean`
119+
- **Reinstall dependencies**: `rm -rf node_modules && npm install`
120+
121+
## Important Notes
122+
123+
- **DO NOT edit `wled00/html_*.h` files** - they are auto-generated
124+
- **Always commit both source files AND generated html_*.h files**
125+
- **Web UI must be built before firmware compilation**
126+
- **Test web interface manually after any web UI changes**
127+
- **Use VS Code with PlatformIO extension for best development experience**
128+
- **Hardware builds require appropriate ESP32/ESP8266 development board**
129+
130+
## CI/CD Pipeline
131+
The GitHub Actions workflow:
132+
1. Installs Node.js and Python dependencies
133+
2. Runs `npm test` to validate build system
134+
3. Builds web UI with `npm run build`
135+
4. Compiles firmware for multiple hardware targets
136+
5. Uploads build artifacts
137+
138+
Match this workflow in your local development to ensure CI success.

0 commit comments

Comments
 (0)