339 lines
6.5 KiB
Markdown
339 lines
6.5 KiB
Markdown
# WLED Central Controller
|
|
|
|
A web-based central controller for multiple WLED instances, allowing you to discover, manage, group, and schedule actions across your WLED devices.
|
|
|
|
## Features
|
|
|
|
- **Device Management**: Add, edit, and monitor multiple WLED devices
|
|
- **Grouping**: Organize devices into logical groups (e.g., "Living Room", "Garden")
|
|
- **Group Actions**: Apply presets and playlists to individual devices or groups
|
|
- **Scheduling**: Automate preset/playlist changes with cron-based schedules
|
|
- **UK Timezone Support**: All times displayed in Europe/London timezone (dd/MM/yyyy HH:mm format)
|
|
- **RESTful API**: Complete backend API for integration with other systems
|
|
- **Modern UI**: Clean, responsive web interface built with React
|
|
|
|
## Tech Stack
|
|
|
|
### Backend
|
|
- Node.js v20+ with TypeScript
|
|
- Express.js for HTTP API
|
|
- SQLite via Prisma ORM
|
|
- node-cron for scheduling
|
|
- Zod for validation
|
|
|
|
### Frontend
|
|
- React 18 with TypeScript
|
|
- Vite build tool
|
|
- React Router for navigation
|
|
- Luxon for date/time handling
|
|
|
|
## Quick Start with Docker
|
|
|
|
The easiest way to run the WLED Controller is using Docker Compose:
|
|
|
|
```bash
|
|
# Clone the repository
|
|
cd wled-controller
|
|
|
|
# Start the services
|
|
docker-compose up -d
|
|
|
|
# Access the web UI
|
|
# Open http://localhost in your browser
|
|
```
|
|
|
|
The backend API will be available at `http://localhost:3000/api`.
|
|
|
|
## Manual Setup
|
|
|
|
### Backend Setup
|
|
|
|
```bash
|
|
cd backend
|
|
|
|
# Copy environment file
|
|
cp .env.example .env
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Generate Prisma Client
|
|
npm run prisma:generate
|
|
|
|
# Run database migrations
|
|
npm run prisma:migrate
|
|
|
|
# Development mode
|
|
npm run dev
|
|
|
|
# Production build
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
### Frontend Setup
|
|
|
|
```bash
|
|
cd frontend
|
|
|
|
# Copy environment file
|
|
cp .env.example .env
|
|
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Development mode
|
|
npm run dev
|
|
|
|
# Production build
|
|
npm run build
|
|
npm run preview
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Backend Environment Variables
|
|
|
|
Create a `.env` file in the `backend` directory:
|
|
|
|
```env
|
|
PORT=3000
|
|
DATABASE_URL="file:./dev.db"
|
|
LOG_LEVEL=info
|
|
```
|
|
|
|
### Frontend Environment Variables
|
|
|
|
Create a `.env` file in the `frontend` directory:
|
|
|
|
```env
|
|
VITE_API_BASE_URL=http://localhost:3000/api
|
|
```
|
|
|
|
## Usage Guide
|
|
|
|
### 1. Add Devices
|
|
|
|
1. Navigate to the **Devices** page
|
|
2. Click **Add Device**
|
|
3. Enter device details:
|
|
- Name (e.g., "Kitchen Strip")
|
|
- IP Address (e.g., "192.168.1.50")
|
|
- Port (default: 80)
|
|
- Enabled checkbox
|
|
4. Use **Ping** to verify connectivity
|
|
|
|
### 2. Create Groups
|
|
|
|
1. Navigate to the **Groups** page
|
|
2. Click **Create Group**
|
|
3. Enter group name
|
|
4. Select devices to include
|
|
5. Save
|
|
|
|
### 3. Control Groups
|
|
|
|
1. Click **Control** on any group
|
|
2. Apply a preset:
|
|
- Enter preset ID
|
|
- Click **Apply Preset**
|
|
3. Or apply a playlist:
|
|
- Enter comma-separated preset IDs
|
|
- Configure duration, transition, repeat options
|
|
- Click **Apply Playlist**
|
|
|
|
### 4. Schedule Actions
|
|
|
|
1. Navigate to the **Schedules** page
|
|
2. Click **Create Schedule**
|
|
3. Configure:
|
|
- Name
|
|
- Group
|
|
- Type (Preset or Playlist)
|
|
- Cron expression (e.g., `30 18 * * *` for 6:30 PM daily)
|
|
- Timezone (default: Europe/London)
|
|
- Action payload (preset ID or playlist config)
|
|
4. Enable/disable schedules with the toggle
|
|
|
|
## API Documentation
|
|
|
|
### Devices
|
|
|
|
- `GET /api/devices` - List all devices
|
|
- `POST /api/devices` - Create device
|
|
- `GET /api/devices/:id` - Get device
|
|
- `PUT /api/devices/:id` - Update device
|
|
- `DELETE /api/devices/:id` - Delete device
|
|
- `POST /api/devices/:id/ping` - Ping device
|
|
|
|
### Groups
|
|
|
|
- `GET /api/groups` - List all groups
|
|
- `POST /api/groups` - Create group
|
|
- `GET /api/groups/:id` - Get group
|
|
- `PUT /api/groups/:id` - Update group
|
|
- `DELETE /api/groups/:id` - Delete group
|
|
- `POST /api/groups/:id/preset` - Apply preset to group
|
|
- `POST /api/groups/:id/playlist` - Apply playlist to group
|
|
|
|
### Schedules
|
|
|
|
- `GET /api/schedules` - List all schedules
|
|
- `POST /api/schedules` - Create schedule
|
|
- `GET /api/schedules/:id` - Get schedule
|
|
- `PUT /api/schedules/:id` - Update schedule
|
|
- `DELETE /api/schedules/:id` - Delete schedule
|
|
|
|
## WLED Integration
|
|
|
|
The controller communicates with WLED devices over HTTP using the JSON API:
|
|
|
|
- `/json/info` - Device information
|
|
- `/json/state` - Device state and control
|
|
|
|
### Preset Application
|
|
|
|
```json
|
|
POST /json/state
|
|
{
|
|
"ps": 5
|
|
}
|
|
```
|
|
|
|
### Playlist Application
|
|
|
|
```json
|
|
POST /json/state
|
|
{
|
|
"playlist": {
|
|
"ps": [1, 2, 3],
|
|
"dur": [30, 30, 30],
|
|
"transition": 0,
|
|
"repeat": 0,
|
|
"end": 1
|
|
}
|
|
}
|
|
```
|
|
|
|
## Cron Expression Format
|
|
|
|
Schedules use standard cron syntax:
|
|
|
|
```
|
|
* * * * *
|
|
┬ ┬ ┬ ┬ ┬
|
|
│ │ │ │ │
|
|
│ │ │ │ └─ day of week (0-7, 0 and 7 are Sunday)
|
|
│ │ │ └────── month (1-12)
|
|
│ │ └─────────── day of month (1-31)
|
|
│ └──────────────── hour (0-23)
|
|
└───────────────────── minute (0-59)
|
|
```
|
|
|
|
### Examples
|
|
|
|
- `30 18 * * *` - Every day at 6:30 PM
|
|
- `0 9 * * 1-5` - Weekdays at 9:00 AM
|
|
- `*/15 * * * *` - Every 15 minutes
|
|
- `0 22 * * 0` - Sundays at 10:00 PM
|
|
|
|
## Development
|
|
|
|
### Backend Tests
|
|
|
|
```bash
|
|
cd backend
|
|
npm test
|
|
```
|
|
|
|
### Code Formatting
|
|
|
|
```bash
|
|
# Backend
|
|
cd backend
|
|
npm run format
|
|
|
|
# Frontend
|
|
cd frontend
|
|
npm run format
|
|
```
|
|
|
|
### Linting
|
|
|
|
```bash
|
|
# Backend
|
|
cd backend
|
|
npm run lint
|
|
|
|
# Frontend
|
|
cd frontend
|
|
npm run lint
|
|
```
|
|
|
|
## Deployment
|
|
|
|
### Behind a Reverse Proxy
|
|
|
|
The application is designed to work behind HTTPS reverse proxies. Configure your reverse proxy to:
|
|
|
|
1. Serve the frontend on your domain
|
|
2. Proxy `/api/*` requests to the backend
|
|
3. Set appropriate CORS headers if needed
|
|
|
|
Example Nginx configuration:
|
|
|
|
```nginx
|
|
server {
|
|
listen 443 ssl;
|
|
server_name wled.example.com;
|
|
|
|
ssl_certificate /path/to/cert.pem;
|
|
ssl_certificate_key /path/to/key.pem;
|
|
|
|
location / {
|
|
proxy_pass http://localhost:80;
|
|
}
|
|
|
|
location /api {
|
|
proxy_pass http://localhost:3000;
|
|
}
|
|
}
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Device Not Reachable
|
|
|
|
- Verify the device IP address is correct
|
|
- Ensure the device is on the same network
|
|
- Check firewall rules
|
|
- Use the **Ping** button to test connectivity
|
|
|
|
### Schedule Not Triggering
|
|
|
|
- Verify the cron expression is correct
|
|
- Check the schedule is enabled
|
|
- Ensure the group has enabled devices
|
|
- Review backend logs for errors
|
|
|
|
### Database Issues
|
|
|
|
```bash
|
|
cd backend
|
|
|
|
# Reset database
|
|
rm dev.db
|
|
npm run prisma:migrate
|
|
|
|
# View database
|
|
npm run prisma:studio
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Contributing
|
|
|
|
Contributions welcome! Please open an issue or pull request.
|