Box HTTP API

Zweck

Stabiler Vertrag zwischen GUI/CLI und Box. Die Box ist autoritativ, der Client sendet nur Commands und liest Status.

Voraussetzungen

Box laeuft auf http://127.0.0.1:8000

Schritt-fuer-Schritt

Status

curl http://127.0.0.1:8000/status

Command (Beispiel)

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

Felder:

box_id: eindeutige Box-ID
pairing_state: UNPAIRED | PAIRING_PENDING | PAIRED
wifi_state: WIFI_UNCONFIGURED | WIFI_CONNECTING | WIFI_ONLINE | WIFI_OFFLINE
ip_address: simulierte IP (192.168.4.1 oder 127.0.0.1)
connected_ssid: verbundene SSID oder null
wifi_profiles_count: Anzahl gespeicherter Profile
spotify_status: NOT_CONFIGURED | READY
last_nfc:
- uid: letzte erkannte UID oder null
- known: true wenn Tag in der Box zugeordnet ist
blocked_tags: Liste gesperrter Tag-UIDs
playback_state:
- state: IDLE | PLAYING | PAUSED
- active_uid
- playback_root
- current_file
- file_index
- position
- duration
- volume
- last_error

Beispielantwort:

{
  "box_id": "klangkiste-a9f3k7m2q8",
  "pairing_state": "UNPAIRED",
  "wifi_state": "WIFI_ONLINE",
  "ip_address": "127.0.0.1",
  "connected_ssid": "HomeWiFi",
  "wifi_profiles_count": 1,
  "spotify_status": "READY",
  "blocked_tags": [],
  "playback_state": {
    "state": "PLAYING",
    "active_uid": "UID_1",
    "playback_root": "media/book_1",
    "current_file": "/root/klangkiste/box/data/media/stories/dragons/album_1/track_01.mp3",
    "file_index": 0,
    "position": 42,
    "duration": 180,
    "volume": 40,
    "last_error": null
  }
}

GET /local-tags

Nur fuer gepairte Boxen (Header: X-API-Token). Zeigt lokale Tags, inkl. Dateiliste und Groesse.

curl http://127.0.0.1:8000/local-tags \
  -H "X-API-Token: <api_token>"

POST /command

Request Body:

{
  "command": "nfc_on",
  "payload": { "uid": "UID_1" }
}

Unterstuetzte 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
unpair
tag_assign { uid, media_path }
tag_remove { uid }
tag_block { uid }
tag_unblock { uid }
export_tag { uid, target_folder }
factory_reset

Tag-Commands

tag_assign { uid, media_path } weist ein Tag einem Medienordner zu.
tag_remove { uid } entfernt die Zuordnung fuer ein Tag.
tag_block sperrt den Tag fuer diese Box.
tag_unblock hebt die Sperre auf.
export_tag uebertraegt die lokalen Medien dieses Tags an den Server.

Auth fuer Commands

Vor Pairing sind nur diese Commands erlaubt:
- wifi_add_profile, wifi_reset, spotify_set_tokens, spotify_clear
Alle anderen Commands erfordern X-API-Token im Header.

Beispiel mit Token:\n``` curl -X POST http://127.0.0.1:8000/command \ -H "Content-Type: application/json" \ -H "X-API-Token: <api_token>" \ -d '{"command":"nfc_on","payload":{"uid":"UID_1"}}'


Beispiel: WLAN-Profil hinzufuegen

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}}'


Beispiel: Spotify Tokens setzen

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}}'


## Checkliste
- ✅ `GET /status` liefert JSON
- ✅ `POST /command` liefert `{ "ok": true }`
- ✅ Keine Secrets in `/status`

## Troubleshooting
- 400 Responses:
  - Payload pruefen (Pflichtfelder).
- CORS-Fehler:
  - API muss laufen und erreichbar sein.

4.0 KiB Raw Permalink Blame History