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._tcpover mDNS and opensws://<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
tokenin the settings. The connector sends it asAuthorization: Bearerto the servers you entered. - The server named in
hostis 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
rolemessage, 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
roleafter 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
| 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.