Skip to content
DeckConnectorSet it up
Skip to Content

Own server

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

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. 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.
  • 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

{"t": "hello", "proto": 1, "id": "80f1b2a1b2c3", "name": "deckconnector-a1b2c3", "fw": "0.1.0",
 "c6": "3.0.10", "board": "waveshare-p4-poe-eth", "active": true}
{"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.

{"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 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

{"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.

Binary frames

The first byte is the type.

Server to connector

TypeNameAfter the type byte
0x01IMAGEu8 display, u16 x, u16 y, u16 w, u16 h, u32 seq, then the JPEG
0x02TIMEu8[7] reserved, u64 server_time_us

Connector to server

TypeNameAfter the type byte
0x81ACKu8 result, u8 display, u8 reserved, u32 seq, u64 t_recv, u64 t_start, u64 t_done
0x82TIMEu8[7] reserved, u64 server_time_us, u64 bridge_time_us
0x83INPUTu8 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

ValueNameMeaning
0SHOWNSent to the deck
1SUPERSEDEDA newer image covered it before it was sent
2REJECTED_RECTThe rectangle is not a target of this display
3REJECTED_ROLEThis server is not active, or the menu, the Elgato app or Companion has the deck
4NO_DEVICENo deck, or the USB transfer failed
5BUSYThe connector is out of image memory
6TOO_BIGThe image is larger than the display's max_bytes

INPUT kind

ValueKindFields
1KEY_DOWNindex
2KEY_UPindex
3ENCODER_DOWNindex
4ENCODER_UPindex
5ENCODER_TURNindex, value in ticks, positive is clockwise
6TOUCH_TAPdisplay, x, y
7TOUCH_LONGdisplay, x, y
8TOUCH_SWIPEdisplay, 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.

On this page