# Eigener Server

> Das Deck per WebSocket aus dem eigenen Programm zeichnen. Protokoll Version 1.

Source: https://deckconnector.com/de/docs/own-server/

Dein Server rendert die Bilder. Der Connector zeigt sie an und schickt jeden Druck, jede Drehung und jede Berührung zurück. Als Ausgangspunkt dient `tools/dbtools/server.py` im Repository, ein kleiner Python-Server.

## Verbindung

- Der Connector ist der Client. Er öffnet bis zu vier URLs aus **Quellen** mit dem Subprotokoll `deckconnector.v1`.
- Ist die Liste leer, findet er Server, die `_deckconnector._tcp` per mDNS anmelden, und öffnet `ws://<adresse>:<port>/deckbridge`.
- `wss://` braucht ein Zertifikat einer öffentlichen CA für diesen Host oder den SHA-256-Pin dieses Servers.
- Damit dein Server prüfen kann, wer sich verbindet, setz `token` in den [Einstellungen](https://deckconnector.com/de/docs/api/#einstellungen). Der Connector schickt ihn als `Authorization: Bearer` an die Server, die du eingetragen hast.
- Der Server aus `host` ist **aktiv**, wenn er verbunden ist. Sonst ist es der erste verbundene Server der Liste. Die anderen stehen auf **Standby**. Nur der aktive zeichnet und bekommt Eingaben.
- Fällt er weg, wird der nächste aktiv, bekommt eine `role`-Nachricht und muss alle Bereiche neu zeichnen. Bis dahin zeigt das Deck, was dieser Server zuletzt gezeichnet hat. Das kann alt sein.
- Der aktive Server bekommt `role` auch, wenn das Menü oder ein Update über sein Bild gezeichnet hat.
- Solange Companion oder die Elgato-App die aktive Quelle ist, stehen alle Server auf Standby. Siehe [Quellen](https://deckconnector.com/de/docs/hosts/).
- Der Connector pingt alle 2 s. Ein Server, der 6 s schweigt, gilt als verloren.

Text-Frames tragen JSON. Binäre Frames tragen Bilder, Bestätigungen, Eingaben und Zeitabgleich. Alle binären Ganzzahlen sind Little Endian.

## Koordinaten

Jedes Display hat ein Pixel-Koordinatensystem, Ursprung oben links auf dem ganzen Glas. Tasten und Leisten sind Rechtecke darin. Schick jedes Rechteck aus `targets` des Displays, den USB-Befehl wählt der Connector. Wende Drehung und Spiegelung an, bevor du das Bild kodierst. `format` ist `jpeg`, beim Mini und beim Module 6 `bmp`. `max_bytes` ist, wenn vorhanden, das größte Bild, das das Display nimmt.

## Vom Connector

```json
{"t": "hello", "proto": 1, "id": "80f1b2a1b2c3", "name": "deckconnector-a1b2c3", "fw": "0.1.0",
 "c6": "3.0.10", "board": "waveshare-p4-poe-eth", "active": true}
```

```json
{"t": "device", "present": true, "vendor": "Elgato", "model": "Stream Deck +", "vid": 4057, "pid": 132,
 "serial": "A00SA0000AA0A0", "fw": "1.01.008", "tested": true, "keys": 8, "encoders": 4,
 "displays": [{"id": 0, "w": 800, "h": 480, "format": "jpeg", "rotate": 0, "flip_x": false, "flip_y": false,
   "targets": [{"kind": "full", "x": 0, "y": 0, "w": 800, "h": 480},
               {"kind": "key", "index": 0, "x": 13, "y": 12, "w": 120, "h": 120},
               {"kind": "strip", "x": 0, "y": 380, "w": 800, "h": 100, "partial": true}]}],
 "touch": [{"display": 0, "x": 0, "y": 380, "w": 800, "h": 100}]}
```

Ein `strip`-Ziel mit `partial: true` nimmt jedes Rechteck darin an. Andere Ziele nehmen nur genau ihr Rechteck. `{"t": "device", "present": false}` heißt, das Deck wurde abgezogen.

```json
{"t": "role", "active": true}
{"t": "status", "name": "deckconnector-a1b2c3", "firmware": "v1.0.0", "controller": "server", "writer": "server1"}
{"t": "ota", "target": "p4", "state": "download", "pct": 40}
{"t": "ota", "target": "p4", "state": "error", "error": "signature"}
```

`status` hat die Felder von [`GET /api/status`](https://deckconnector.com/de/docs/api/#status) ohne `memory`, `boot_ms`, `temp_c` und `via_ap`. OTA-`state` ist `download`, `verify`, `done` oder `error`. Nach `done` startet der Connector neu.

## An den Connector

```json
{"t": "brightness", "pct": 70}
{"t": "ota", "target": "p4", "url": "http://server:8000/deckconnector-v1.0.0.dbfw"}
{"t": "reboot"}
```

Der Connector nimmt diese nur vom aktiven Server an. `ota` braucht `target`, aber die signierte Datei bestimmt, für welchen Chip sie ist. Siehe [Updates](https://deckconnector.com/de/docs/updates/).

## Binäre Frames

Das erste Byte ist der Typ.

### Server an Connector

| Typ | Name | Nach dem Typ-Byte |
|---|---|---|
| `0x01` | IMAGE | `u8 display, u16 x, u16 y, u16 w, u16 h, u32 seq`, dann das JPEG |
| `0x02` | TIME | `u8[7] reserved, u64 server_time_us` |

### Connector an Server

| Typ | Name | Nach dem Typ-Byte |
|---|---|---|
| `0x81` | ACK | `u8 result, u8 display, u8 reserved, u32 seq, u64 t_recv, u64 t_start, u64 t_done` |
| `0x82` | TIME | `u8[7] reserved, u64 server_time_us, u64 bridge_time_us` |
| `0x83` | INPUT | `u8 kind, u8 index, u8 display, i16 value, u16 x, u16 y, u16 x2, u16 y2, u8[10] reserved, u64 t` |

Zeiten sind Mikrosekunden auf der Uhr des Connectors. `t_recv` ist der Moment, in dem das Bild vollständig war. `t_start` und `t_done` rahmen die USB-Übertragung ein. Bei INPUT ist `t` der Eingang des USB-Reports.

### ACK result

| Wert | Name | Bedeutung |
|---|---|---|
| 0 | `SHOWN` | An das Deck geschickt |
| 1 | `SUPERSEDED` | Ein neueres Bild hat es vorher verdeckt |
| 2 | `REJECTED_RECT` | Das Rechteck ist kein Ziel dieses Displays |
| 3 | `REJECTED_ROLE` | Dieser Server ist nicht aktiv, oder Menü, Elgato-App oder Companion haben das Deck |
| 4 | `NO_DEVICE` | Kein Deck, oder die USB-Übertragung ist fehlgeschlagen |
| 5 | `BUSY` | Dem Connector ist der Bildspeicher ausgegangen |
| 6 | `TOO_BIG` | Das Bild ist größer als `max_bytes` des Displays |

### INPUT kind

| Wert | Art | Felder |
|---|---|---|
| 1 | `KEY_DOWN` | `index` |
| 2 | `KEY_UP` | `index` |
| 3 | `ENCODER_DOWN` | `index` |
| 4 | `ENCODER_UP` | `index` |
| 5 | `ENCODER_TURN` | `index`, `value` in Rastungen, positiv ist im Uhrzeigersinn |
| 6 | `TOUCH_TAP` | `display`, `x`, `y` |
| 7 | `TOUCH_LONG` | `display`, `x`, `y` |
| 8 | `TOUCH_SWIPE` | `display`, von `x`, `y` nach `x2`, `y2` |

Touch-Positionen sind Display-Koordinaten.

## Flusskontrolle

Schick das nächste Bild für einen Bereich erst nach dem ACK für das letzte dort. Das hält die Verzögerung auf langsamen Strecken wie WLAN klein. Gib einen Bereich nach 2 s ohne ACK wieder frei, denn ein ACK kann verloren gehen.

`seq` wählst du selbst, es kommt im ACK zurück. Ein neueres Bild, das ein wartendes verdeckt, ersetzt es, und das ältere bekommt `SUPERSEDED`.

Next: [API](https://deckconnector.com/de/docs/api/)
