# ESP32 LED Controller — UDP Protocol Reference

**Version:** 1 (`"v":1` required in every command)
**Transport:** UDP
**Port:** 4210
**Max payload:** 512 bytes

## Zones

| Zone value | Strip | LEDs | Protocol |
|------------|-------|------|----------|
| `"schrank"` | WS2801 (Schrank, cabinet) | 160 | SPI RGB |
| `"wand"` | SK6812 (Wand, wall) | 300 | RMT RGBW |
| `"all"` | Both strips | 460 | — |

## Commands

### Run Animation

```json
{"v":1,"zone":"wand","animation":"chase","params":{"speed":0.5,"intensity":1.0,"colors":[[255,0,0,0]]}}
```

Fields:
- `zone` (required): `"schrank"`, `"wand"`, or `"all"`
- `animation` (required): see Animation List below
- `params.speed` (optional, 0.0–1.0, default 0.5): animation tempo multiplier
- `params.intensity` (optional, 0.0–1.0, default 1.0): brightness multiplier
- `params.colors` (optional): array of `[R,G,B,W]` arrays (W=0 → auto-derived on RGBW strip)
- `params.direction` (optional, 0 or 1): forward/reverse

### Stop Animation

```json
{"v":1,"cmd":"stop","zone":"all"}
```

### Set Brightness

```json
{"v":1,"cmd":"brightness","zone":"all","value":40}
```

`value`: 0–60 (firmware enforces max 60% for safety)

### Query Status

```json
{"v":1,"cmd":"status"}
```

Response (UDP to sender IP:port):

```json
{"v":1,"status":"ok","wand":"chase","schrank":"breathe","brightness":40}
```

## Animation List

| Name | Effect | Key params |
|------|--------|------------|
| `chase` | Moving window of lit LEDs along strip | speed, colors[0] |
| `pulse` | All LEDs pulse to sine wave | speed, colors[0] |
| `rainbow` | HSV rainbow sweeps across strip | speed |
| `strobe` | Rapid on/off flash | speed (flash rate), colors[0] |
| `color_wash` | Cross-fades through palette colors | speed, colors[] |
| `breathe` | Slow brightness inhale/exhale | speed, colors[0] |
| `sparkle` | Random pixels flash | intensity, colors[0] |
| `gradient_sweep` | Gradient between 2 colors sweeps | speed, colors[0..1] |

## Error Handling

- Unknown commands → silently ignored, logged to ESP32 serial console
- Malformed JSON → silently dropped, logged to serial console
- Wrong version (`"v"` != 1) → dropped
- No UDP error responses on error (check serial console for debugging)

## Timing

- Animation tick rate: 50fps (20ms)
- UDP → animation start latency: <50ms (queue drain on next tick)
- WiFi disconnect: last animation continues, UDP server restarts on reconnect