alexei.dolgolyov
ec3c40d59c
Some checks failed
Validate / validate (push) Failing after 9s
Server fixes: - Fix numpy uint8 JSON serialization by converting to Python int - Change WLED payload to flat array format [r,g,b,r,g,b,...] - Add payload debugging logs (size, LED count, sample data) Web UI improvements: - Add comprehensive console logging for device errors - Log actual error messages from state.errors array - Log device operations (start/stop/add) with details - Fix password field form validation warning The HTTP API may have payload size limitations for large LED counts. Consider UDP protocols (DDP/E1.31) for better real-time performance. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
93 lines
3.3 KiB
Markdown
93 lines
3.3 KiB
Markdown
# Claude Instructions for WLED Screen Controller Server
|
|
|
|
## Development Workflow
|
|
|
|
### Server Restart Policy
|
|
|
|
**IMPORTANT**: When making changes to server code (Python files in `src/wled_controller/`), you MUST restart the server if it's currently running to ensure the changes take effect.
|
|
|
|
#### When to restart:
|
|
- After modifying API routes (`api/routes.py`, `api/schemas.py`)
|
|
- After updating core logic (`core/*.py`)
|
|
- After changing configuration (`config.py`)
|
|
- After modifying utilities (`utils/*.py`)
|
|
- After updating data models or database schemas
|
|
|
|
#### How to check if server is running:
|
|
```bash
|
|
# Look for running Python processes with wled_controller
|
|
ps aux | grep wled_controller
|
|
# Or check for processes listening on port 8080
|
|
netstat -an | grep 8080
|
|
```
|
|
|
|
#### How to restart:
|
|
1. Stop the current server (if running as background task, use TaskStop with the task ID)
|
|
2. Start a new server instance:
|
|
```bash
|
|
cd server && python -m wled_controller.main
|
|
```
|
|
3. Verify the new server started successfully by checking the output logs
|
|
|
|
#### Files that DON'T require restart:
|
|
- Static files (`static/*.html`, `static/*.css`, `static/*.js`) - these are served directly
|
|
- Locale files (`static/locales/*.json`) - loaded by frontend
|
|
- Documentation files (`*.md`)
|
|
- Configuration files in `config/` if server supports hot-reload (check implementation)
|
|
|
|
### Testing Changes
|
|
|
|
After restarting the server with new code:
|
|
1. Test the modified endpoints/functionality
|
|
2. Check browser console for any JavaScript errors
|
|
3. Verify API responses match updated schemas
|
|
4. Test with different locales if i18n was modified
|
|
|
|
## Project Structure Notes
|
|
|
|
- `src/wled_controller/main.py` - FastAPI application entry point
|
|
- `src/wled_controller/api/` - REST API endpoints and schemas
|
|
- `src/wled_controller/core/` - Core business logic (screen capture, WLED client, processing)
|
|
- `src/wled_controller/utils/` - Utility functions (logging, monitor detection)
|
|
- `src/wled_controller/static/` - Frontend files (HTML, CSS, JS, locales)
|
|
- `config/` - Configuration files (YAML)
|
|
- `data/` - Runtime data (devices.json, persistence)
|
|
|
|
## Common Tasks
|
|
|
|
### Adding a new API endpoint:
|
|
1. Add route to `api/routes.py`
|
|
2. Define request/response schemas in `api/schemas.py`
|
|
3. **Restart the server**
|
|
4. Test the endpoint via `/docs` (Swagger UI)
|
|
|
|
### Adding a new field to existing API:
|
|
1. Update Pydantic schema in `api/schemas.py`
|
|
2. Update corresponding dataclass (if applicable)
|
|
3. Update backend logic to populate the field
|
|
4. **Restart the server**
|
|
5. Update frontend to display the new field
|
|
|
|
### Modifying display/monitor detection:
|
|
1. Update functions in `utils/monitor_names.py` or `core/screen_capture.py`
|
|
2. **Restart the server**
|
|
3. Test with `GET /api/v1/config/displays`
|
|
|
|
### Modifying server login:
|
|
1. Update the logic.
|
|
2. **Restart the server**
|
|
|
|
### Adding translations:
|
|
1. Add keys to `static/locales/en.json` and `static/locales/ru.json`
|
|
2. Add `data-i18n` attributes to HTML elements in `static/index.html`
|
|
3. Use `t('key')` function in `static/app.js` for dynamic content
|
|
4. No server restart needed (frontend only)
|
|
|
|
## Authentication
|
|
|
|
Server uses API key authentication. Keys are configured in:
|
|
- `config/default_config.yaml` under `auth.api_keys`
|
|
- Or via environment variables: `WLED_AUTH__API_KEYS`
|
|
|
|
For development, ensure at least one API key is configured or the server won't start.
|