# HTTP- und WebSocket-API

> Jede Route der JSON-API, die Einstellungen, der Status und der Live-WebSocket.

Source: https://deckconnector.com/de/docs/api/

Alles, was die Weboberfläche tut, läuft über diese API, auf Port 80 und per HTTPS auf Port 443. `GET /api` listet jede Route mit ihrer Zugriffsstufe.

## Anmeldung

Nimm einen dieser Wege.

| Weg | Wie | Hinweise |
|---|---|---|
| Passwort | HTTP Basic Auth, beliebiger Benutzername | Jede Anfrage, die etwas ändert, braucht dazu den Header `X-DeckConnector: 1` |
| Sitzung | `POST /api/login` mit `{"password": "..."}` und `X-DeckConnector: 1` | Setzt ein Cookie. Endet nach 12 Stunden ohne Nutzung oder mit `POST /api/logout` |
| API-Schlüssel | `Authorization: Bearer SCHLUESSEL` | Braucht keinen `X-DeckConnector`-Header. Rechte siehe unten |
| Setup-WLAN | Ein Client im Setup-WLAN | Rechte wie das Passwort. Änderungen brauchen trotzdem `X-DeckConnector: 1` |

```bash
curl -u admin:PASSWORT http://192.168.1.50/api/status
curl -u admin:PASSWORT -H 'X-DeckConnector: 1' -X PUT -d '{"brightness": 60}' http://192.168.1.50/api/config
curl -H 'Authorization: Bearer SCHLUESSEL' http://192.168.1.50/api/status
```

## Zugriffsstufen

