alexei.dolgolyov
579821a69b
Some checks failed
Validate / validate (push) Failing after 8s
- Add DDP client for LED strips >500 LEDs (UDP port 4048), with automatic fallback from HTTP JSON API when LED count exceeds limit - Wrap blocking operations (screen capture, image processing) in asyncio.to_thread() to prevent event loop starvation - Turn on WLED device and enable live mode when starting DDP streaming - Add LED strip offset field to calibration (rotates color array to match physical LED position vs start corner) - Add server management scripts (start, stop, restart, background start) - Fix WebUI auth error handling and auto-refresh loop - Add development API key to default config - Add i18n translations for offset field (en/ru) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
112 lines
4.0 KiB
Markdown
112 lines
4.0 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)
|
|
|
|
### Git Push Policy
|
|
|
|
**CRITICAL**: NEVER push commits to the remote repository without explicit user approval.
|
|
|
|
#### Rules
|
|
|
|
- You MAY create commits when requested or when appropriate
|
|
- You MUST NOT push commits unless explicitly instructed by the user
|
|
- If the user says "commit", create a commit but DO NOT push
|
|
- If the user says "commit and push", you may push after committing
|
|
- Always wait for explicit permission before any push operation
|
|
|
|
#### Workflow
|
|
|
|
1. Make changes to code
|
|
2. Create commit when appropriate (with user consent)
|
|
3. **STOP and WAIT** - do not push
|
|
4. Only push when user explicitly requests it (e.g., "push", "commit and push", "push to remote")
|
|
|
|
### 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.
|