Introduction
# WLED Control
Control WLED LED strips and matrices via the HTTP JSON API.
## Requirements
- WLED device on the same network - Device IP address or hostname - Python 3 (no external dependencies)
## Usage
All commands require `--host` (or `-H`) with the WLED device IP/hostname.
### Power Control
```bash python3 scripts/wled.py -H <ip> power # Get power state python3 scripts/wled.py -H <ip> power on # Turn on python3 scripts/wled.py -H <ip> power off # Turn off ```
### Brightness
```bash python3 scripts/wled.py -H <ip> brightness # Get current brightness python3 scripts/wled.py -H <ip> brightness 255 # Max brightness python3 scripts/wled.py -H <ip> brightness 128 # 50% brightness ```
### Colors
```bash python3 scripts/wled.py -H <ip> color 255 0 0 # Red python3 scripts/wled.py -H <ip> color 0 255 0 # Green python3 scripts/wled.py -H <ip> color 0 0 255 # Blue python3 scripts/wled.py -H <ip> color 255 255 255 # White ```
### Effects
```bash python3 scripts/wled.py -H <ip> effects # List all effects with IDs python3 scripts/wled.py -H <ip> effect 0 # Solid color python3 scripts/wled.py -H <ip> effect 9 # Rainbow python3 scripts/wled.py -H <ip> effect 9 -s 200 # Rainbow, fast speed python3 scripts/wled.py -H <ip> effect 9 -i 128 # Rainbow, medium intensity ```
### Palettes
```bash python3 scripts/wled.py -H <ip> palettes # List all palettes with IDs python3 scripts/wled.py -H <ip> palette 6 # Set Party palette ```
### Presets
```bash python3 scripts/wled.py -H <ip> presets # List saved presets python3 scripts/wled.py -H <ip> preset 1 # Load preset #1 ```
### Status
```bash python3 scripts/wled.py -H <ip> status # Full device status ```
## Reference
See [references/api.md](references/api.md) for complete API documentation.
## Configuration
Avoid passing `--host` every time by creating a config file at `~/.wled/config.json`:
```json { "bedroom": "192.168.1.100", "kitchen": "192.168.1.101", "living_room": "wled-abc123.local" } ```
Then use aliases: ```bash python3 scripts/wled.py -H bedroom brightness 255 python3 scripts/wled.py -H kitchen color 255 0 0 ```
Or set the `WLED_HOST` environment variable: ```bash export WLED_HOST=192.168.1.100 python3 scripts/wled.py brightness 255 ```
## Finding Your WLED Device
WLED devices can typically be found via: - Router admin panel (look for ESP device) - mDNS/Bonjour: `wled-<mac>.local` - WLED app discovery
## Static IP Recommendation
IP addresses change over time. To avoid updating your config, **set a static IP** on your WLED device:
**Option 1: Router-based (easiest)** 1. Open your router admin panel 2. Find the WLED device by MAC address 3. Reserve/assign a static IP
**Option 2: On-device** 1. Access WLED web UI at `http://<current-ip>` 2. Go to Settings → WiFi Settings 3. Set static IP manually 4. Save and reboot
Using mDNS hostnames (e.g., `wled-abc123.local`) also avoids IP tracking—routers resolve these automatically.