Jede Route hat eine Stufe, in der letzten Spalte der Tabellen unten. Die Stufen stehen unter [API-Schlüssel](https://deckconnector.com/de/docs/security/#api-schlüssel).

Kein API-Schlüssel ändert `admin_pass`, `setup_done` oder `qr_login`. Das gibt 403.

Solange das Deck das Passwort oder den Login-Code der Einrichtung zeigt oder das Setup-WLAN offen ist, bekommt ein API-Schlüssel 403 für die Routen, die auf ein Deck wirken. Das Deck-Bild (`/api/screen`, seine Bilder, `/api/screen.jpg`) antwortet einem API-Schlüssel außerdem mit 403, solange das Deck das Passwort zeigt, im Menü oder auf einer Seite der Einrichtung.

## Fehler

Fehler sind JSON mit passendem HTTP-Status. `error` ist englischer Text. `code`, wo vorhanden, bleibt gleich, auch wenn sich der Text ändert.

```json
{"ok": false, "error": "not signed for this DeckConnector", "code": "ota_not_signed"}
```

| `code` | Bedeutung |
|---|---|
| `ota_too_short` | Die Datei ist zu kurz für eine Firmware-Datei |
| `ota_not_dbfw` | Keine `.dbfw`-Datei |
| `ota_not_signed` | Nicht mit dem Schlüssel dieses Connectors signiert |
| `ota_wrong_target` | Für ein anderes Gerät oder einen anderen Teil |
| `ota_too_old` | Unter der Sicherheitsstufe |
| `url_http_only` | Die URL muss mit `http://` oder `https://` beginnen |
| `no_releases` | Noch keine Releases zum Prüfen |
| `rate_limited` | GitHub begrenzt die Abfragen. Später nochmal versuchen |
| `unreachable` | GitHub antwortet nicht |
| `probe_no_connection` | Unter dieser Adresse antwortet nichts |
| `probe_no_answer` | Die Adresse nimmt die Verbindung an, schickt aber 3 s lang nichts |
| `probe_not_companion` | Etwas antwortet, aber nicht Companion Satellite |
| `strip_outside` | Der Punkt liegt außerhalb der Touchleiste |
| `busy` | Der Connector ist beschäftigt. Versuch es noch einmal |
| `locked` | Zu viele falsche Passwörter. Status 429, die Antwort hat `retry` in Sekunden |
| `paused` | Diese Adresse hat vor weniger als einer Minute eine Frage aufs Deck gebracht, die ohne Ja endete. Status 429, `retry` in Sekunden und `Retry-After` |
| `wrong_password` | Falsches Passwort |
| `needs_password` | Braucht das Passwort, ein API-Schlüssel reicht nicht |
| `passkey_host` | Passkeys brauchen HTTPS und einen Namen |
| `passkey_refused` | Der Connector hat den Passkey nicht angenommen |

## Routen

Routen, die auf ein Deck wirken, nehmen `?deck=<seriennummer>` aus `decks` im Status. Ohne das wirken sie auf das erste Deck. Ein Deck, das nicht steckt, gibt 404.

### Anmeldung und Passwort

| Route | Was sie tut | Stufe |
|---|---|---|
| `POST /api/login` | `{"password": "..."}`, setzt das Sitzungs-Cookie | open |
| `POST /api/logout` | Beendet die Sitzung | open |
| `POST /api/setup/claim` | Vor der Einrichtung: eine Sitzung ohne Passwort, siehe [Passwort](https://deckconnector.com/de/docs/security/#passwort). 403 unter dem Namen einer fremden Seite, 409 mit `set up`, `claimed` oder `too late` | open |
| `POST /api/login/request` | `{"who": "iPhone · Safari"}`, bis zu 48 Zeichen. Das Deck fragt, ob dieser Browser rein darf. Antwortet `{"id": "...", "s": 60}`. 409 ohne Deck, 429 innerhalb von 3 s nach der letzten Anfrage oder mit `paused` | open |
| `GET /api/login/request/<id>` | `state` ist `pending`, `accepted`, `denied`, `expired` oder `used`. Bei `accepted` setzt die Antwort einmal das Sitzungs-Cookie | open |
| `DELETE /api/login/request/<id>` | Zieht die Anfrage zurück | open |
| `POST /api/passkeys/challenge` | `{"login": true}` für eine Anmeldung, `false` für einen neuen Passkey. Antwortet `{"challenge": "<hex>"}`. Gilt einmal, 2 Minuten lang, von dieser Adresse. 30 je 10 s und Adresse, sonst 429. Nur per HTTPS unter einem Namen, sonst 403 | open |
| `POST /api/login/passkey` | Die Antwort von `navigator.credentials.get()`, mit `id`, `clientDataJSON`, `authenticatorData` und `signature` in base64url. Der Passkey muss den Nutzer prüfen. Setzt das Sitzungs-Cookie. Ein abgelehnter Passkey zählt wie ein falsches Passwort, eine unbekannte oder benutzte Challenge nicht | open |
| `POST /api/password/show` | Das Deck zeigt das Passwort 30 s lang. 409 ohne Deck, 429 mit `paused` | open |
| `POST /api/password/reset` | Das Deck fragt 60 s lang, ob alles zurückgesetzt wird. Antwortet `{"ok": true, "s": 60}`. 409 ohne Deck, 429 mit `paused` | open |
| `DELETE /api/password/reset` | Beendet die Frage | open |

Die `open`-Routen, die etwas tun, brauchen `X-DeckConnector: 1`.

### Status und Einstellungen

| Route | Was sie tut | Stufe |
|---|---|---|
| `GET /api` | Jede Route mit `method`, `path` und `access` | control |
| `OPTIONS /api/...` | Der CORS-Preflight für die Origins in `cors_origins` | open |
| `GET /api/ws` | Der Live-[WebSocket](#websocket) | control |
| `GET /api/status` | Zustand des Connectors, siehe [Status](#status) | control |
| `GET /api/config` | Einstellungen, siehe [Einstellungen](#einstellungen). Geheimes nur als `wifi_pass_set`, `wifi2_pass_set` und `token_set` | full |
| `PUT /api/config` | Einstellungen ändern. Schick nur die Schlüssel, die sich ändern. Die Antwort hat `restart` und `config` | full |
| `POST /api/config` | **Setup** aus Companions Surfaces › Discover: `{"host": "...", "port": 16622}` als `application/json`. Während der Einrichtung verbindet sich der Connector sofort, danach fragt das Deck 60 s lang | open |
| `GET /api/backup` | Die Einstellungen zum Wiederherstellen. `?secrets=1` fügt die Passwörter hinzu | admin |
| `PUT /api/setup` | `{"step": 3}` merkt sich den Schritt der Einrichtung, `{"step": 0}` beendet sie | full |
| `POST /api/reboot` | Neustart | full |
| `POST /api/sound` | `{"sound": "find"}` spielt `ready`, `connected`, `lost` oder `find`. `volume` 0 bis 100 übergeht die Einstellung. Ohne `volume` spielt `find` mindestens mit 60. 409, solange `speaker` false ist, und bei Lautstärke 0 für jeden Ton außer `find` | control |
| `DELETE /api/ap` | Schließt das Setup-WLAN | full |
| `POST /api/reset` | [Werkszustand](https://deckconnector.com/de/docs/first-setup/#werkszustand), danach ein Neustart | admin |

### Deck

| Route | Was sie tut | Stufe |
|---|---|---|
| `GET /api/screen` | Was das Deck zeigt, siehe [Bild](#bild) | control |
| `GET /api/screen/<id>.jpg` | Ein Bild aus diesem Bild | control |
| `GET /api/screen.jpg` | Das ganze Bild als ein JPEG | control |
| `POST /api/input` | Drücken, drehen oder berühren, siehe [Eingaben](#eingaben) | control |
| `GET /api/input/log` | Die neuesten 400 der letzten 2000 Eingaben, älteste zuerst. `?since=<seq>` für neuere, `?before=<seq>` für ältere | control |
| `POST /api/menu` | Deck-Menü öffnen. 409 ohne Deck | control |
| `DELETE /api/menu` | Schließt Deck-Menü, Passwort, Rücksetzfrage und Login-Anfrage | control |
| `POST /api/screen` | `{"on": false}` schaltet alle Decks sofort dunkel, `{"on": true}` wieder an. Kein Druck wird verschluckt | full |
| `POST /api/deck/reconnect` | Schaltet den USB-Port aus und wieder an. `?off_s=N` (1 bis 600) lässt ihn N Sekunden aus | control |
| `POST /api/deck/stall` | Stoppt die Bildausgabe wie bei einem hängenden Deck, für Tests | full |
| `POST /api/sound/stream` | Der Body ist rohes PCM: 16 kHz, mono, 16 Bit Little Endian, mit `Content-Length`. Bei einem Stream unbekannter Länge eine größere `Content-Length` (höchstens 2147483647) senden und am Ende die Senderichtung der Verbindung schließen. Spielt es mit der Einstellung `volume` und antwortet `{"ok": true, "stopped": false}`, wenn es gespielt hat. Kommen Daten zu spät, spielt es Stille. `stopped` ist true, wenn `find`, ein neuerer Stream, `speaker` false oder 5 Sekunden ohne Daten es beendet haben. Andere Töne lässt der Connector weg, solange es spielt. Eine zurückgesetzte Verbindung stoppt es sofort. Der Connector puffert 3 Sekunden, also höchstens eine Sekunde im Voraus senden. 409, solange `speaker` false ist, 503, wenn der Codec versagt. Ohne CORS-Header | control |
| `POST /api/sound/selftest` | Spielt `find` und nimmt es mit dem Mikrofon der Platine auf, für Tests. Drei Gegenproben: eine andere Tonhöhe (1500 Hz) in derselben Aufnahme, `find` mit Lautstärke 0 und `find` mit ausgeschaltetem Verstärker. `heard` ist true, wenn der Ton mehr als 10-mal stärker ist als jede davon. Optional: `volume` 1 bis 100 (60), `gain` 0 bis 42 dB (24). Dauert etwa 6 Sekunden. 503 mit dem Grund, wenn ein Durchlauf scheitert | full |

### Quellen und Kopplung

| Route | Was sie tut | Stufe |
|---|---|---|
| `POST /api/sources/retry` | `{"host": "..."}` mit einer Server-URL oder der Satellite-Adresse. Verbindet sofort statt nach der Wartezeit | control |
| `POST /api/sources/probe` | `{"addr": "host:port", "pin": ""}` versucht Companion einmal und liefert seine `version` oder einen `code` dafür, was scheiterte (`probe_no_name`, `probe_refused`, `probe_timeout`, `probe_no_connection`, `probe_cert`, `probe_tls`, `probe_not_ws`, `probe_no_answer`, `probe_not_companion`). Höchstens etwa 6 s. Die Webseite probiert mehrere Formen einer Adresse nacheinander | full |
| `GET /api/companion/found` | Companions, die Satellite per mDNS anmelden. Der erste Aufruf startet eine Suche von 2 s | full |
| `POST /api/dock` | Kopplung, siehe [Kopplung](#kopplung) | full |
| `DELETE /api/pairing/denied/<ip>` | Nimmt einen Rechner von der Liste der Abgelehnten | full |

### Matter

Siehe [Matter](https://deckconnector.com/de/docs/matter/). Solange `matter.running` false ist, antworten `GET /api/matter`, `{"pair": true}`, `{"show": true}` und `POST /api/matter/press` mit 409.

| Route | Was sie tut | Stufe |
|---|---|---|
| `GET /api/matter` | `qr` (der Text des QR-Codes), `code` (der Kopplungscode) und `qr_bits` | full |
| `POST /api/matter` | `{"on": true}` startet Matter sofort, `{"on": false}` gilt nach einem Neustart. `{"pair": true}` öffnet das Koppeln für 15 Minuten. `{"show": true}` zeigt den Code 60 s auf den Decks | full |
| `DELETE /api/matter` | Entfernt alle Matter-Apps, macht einen neuen Kopplungscode und startet neu | full |
| `POST /api/matter/press` | Für Tests: der Body von [`POST /api/input`](#eingaben), nur an Matter. Kein Programm, kein Menü und kein Eingabe-Log sieht ihn | full |

### Netzwerk

| Route | Was sie tut | Stufe |
|---|---|---|
| `GET /api/wifi/scan` | Netze in Reichweite, das stärkste zuerst: `ssid`, `bssid`, `rssi`, `channel`, `open`. Nur 2,4 GHz. Dauert 2 bis 3 s | full |
| `POST /api/wifi/join` | `{"ssid": "...", "pass": "...", "bssid": ""}`. Antwortet 202. `network.wlan.join` im Status geht innerhalb von 15 s von `testing` auf `ok` oder `failed` | full |

### Firmware

| Route | Was sie tut | Stufe |
|---|---|---|
| `POST /api/ota` | Eine signierte `.dbfw`-Datei als Body. Kommt in den nächsten Platz und startet neu. `?slot=N` schreibt in Platz N, `?boot=0` behält die laufende Firmware | full |
| `POST /api/ota/url` | `{"url": "https://..."}`, der Connector lädt die Datei selbst, auch über eine Weiterleitung. Der Fortschritt kommt über den WebSocket | full |
| `POST /api/ota/inspect` | Die ersten 144 Bytes einer Datei. Antwortet `target`, `version`, `length`, `sha256` und `ok` mit `error` | full |
| `GET /api/update/check` | `{"current": "v1.0.0", "latest": null, ...}` | full |
| `GET /api/slots` | Die vier Plätze mit `state`, `version`, `running`, `next`, `bootable` und `why_not` | full |
| `POST /api/slots/<n>/boot` | Neustart in Platz N. 409, wenn er nicht starten kann | full |
| `GET /api/frontend` | Die aktive Weboberfläche: `source` (`partition` oder `builtin`), `api` und bei einer hochgeladenen `version` | control |
| `PUT /api/frontend` | Eine signierte Weboberfläche als Body. Sofort aktiv | full |
| `DELETE /api/frontend` | Zurück zur Oberfläche aus der Firmware | full |
| `GET /api/boot` | Bootloader und Partitionstabelle. `?raw=bootloader` oder `?raw=ptable` liefert die Bytes | full |

### Zugang

| Route | Was sie tut | Stufe |
|---|---|---|
| `GET /api/tokens` | Die API-Schlüssel, `name` und `right` | admin |
| `POST /api/tokens` | `{"name": "home-assistant", "right": "control"}`. Zeigt den Schlüssel einmal. `name` hat 1 bis 23 Buchstaben, Ziffern, `-` oder `_` | admin |
| `DELETE /api/tokens/<name>` | Beendet diesen Schlüssel sofort | admin |
| `DELETE /api/token` | Der Schlüssel der Anfrage beendet sich selbst. Home Assistant macht das, wenn du die Integration entfernst | control |
| `GET /api/passkeys` | Die Passkeys, mit `id`, `name` und `rp`, dem Namen, unter dem jeder gilt | admin |
| `POST /api/passkeys` | Die Antwort von `navigator.credentials.create()`, mit `name`, `id`, `clientDataJSON`, `authenticatorData`, `publicKey` (SPKI) und `publicKeyAlgorithm` (`-7`), binäre Teile in base64url. Nur ES256 mit Nutzerprüfung, höchstens 8 | admin |
| `PUT /api/passkeys/<id>` | `{"name": "Laptop"}`, 1 bis 23 Bytes | admin |
| `DELETE /api/passkeys/<id>` | Entfernt diesen Passkey | admin |
| `GET /api/cert` | Das HTTPS-Zertifikat als PEM | open |
| `GET /api/ca` | Die CA des Connectors als DER, um ihr einmal zu vertrauen. Das Deck zeigt ihren kurzen Code, `https_ca` im Status, aber nicht, solange diese Adresse `paused` ist | open |
| `PUT /api/tls` | `{"cert": "<PEM>", "key": "<PEM>"}` prüft dein eigenes Zertifikat. Mit `"apply": true` wird es behalten und der Connector startet neu | admin |
| `DELETE /api/tls` | Zurück zum eigenen Zertifikat des Connectors, mit Neustart | full |

### Diagnose

| Route | Was sie tut | Stufe |
|---|---|---|
| `GET /api/log` | Die letzten 16 KB des Logs als Text. `?boot=prev` für den Start davor | full |
| `GET /api/events` | Ereignisse, neueste zuerst, höchstens 200. `?before=<seq>` für ältere, `?since=<Unix-Zeit>` hört dort auf, `?n=` für weniger. Jedes hat `seq`, `at`, `since_s`, `boot`, `kind`, `code`, `level`, `args` und den englischen `text` | control |
| `GET /api/metrics` | CPU, RAM und PSRAM alle 5 s für 10 Minuten, dazu die Flash-Belegung | control |
| `GET /api/profile` | Zeit je Route und CPU je Task seit dem letzten Aufruf | full |
| `GET /api/coredump` | Der letzte Absturz. `?raw=1` liefert den Dump. 404, wenn es keinen gibt | admin |
| `DELETE /api/coredump` | Löscht ihn | full |

## Einstellungen

```json
{"name": "deckconnector-a1b2c3", "controller": "companion", "host": "satellite", "brightness": 80,
 "lan": {"dhcp": true, "ip": "", "mask": "", "gateway": "", "dns": ""},
 "wlan": {"dhcp": true, "ip": "", "mask": "", "gateway": "", "dns": ""},
 "wifi_ssid": "studio", "wifi_pass_set": true, "wifi_bssid": "", "wifi2_ssid": "", "wifi2_pass_set": false,
 "servers": ["ws://192.168.1.20:8765/deckconnector", "", "", ""],
 "server_pins": ["", "", "", ""], "satellite": "192.168.1.10", "satellite_auto": true, "satellite_pin": "",
 "https_only": false, "cors_origins": "", "menu_chord": "auto", "menu_hold_ms": 2000, "lang": "de", "usb_speed": "auto",
 "max_decks": 2, "screen_off_s": 0, "screen_dim": 0, "star_off": false, "star_fw": "v1.0.0", "star_until": 0, "dock_paired_only": false, "qr_login": true, "ntp_server": "", "trusted_proxy": "", "setup_done": true, "token_set": false, "matter": false}
```

| Schlüssel | Werte |
|---|---|
| `name` | 1 bis 31 Buchstaben, Ziffern und Bindestriche, kein Bindestrich am Anfang oder Ende. Auch der Hostname |
| `controller`, `host` | Die Quelle, die zeichnet, siehe [Quellen](https://deckconnector.com/de/docs/hosts/#über-die-api) |
| `brightness` | 0 bis 100. Ein Druck auf ein Deck bei 0 setzt sie auf 50 |
| `volume` | Der Lautsprecher, 0 (aus, ab Werk) bis 100 |
| `speaker` | Ein Lautsprecher ist angeschlossen. Ein neuer Connector startet mit false, bis die Einrichtung in der Weboberfläche fragt. Mit false spielt er keinen Ton, und `/api/sound` antwortet 409 |
| `lan`, `wlan` | `dhcp`, oder `ip` und `mask` mit optionalem `gateway` und `dns` |
| `wifi_ssid`, `wifi_pass` | `wifi_pass` hat 8 bis 63 Zeichen, 64 Hex-Ziffern oder ist leer für ein offenes Netz |
| `wifi_bssid` | An einen Zugangspunkt binden, leer für jeden |
| `wifi2_ssid`, `wifi2_pass` | Das Ersatz-WLAN, Werte wie bei `wifi_ssid` und `wifi_pass`. Leer schaltet es ab |
| `servers` | Bis zu 4 `ws://`- oder `wss://`-URLs. Leer sucht Server per mDNS |
| `server_pins` | SHA-256 je Server, an derselben Stelle wie in `servers` |
| `satellite` | Die Adresse von Companion als `host`, `host:port` oder `ws://`- bzw. `wss://`-URL. Leer schaltet es ab |
| `satellite_pin` | SHA-256 für ein Companion hinter `wss://` |
| `token` | Geht als `Authorization: Bearer` an die Server in `servers`, nie an einen per mDNS gefundenen. Bis zu 47 Zeichen, leer für keinen. `GET` zeigt nur `token_set` |
| `satellite_auto` | Companion von selbst vom Dock auf Satellite umstellen |
| `https_only` | Plain HTTP abschalten |
| `cors_origins` | Origins mit Komma getrennt, die die API mit einem Schlüssel aufrufen dürfen |
| `menu_chord` | `auto`, `keys`, `encoders` oder `off` |
| `lang` | Die Sprache der eigenen Deck-Seiten: `de` oder `en` |
| `menu_hold_ms` | 500 bis 10000 |
| `usb_speed` | `auto` oder `full` |
| `max_decks` | 1 bis 4 Decks gleichzeitig, Standard 2 |
| `screen_off_s` | Sekunden ohne Eingabe, bis der Bildschirmschoner startet, 10 bis 86400. 0 heißt nie und ist der Standard |
| `screen_dim` | Was der Bildschirmschoner tut. 0 schaltet alle Decks dunkel und ist der Standard. 10 bis 90 in Zehnerschritten dimmt sie auf so viel Prozent |
| `star_off`, `star_fw`, `star_until` | Der Stern-Hinweis im Web-UI. `star_off` blendet ihn für immer aus. `star_until` blendet ihn bis zu dieser Unix-Zeit aus. `star_fw` ist die Firmware, auf der ihn zuletzt jemand geschlossen hat. Nach einem Update auf eine neuere erscheint er einmal |
| `dock_paired_only` | Nur gekoppelte Dock-Rechner kommen rein |
| `qr_login` | Login-QR-Code auf dem Deck, bis die Einrichtung fertig ist |
| `ntp_server` | Leer nimmt den von DHCP, sonst `pool.ntp.org` |
| `trusted_proxy` | IPv4-Adresse eines Reverse Proxys, leer für keinen. Siehe [Hinter einem Reverse Proxy](https://deckconnector.com/de/docs/security/#hinter-einem-reverse-proxy) |
| `matter` | `true` startet Matter sofort. `false` startet den Connector neu, wenn Matter läuft |
| `admin_pass` | 6 bis 23 Zeichen. Nur mit Passwort |
| `setup_done` | Nur mit Passwort. Für eine neue Einrichtung `PUT /api/setup` mit `{"step": 1}` |

`brightness`, `volume`, `speaker`, `controller`, `host`, `servers`, `server_pins`, `satellite`, `satellite_auto`, `satellite_pin`, `https_only`, `cors_origins`, `trusted_proxy`, `menu_chord`, `menu_hold_ms`, `lang`, `max_decks`, `screen_off_s`, `screen_dim`, `star_off`, `star_fw`, `star_until`, `wifi2_ssid`, `wifi2_pass`, `qr_login`, `dock_paired_only` und `setup_done` wirken sofort. Jede andere Änderung startet den Connector neu. Die Antwort hat dann `reach` mit den Adressen, unter denen der Connector danach zu finden ist.

```json
{"ok": true, "restart": true, "reach": ["http://192.168.1.50", "http://deckconnector-a1b2c3.local"]}
```

Ein abgelehnter Wert gibt 400 mit dem Grund, und der Connector speichert nichts. Die Antwort von `GET /api/config` ist eine Sicherung ohne Passwörter und Token. Ein `PUT` davon stellt die Einstellungen wieder her. `GET /api/backup?secrets=1` fügt `admin_pass`, `wifi_pass`, `wifi2_pass` und `token` hinzu. Keine Sicherung enthält API-Schlüssel, Passkeys, gekoppelte Dock-Rechner, die Dateien für [eigenes HTTPS](https://deckconnector.com/de/docs/security/#https) oder die mit Matter gekoppelten Apps. Lege sie neu an, kopple sie neu oder lade sie neu hoch.

## Status

```json
{"via_ap": false, "id": "a0b1c2a1b2c3", "name": "deckconnector-a1b2c3", "firmware": "v1.0.0",
 "wlan_firmware": "3.0.10", "uptime_s": 23, "boot": {"reason": "restart", "at": 1794012139},
 "setup": {"active": false, "step": 0, "rerun": false}, "controller": "companion", "writer": "satellite",
 "menu_open": false, "screen_off": false, "brightness": 80,
 "device": {"model": "Stream Deck +", "serial": "EL00K1A00001", "firmware": "2.0.3.7", "keys": 8, "encoders": 4,
            "width": 800, "height": 480},
 "network": {"lan": {"cable": true, "dead": false, "ip": "192.168.1.50"},
             "wlan": {"ssid": "studio", "ip": "192.168.1.51", "bssid": "aa:bb:cc:dd:ee:ff", "channel": 1,
                      "lock": "", "backup": false, "rssi": -48, "join": "", "join_error": ""},
             "ap": {"on": false, "ssid": ""}},
 "sources": [{"kind": "companion", "host": "192.168.1.10", "via": "satellite", "name": "studio",
              "connected": true, "chosen": true, "drawing": true}],
 "counters": {"images": 7, "superseded": 0, "rejected": 0, "usb_errors": 0, "usb_recoveries": 0,
              "usb_speed": "high", "inputs": 0, "inputs_dropped": 0}}
```

| Feld | Bedeutung |
|---|---|
| `id` | Die MAC-Adresse. Bleibt, wenn sich der Name ändert |
| `writer` | Wer gerade zeichnet: `ui`, `server1` bis `server4`, `dock1` bis `dock4` oder `satellite`. `ui`, solange das Menü offen ist, ein Update läuft oder die aktive Quelle nicht verbunden ist |
| `device` | Das erste Deck, `null` ohne Deck. `decks` listet jedes Deck mit seinem `slot` (0 für Deck 1) und seiner `number` (1 für Deck 1) |
| `decks[].locked` | Companion zeichnet über Satellite auf dem Deck und hat es mit seiner PIN gesperrt. Das Deck zeigt das Zahlenfeld. `pin_count` ist die Zahl der getippten Ziffern, `pin_wrong` ist nach einer falschen PIN 600 ms lang true |
| `decks_over_limit` | Decks, die stecken, aber wegen `max_decks` dunkel bleiben |
| `sources` | Jedes Programm. `chosen` markiert das, das zeichnet, wenn kein Menü darüber liegt. Server und Satellite haben dazu `error`, `since_s` und `iface` |
| `boot.reason` | `power`, `pin`, `restart`, `crash`, `watchdog`, `brownout` oder `other` |
| `setup` | `step` der Einrichtung im Browser, `active`, bis die Einrichtung fertig ist |
| `menu_open` | Menü, Passwort, Rücksetzfrage oder Login-Anfrage liegen über dem Deck |
| `screen_off` | Alle Decks sind dunkel, durch den Bildschirmschoner oder `POST /api/screen`. Die erste Eingabe weckt sie und erreicht kein Programm. `decks[].brightness` ist dann 0. Ein gedimmtes Deck ist nicht aus |
| `brightness` | Die eingestellte Helligkeit. `decks[].brightness` ist, was jedes Deck zeigt |
| `network.lan.dead` | Das Kabel steckt, aber das Gateway antwortet nicht |
| `network.wlan.backup` | Der Connector ist im Ersatz-WLAN, `ssid` nennt es |
| `matter` | `on`, `running`, `controllers` (gekoppelte Apps) und `pairing` (offen für eine neue App) |
| `pairing` | Dock-Kopplung, siehe [Kopplung](#kopplung) |
| `counters` | Bilder, ersetzte Bilder, USB-Fehler, Deck-Neuverbindungen, Eingaben und verlorene Eingaben |
| `decks[].writer` | Wer auf diesem Deck zeichnet, Werte wie bei `writer` |
| `decks[].hub` | Das Deck hängt an einem USB-Hub |
| `speaker` | Ein Lautsprecher ist angeschlossen. Die Platine hat einen Lautsprecher-Ausgang und `speaker` ist in den Einstellungen an, siehe [Hardware](https://deckconnector.com/de/docs/hardware/#platine) |
| `temp_c` | Die Chiptemperatur in °C. Fehlt bis zur ersten Messung |
| `https_ca` | Der Kurzcode der CA des Connectors, siehe [HTTPS](https://deckconnector.com/de/docs/security/#https). Leer mit eigenem Zertifikat, dann ist `https_custom` true |

Der Status hat außerdem `api`, `simulated_input`, `boot_ms`, `memory`, `https_fingerprint` und `https_custom_unread` sowie Kopien der Einstellungen `volume`, `screen_off_s`, `screen_dim` und `max_decks`.

## Bild

```json
{"writer": "satellite", "width": 800, "height": 480,
 "keys": [{"x": 13, "y": 12, "w": 120, "h": 120}], "touch": [{"x": 0, "y": 380, "w": 800, "h": 100}],
 "encoders": 4, "menu_chord": {"on": "encoders", "first": 0, "last": 3, "hold_ms": 2000},
 "images": [{"x": 13, "y": 12, "w": 120, "h": 120, "url": "/api/screen/9.jpg"}]}
```

`strips` listet jede Leiste des Displays, auch die Infoleiste des Stream Deck Neo, die keinen Touch hat. Zeichne die JPEGs in dieser Reihenfolge an ihre Stelle, dann hast du das Bild. Ein Bild behält seine URL, bis etwas es verdeckt. Ein Browser darf es also cachen. Eine URL, die weg ist, gibt 404.

## Eingaben

`POST /api/input` tut so, als hätte jemand das Deck benutzt. Tasten und Drehregler zählen ab 0. Die Koordinaten sind die von `/api/screen`.

```json
{"key": 3}
{"key": 3, "action": "down"}
{"encoder": 0, "action": "turn", "ticks": -2}
{"touch": "tap", "x": 100, "y": 430}
{"touch": "long", "x": 100, "y": 430}
{"touch": "swipe", "x": 700, "y": 430, "x2": 100, "y2": 430}
```

`action` ist `press` (Standard), `down`, `up` oder `turn` für Drehregler. Positive Rastungen drehen nach rechts.

`{"pin": 3}` tippt eine Ziffer von Companions PIN auf einem gesperrten Deck, auch auf einem Deck, das kein Zahlenfeld zeigen kann. Das braucht `"real"` und gibt 409, wenn das Deck nicht gesperrt ist.

> **Echte Eingaben**
>
> Companion, die Elgato-App und die Satellite-Verbindung bekommen eine API-Eingabe nur mit `"real"`, denn ihre Tasten schalten echte Dinge. Ohne `"real"` erreicht die Eingabe nur die eigenen Bildschirme des Connectors und deine eigenen Server. `"real": true` ist für einen Menschen an einer Webseite. Ein Skript nennt stattdessen den Rechner, `"real": "192.168.1.10"`, und die Eingabe geht nur raus, solange dieser Rechner zeichnet.

Neustart, Werkszustand, die LAN-Einstellungen, das Setup-WLAN und die Tasten, die einen Rechner reinlassen, gehen nur am Deck selbst.

## Kopplung

`POST /api/dock` nimmt eins davon. `pairing` öffnet die Kopplung für 0 bis 3600 Sekunden.

```json
{"accept": true, "ip": "192.168.1.15"}
{"accept": false, "ip": "192.168.1.15"}
{"pairing": 300}
{"pairing": 0}
{"forget": "192.168.1.15"}
{"forget": true}
```

`pairing` im Status hat `only_paired`, die wartende `request`, `open` und `open_s`, solange die Kopplung offen ist, `denied` und die gekoppelten `hosts`. Eine Antwort, die einen anderen Rechner als den wartenden nennt, gibt 409.

## WebSocket

`/api/ws` nutzt dieselbe Anmeldung wie die anderen Routen. Eine Seite von einer anderen Website wird abgewiesen. Jede Nachricht ist ein JSON-Objekt, und `t` sagt, was es ist.

| `t` | Wann |
|---|---|
| `state` | Sofort, dann bei jeder Änderung. Der Status ohne Laufzeit, Signal, Zähler, `temp_c`, `boot_ms`, `memory`, `via_ap` und `pairing.open_s` |
| `screen` | Das Bild des Decks in `deck` (seine Seriennummer) hat sich geändert |
| `input` | Jemand hat das Deck in `deck` benutzt. `simulated` ist bei einer API-Eingabe ohne `"real"` wahr. Ein API-Schlüssel bekommt nie simulierte Eingaben |
| `ota` | Update-Fortschritt mit `target`, `state`, `pct` und `error` |
| `ping` | Alle 5 s. Kommt 12 s lang gar nichts, neu verbinden |
| `log` | Neuer Log-Text, erst nach `{"t": "log"}`. Braucht das Passwort oder einen `full`-Schlüssel |
| `event` | Ein neues Ereignis in `event`, wie `GET /api/events` es liefert |

Zum Ändern schickst du die Schlüssel von `PUT /api/config` oder `POST /api/input` mit einer `id`. Eine Eingabe geht an das erste Deck oder an das, dessen Seriennummer in `deck` steht. `GET /api/input/log` nennt das Deck genauso.

```json
{"t": "set", "id": 1, "brightness": 40}
{"t": "input", "id": 2, "key": 3}
{"t": "result", "id": 1, "status": 200, "reply": {"ok": true, "restart": false}}
```

Next: [Eigener Server](https://deckconnector.com/de/docs/own-server/), [Home Assistant](https://deckconnector.com/de/docs/home-assistant/)
