# Own server

> Draw the deck from your own program over WebSocket. Protocol version 1.

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

Your server renders the images. The connector shows them and sends back every press, turn and touch. Start from `tools/dbtools/server.py` in the repository, a small Python server.

## Connection

- The connector is the client. It opens up to four URLs from **Sources** with the subprotocol `deckconnector.v1`.
- With an empty list, it finds servers that announce `_deckconnector._tcp` over mDNS and opens `ws://<address>:<port>/deckbridge`.
- `wss://` needs a certificate from a public CA for that host, or the SHA-256 pin set for that server.
- To check who connects, set `token` in the [settings](https://deckconnector.com/docs/api/#settings). The connector sends it as `Authorization: Bearer` to the servers you entered.
- The server named in `host` is **active** when it is connected. Otherwise it is the first connected server in the list. The others are **standby**. Only the active one draws and gets input.
- When it is lost, the next one becomes active, gets a `role` message, and must draw every area again. Until then the deck shows what that server drew last, which may be old.
- The active server also gets `role` after the menu or an update drew over its picture.
- While Companion or the Elgato app is the active source, every server is standby. See [Sources](https://deckconnector.com/docs/hosts/).
- The connector pings every 2 s. A server silent for 6 s counts as lost.

Text frames carry JSON. Binary frames carry images, acknowledgements, input and time sync. All binary integers are little endian.

## Coordinates

Each display has one pixel coordinate system, origin at the top left of the whole glass. Keys and strips are rectangles in it. Send any rectangle from the display's `targets`, and the connector picks the USB command. Apply the listed rotation and flip before you encode the image. `format` is `jpeg`, or `bmp` on the Mini and the Module 6. `max_bytes`, when present, is the largest image the display takes.

## From the 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}]}
```

A `strip` target with `partial: true` takes any rectangle inside it. Other targets take only their exact rectangle. `{"t": "device", "present": false}` means the deck was unplugged.

```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` has the fields of [`GET /api/status`](https://deckconnector.com/docs/api/#status) without `memory`, `boot_ms`, `temp_c` and `via_ap`. OTA `state` is `download`, `verify`, `done` or `error`. After `done` the connector restarts.

## To the connector

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

The connector takes these only from the active server. `ota` needs `target`, but the signed file decides which chip it is for. See [Updates](https://deckconnector.com/docs/updates/).

## Binary frames

The first byte is the type.

### Server to connector

| Type | Name | After the type byte |
|---|---|---|
| `0x01` | IMAGE | `u8 display, u16 x, u16 y, u16 w, u16 h, u32 seq`, then the JPEG |
| `0x02` | TIME | `u8[7] reserved, u64 server_time_us` |

### Connector to server

| Type | Name | After the type 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` |

Times are microseconds on the connector's clock. `t_recv` is when the image was complete. `t_start` and `t_done` frame the USB transfer. INPUT `t` is when the USB report arrived.

### ACK result

| Value | Name | Meaning |
|---|---|---|
| 0 | `SHOWN` | Sent to the deck |
| 1 | `SUPERSEDED` | A newer image covered it before it was sent |
| 2 | `REJECTED_RECT` | The rectangle is not a target of this display |
| 3 | `REJECTED_ROLE` | This server is not active, or the menu, the Elgato app or Companion has the deck |
| 4 | `NO_DEVICE` | No deck, or the USB transfer failed |
| 5 | `BUSY` | The connector is out of image memory |
| 6 | `TOO_BIG` | The image is larger than the display's `max_bytes` |

### INPUT kind

| Value | Kind | Fields |
|---|---|---|
| 1 | `KEY_DOWN` | `index` |
| 2 | `KEY_UP` | `index` |
| 3 | `ENCODER_DOWN` | `index` |
| 4 | `ENCODER_UP` | `index` |
| 5 | `ENCODER_TURN` | `index`, `value` in ticks, positive is clockwise |
| 6 | `TOUCH_TAP` | `display`, `x`, `y` |
| 7 | `TOUCH_LONG` | `display`, `x`, `y` |
| 8 | `TOUCH_SWIPE` | `display`, from `x`, `y` to `x2`, `y2` |

Touch positions are in display coordinates.

## Flow control

Send the next image for an area only after the ACK for the last one there. That keeps the delay low on slow links like Wi-Fi. Treat an area as free again after 2 s without an ACK, because one can get lost.

`seq` is yours and comes back in the ACK. A newer image that covers a waiting one replaces it, and the older one gets `SUPERSEDED`.

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