HTTP- und WebSocket-API
Jede Route der JSON-API, die Einstellungen, der Status und der Live-WebSocket.
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 |
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/statusZugriffsstufen
Jede Route hat eine Stufe, in der letzten Spalte der Tabellen unten. Die Stufen stehen unter 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.
{"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. 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 | control |
GET /api/status | Zustand des Connectors, siehe Status | control |
GET /api/config | Einstellungen, siehe 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, danach ein Neustart | admin |
Deck
| Route | Was sie tut | Stufe |
|---|---|---|
GET /api/screen | Was das Deck zeigt, siehe 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 | 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 | full |
DELETE /api/pairing/denied/<ip> | Nimmt einen Rechner von der Liste der Abgelehnten | full |
Matter
Siehe 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, 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
{"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 |
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 |
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.
{"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 oder die mit Matter gekoppelten Apps. Lege sie neu an, kopple sie neu oder lade sie neu hoch.
Status
{"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 |
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 |
temp_c | Die Chiptemperatur in °C. Fehlt bis zur ersten Messung |
https_ca | Der Kurzcode der CA des Connectors, siehe 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
{"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.
{"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.
{"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.
{"t": "set", "id": 1, "brightness": 40}
{"t": "input", "id": 2, "key": 3}
{"t": "result", "id": 1, "status": 200, "reply": {"ok": true, "restart": false}}