Zum Inhalt springen
DeckConnectorEinrichten
Skip to Content

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.

WegWieHinweise
PasswortHTTP Basic Auth, beliebiger BenutzernameJede Anfrage, die etwas ändert, braucht dazu den Header X-DeckConnector: 1
SitzungPOST /api/login mit {"password": "..."} und X-DeckConnector: 1Setzt ein Cookie. Endet nach 12 Stunden ohne Nutzung oder mit POST /api/logout
API-SchlüsselAuthorization: Bearer SCHLUESSELBraucht keinen X-DeckConnector-Header. Rechte siehe unten
Setup-WLANEin Client im Setup-WLANRechte 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/status

Zugriffsstufen

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"}
codeBedeutung
ota_too_shortDie Datei ist zu kurz für eine Firmware-Datei
ota_not_dbfwKeine .dbfw-Datei
ota_not_signedNicht mit dem Schlüssel dieses Connectors signiert
ota_wrong_targetFür ein anderes Gerät oder einen anderen Teil
ota_too_oldUnter der Sicherheitsstufe
url_http_onlyDie URL muss mit http:// oder https:// beginnen
no_releasesNoch keine Releases zum Prüfen
rate_limitedGitHub begrenzt die Abfragen. Später nochmal versuchen
unreachableGitHub antwortet nicht
probe_no_connectionUnter dieser Adresse antwortet nichts
probe_no_answerDie Adresse nimmt die Verbindung an, schickt aber 3 s lang nichts
probe_not_companionEtwas antwortet, aber nicht Companion Satellite
strip_outsideDer Punkt liegt außerhalb der Touchleiste
busyDer Connector ist beschäftigt. Versuch es noch einmal
lockedZu viele falsche Passwörter. Status 429, die Antwort hat retry in Sekunden
pausedDiese 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_passwordFalsches Passwort
needs_passwordBraucht das Passwort, ein API-Schlüssel reicht nicht
passkey_hostPasskeys brauchen HTTPS und einen Namen
passkey_refusedDer 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

RouteWas sie tutStufe
POST /api/login{"password": "..."}, setzt das Sitzungs-Cookieopen
POST /api/logoutBeendet die Sitzungopen
POST /api/setup/claimVor der Einrichtung: eine Sitzung ohne Passwort, siehe Passwort. 403 unter dem Namen einer fremden Seite, 409 mit set up, claimed oder too lateopen
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 pausedopen
GET /api/login/request/<id>state ist pending, accepted, denied, expired oder used. Bei accepted setzt die Antwort einmal das Sitzungs-Cookieopen
DELETE /api/login/request/<id>Zieht die Anfrage zurückopen
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 403open
POST /api/login/passkeyDie 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 nichtopen
POST /api/password/showDas Deck zeigt das Passwort 30 s lang. 409 ohne Deck, 429 mit pausedopen
POST /api/password/resetDas Deck fragt 60 s lang, ob alles zurückgesetzt wird. Antwortet {"ok": true, "s": 60}. 409 ohne Deck, 429 mit pausedopen
DELETE /api/password/resetBeendet die Frageopen

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

Status und Einstellungen

RouteWas sie tutStufe
GET /apiJede Route mit method, path und accesscontrol
OPTIONS /api/...Der CORS-Preflight für die Origins in cors_originsopen
GET /api/wsDer Live-WebSocketcontrol
GET /api/statusZustand des Connectors, siehe Statuscontrol
GET /api/configEinstellungen, siehe Einstellungen. Geheimes nur als wifi_pass_set, wifi2_pass_set und token_setfull
PUT /api/configEinstellungen ändern. Schick nur die Schlüssel, die sich ändern. Die Antwort hat restart und configfull
POST /api/configSetup 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 langopen
GET /api/backupDie Einstellungen zum Wiederherstellen. ?secrets=1 fügt die Passwörter hinzuadmin
PUT /api/setup{"step": 3} merkt sich den Schritt der Einrichtung, {"step": 0} beendet siefull
POST /api/rebootNeustartfull
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 findcontrol
DELETE /api/apSchließt das Setup-WLANfull
POST /api/resetWerkszustand, danach ein Neustartadmin

Deck

RouteWas sie tutStufe
GET /api/screenWas das Deck zeigt, siehe Bildcontrol
GET /api/screen/<id>.jpgEin Bild aus diesem Bildcontrol
GET /api/screen.jpgDas ganze Bild als ein JPEGcontrol
POST /api/inputDrücken, drehen oder berühren, siehe Eingabencontrol
GET /api/input/logDie neuesten 400 der letzten 2000 Eingaben, älteste zuerst. ?since=<seq> für neuere, ?before=<seq> für älterecontrol
POST /api/menuDeck-Menü öffnen. 409 ohne Deckcontrol
DELETE /api/menuSchließt Deck-Menü, Passwort, Rücksetzfrage und Login-Anfragecontrol
POST /api/screen{"on": false} schaltet alle Decks sofort dunkel, {"on": true} wieder an. Kein Druck wird verschlucktfull
POST /api/deck/reconnectSchaltet den USB-Port aus und wieder an. ?off_s=N (1 bis 600) lässt ihn N Sekunden auscontrol
POST /api/deck/stallStoppt die Bildausgabe wie bei einem hängenden Deck, für Testsfull
POST /api/sound/streamDer 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-Headercontrol
POST /api/sound/selftestSpielt 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 scheitertfull

