115 lines
2.6 KiB
Markdown
115 lines
2.6 KiB
Markdown
# Box HTTP API
|
|
|
|
## Purpose
|
|
Defines the stable contract between the GUI/CLI and the Box.
|
|
The Box is authoritative; the client only sends commands and reads status.
|
|
|
|
## Prerequisites
|
|
- Box running on `http://127.0.0.1:8000`
|
|
|
|
## Step-by-step
|
|
### Status
|
|
```
|
|
curl http://127.0.0.1:8000/status
|
|
```
|
|
|
|
### Command (example)
|
|
```
|
|
curl -X POST http://127.0.0.1:8000/command \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"command":"nfc_on","payload":{"uid":"UID_1"}}'
|
|
```
|
|
|
|
## GET /status
|
|
Response fields:
|
|
- `box_id`: unique device ID
|
|
- `wifi_state`: `WIFI_UNCONFIGURED | WIFI_CONNECTING | WIFI_ONLINE | WIFI_OFFLINE`
|
|
- `ip_address`: simulated IP (`192.168.4.1` or `127.0.0.1`)
|
|
- `connected_ssid`: connected SSID or `null`
|
|
- `wifi_profiles_count`: number of stored profiles
|
|
- `spotify_status`: `NOT_CONFIGURED | READY`
|
|
- `playback_state`:
|
|
- `state`: `IDLE | PLAYING | PAUSED`
|
|
- `active_uid`
|
|
- `playback_root`
|
|
- `current_file`
|
|
- `file_index`
|
|
- `position`
|
|
- `duration`
|
|
- `volume`
|
|
- `last_error`
|
|
|
|
Example response:
|
|
```
|
|
{
|
|
"box_id": "klangkiste-a9f3k7m2q8",
|
|
"wifi_state": "WIFI_ONLINE",
|
|
"ip_address": "127.0.0.1",
|
|
"connected_ssid": "HomeWiFi",
|
|
"wifi_profiles_count": 1,
|
|
"spotify_status": "READY",
|
|
"playback_state": {
|
|
"state": "PLAYING",
|
|
"active_uid": "UID_1",
|
|
"playback_root": "media/book_1",
|
|
"current_file": "/root/klangkiste/box/data/media/book_1/01.mp3",
|
|
"file_index": 0,
|
|
"position": 42,
|
|
"duration": 180,
|
|
"volume": 40,
|
|
"last_error": null
|
|
}
|
|
}
|
|
```
|
|
|
|
## POST /command
|
|
Request body:
|
|
```
|
|
{
|
|
"command": "nfc_on",
|
|
"payload": { "uid": "UID_1" }
|
|
}
|
|
```
|
|
|
|
Supported commands:
|
|
- `nfc_on` `{ uid }`
|
|
- `nfc_off` `{ uid }`
|
|
- `play_pause`
|
|
- `next`
|
|
- `prev`
|
|
- `volume_up`
|
|
- `volume_down`
|
|
- `vol_up` (alias)
|
|
- `vol_down` (alias)
|
|
- `stop`
|
|
- `trigger_error` `{ type }`
|
|
- `wifi_add_profile` `{ ssid, password, priority? }`
|
|
- `wifi_reset`
|
|
- `spotify_set_tokens` `{ access_token, refresh_token, expires_at, account_id? }`
|
|
- `spotify_clear`
|
|
|
|
Example: add WiFi profile
|
|
```
|
|
curl -X POST http://127.0.0.1:8000/command \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"command":"wifi_add_profile","payload":{"ssid":"HomeWiFi","password":"secret","priority":10}}'
|
|
```
|
|
|
|
Example: set Spotify tokens
|
|
```
|
|
curl -X POST http://127.0.0.1:8000/command \
|
|
-H "Content-Type: application/json" \
|
|
-d '{"command":"spotify_set_tokens","payload":{"access_token":"a","refresh_token":"b","expires_at":123}}'
|
|
```
|
|
|
|
## Checklist
|
|
- ✅ `GET /status` returns JSON
|
|
- ✅ `POST /command` returns `{ "ok": true }`
|
|
- ✅ No secrets appear in `/status`
|
|
|
|
## Troubleshooting
|
|
- 400 responses:
|
|
- Check required fields in the payload.
|
|
- CORS errors:
|
|
- Ensure Box API is running on the expected host/port.
|