Quellen und Kopplung

RouteWas sie tutStufe
POST /api/sources/retry{"host": "..."} mit einer Server-URL oder der Satellite-Adresse. Verbindet sofort statt nach der Wartezeitcontrol
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 nacheinanderfull
GET /api/companion/foundCompanions, die Satellite per mDNS anmelden. Der erste Aufruf startet eine Suche von 2 sfull
POST /api/dockKopplung, siehe Kopplungfull
DELETE /api/pairing/denied/<ip>Nimmt einen Rechner von der Liste der Abgelehntenfull

Matter

Siehe Matter. Solange matter.running false ist, antworten GET /api/matter, {"pair": true}, {"show": true} und POST /api/matter/press mit 409.

RouteWas sie tutStufe
GET /api/matterqr (der Text des QR-Codes), code (der Kopplungscode) und qr_bitsfull
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 Decksfull
DELETE /api/matterEntfernt alle Matter-Apps, macht einen neuen Kopplungscode und startet neufull
POST /api/matter/pressFür Tests: der Body von POST /api/input, nur an Matter. Kein Programm, kein Menü und kein Eingabe-Log sieht ihnfull

Netzwerk

RouteWas sie tutStufe
GET /api/wifi/scanNetze in Reichweite, das stärkste zuerst: ssid, bssid, rssi, channel, open. Nur 2,4 GHz. Dauert 2 bis 3 sfull
POST /api/wifi/join{"ssid": "...", "pass": "...", "bssid": ""}. Antwortet 202. network.wlan.join im Status geht innerhalb von 15 s von testing auf ok oder failedfull

Firmware

RouteWas sie tutStufe
POST /api/otaEine 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 Firmwarefull
POST /api/ota/url{"url": "https://..."}, der Connector lädt die Datei selbst, auch über eine Weiterleitung. Der Fortschritt kommt über den WebSocketfull
POST /api/ota/inspectDie ersten 144 Bytes einer Datei. Antwortet target, version, length, sha256 und ok mit errorfull
GET /api/update/check{"current": "v1.0.0", "latest": null, ...}full
GET /api/slotsDie vier Plätze mit state, version, running, next, bootable und why_notfull
POST /api/slots/<n>/bootNeustart in Platz N. 409, wenn er nicht starten kannfull
GET /api/frontendDie aktive Weboberfläche: source (partition oder builtin), api und bei einer hochgeladenen versioncontrol
PUT /api/frontendEine signierte Weboberfläche als Body. Sofort aktivfull
DELETE /api/frontendZurück zur Oberfläche aus der Firmwarefull
GET /api/bootBootloader und Partitionstabelle. ?raw=bootloader oder ?raw=ptable liefert die Bytesfull

Zugang

RouteWas sie tutStufe
GET /api/tokensDie API-Schlüssel, name und rightadmin
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 sofortadmin
DELETE /api/tokenDer Schlüssel der Anfrage beendet sich selbst. Home Assistant macht das, wenn du die Integration entfernstcontrol
GET /api/passkeysDie Passkeys, mit id, name und rp, dem Namen, unter dem jeder giltadmin
POST /api/passkeysDie 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 8admin
PUT /api/passkeys/<id>{"name": "Laptop"}, 1 bis 23 Bytesadmin
DELETE /api/passkeys/<id>Entfernt diesen Passkeyadmin
GET /api/certDas HTTPS-Zertifikat als PEMopen
GET /api/caDie 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 istopen
PUT /api/tls{"cert": "<PEM>", "key": "<PEM>"} prüft dein eigenes Zertifikat. Mit "apply": true wird es behalten und der Connector startet neuadmin
DELETE /api/tlsZurück zum eigenen Zertifikat des Connectors, mit Neustartfull

Diagnose

RouteWas sie tutStufe
GET /api/logDie letzten 16 KB des Logs als Text. ?boot=prev für den Start davorfull
GET /api/eventsEreignisse, 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 textcontrol
GET /api/metricsCPU, RAM und PSRAM alle 5 s für 10 Minuten, dazu die Flash-Belegungcontrol
GET /api/profileZeit je Route und CPU je Task seit dem letzten Aufruffull
GET /api/coredumpDer letzte Absturz. ?raw=1 liefert den Dump. 404, wenn es keinen gibtadmin
DELETE /api/coredumpLöscht ihnfull

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üsselWerte
name1 bis 31 Buchstaben, Ziffern und Bindestriche, kein Bindestrich am Anfang oder Ende. Auch der Hostname
controller, hostDie Quelle, die zeichnet, siehe Quellen
brightness0 bis 100. Ein Druck auf ein Deck bei 0 setzt sie auf 50
volumeDer Lautsprecher, 0 (aus, ab Werk) bis 100
speakerEin 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, wlandhcp, oder ip und mask mit optionalem gateway und dns
wifi_ssid, wifi_passwifi_pass hat 8 bis 63 Zeichen, 64 Hex-Ziffern oder ist leer für ein offenes Netz
wifi_bssidAn einen Zugangspunkt binden, leer für jeden
wifi2_ssid, wifi2_passDas Ersatz-WLAN, Werte wie bei wifi_ssid und wifi_pass. Leer schaltet es ab
serversBis zu 4 ws://- oder wss://-URLs. Leer sucht Server per mDNS
server_pinsSHA-256 je Server, an derselben Stelle wie in servers
satelliteDie Adresse von Companion als host, host:port oder ws://- bzw. wss://-URL. Leer schaltet es ab
satellite_pinSHA-256 für ein Companion hinter wss://
tokenGeht 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_autoCompanion von selbst vom Dock auf Satellite umstellen
https_onlyPlain HTTP abschalten
cors_originsOrigins mit Komma getrennt, die die API mit einem Schlüssel aufrufen dürfen
menu_chordauto, keys, encoders oder off
langDie Sprache der eigenen Deck-Seiten: de oder en
menu_hold_ms500 bis 10000
usb_speedauto oder full
max_decks1 bis 4 Decks gleichzeitig, Standard 2
screen_off_sSekunden ohne Eingabe, bis der Bildschirmschoner startet, 10 bis 86400. 0 heißt nie und ist der Standard
screen_dimWas 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_untilDer 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_onlyNur gekoppelte Dock-Rechner kommen rein
qr_loginLogin-QR-Code auf dem Deck, bis die Einrichtung fertig ist
ntp_serverLeer nimmt den von DHCP, sonst pool.ntp.org
trusted_proxyIPv4-Adresse eines Reverse Proxys, leer für keinen. Siehe Hinter einem Reverse Proxy
mattertrue startet Matter sofort. false startet den Connector neu, wenn Matter läuft
admin_pass6 bis 23 Zeichen. Nur mit Passwort
setup_doneNur 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}}
FeldBedeutung
idDie MAC-Adresse. Bleibt, wenn sich der Name ändert
writerWer 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
deviceDas 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[].lockedCompanion 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_limitDecks, die stecken, aber wegen max_decks dunkel bleiben
sourcesJedes Programm. chosen markiert das, das zeichnet, wenn kein Menü darüber liegt. Server und Satellite haben dazu error, since_s und iface
boot.reasonpower, pin, restart, crash, watchdog, brownout oder other
setupstep der Einrichtung im Browser, active, bis die Einrichtung fertig ist
menu_openMenü, Passwort, Rücksetzfrage oder Login-Anfrage liegen über dem Deck
screen_offAlle 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
brightnessDie eingestellte Helligkeit. decks[].brightness ist, was jedes Deck zeigt
network.lan.deadDas Kabel steckt, aber das Gateway antwortet nicht
network.wlan.backupDer Connector ist im Ersatz-WLAN, ssid nennt es
matteron, running, controllers (gekoppelte Apps) und pairing (offen für eine neue App)
pairingDock-Kopplung, siehe Kopplung
countersBilder, ersetzte Bilder, USB-Fehler, Deck-Neuverbindungen, Eingaben und verlorene Eingaben
decks[].writerWer auf diesem Deck zeichnet, Werte wie bei writer
decks[].hubDas Deck hängt an einem USB-Hub
speakerEin Lautsprecher ist angeschlossen. Die Platine hat einen Lautsprecher-Ausgang und speaker ist in den Einstellungen an, siehe Hardware
temp_cDie Chiptemperatur in °C. Fehlt bis zur ersten Messung
https_caDer 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.

tWann
stateSofort, dann bei jeder Änderung. Der Status ohne Laufzeit, Signal, Zähler, temp_c, boot_ms, memory, via_ap und pairing.open_s
screenDas Bild des Decks in deck (seine Seriennummer) hat sich geändert
inputJemand hat das Deck in deck benutzt. simulated ist bei einer API-Eingabe ohne "real" wahr. Ein API-Schlüssel bekommt nie simulierte Eingaben
otaUpdate-Fortschritt mit target, state, pct und error
pingAlle 5 s. Kommt 12 s lang gar nichts, neu verbinden
logNeuer Log-Text, erst nach {"t": "log"}. Braucht das Passwort oder einen full-Schlüssel
eventEin 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}}

Auf dieser Seite