WebSocket gateway
How the client protocol travels over a WebSocket: the upgrade and how it's refused, frames, keepalive and close codes. Registration, login and the messages themselves are the same for every gateway, so they're on the protocol page.
1. Connect
Open the WebSocket with the access token from login, and offer the wbskt.v1 subprotocol.
GET /ws HTTP/1.1 Host: ws.dev.wbskt.com Upgrade: websocket Authorization: Bearer <accessToken> Sec-WebSocket-Protocol: wbskt.v1
- A client that can't set headers on the upgrade, like a browser, puts the token in
?access_token=instead. - A connection that offers no subprotocol is treated as v1. One that offers only other versions is refused.
- Send
capabilitiesas soon as it opens, before anything else.
2. When the upgrade is refused
The gateway answers before upgrading, with a Problem Details body whose code says why.
| Answer | Means | Do |
|---|---|---|
| 401 | The token is expired, missing or not ours. | Drop it and log in again. |
401CLIENT_TOKEN_INVALID | The token is missing something a client token needs. | Drop it and log in again. |
| 403 | It's a token, but not a client's. | Use the token from client login. A bug, not something to retry. |
403CLIENT_REVOKED | The client was revoked, deleted or had its secret rotated since the token was issued. | Keep the token and retry on the schedule. Once it expires, login says what happened. |
400SOCKET_PROTOCOL_UNSUPPORTED | Only subprotocol versions this gateway doesn't speak were offered. | Offer wbskt.v1. |
400SOCKET_UPGRADE_REQUIRED | The request wasn't a WebSocket upgrade. | A bug, not something to retry. |
| 503, or no answer | The gateway is restarting or unreachable. | Keep the token and retry on the schedule. |
3. Frames
Every message, both ways, is one text message holding one JSON object. It may arrive as several frames; the 64 KB limit is for the whole message. Binary frames are ignored.
4. Keepalive
Answer the protocol's sys.ping with sys.pong like any other message. Separately, the gateway sends a WebSocket Ping frame every 30 seconds and drops a connection that hasn't answered within another 30, so a board that lost power doesn't stay "online" for minutes. WebSocket libraries answer those Pings on their own.
5. Close codes
How this gateway says why it ended a connection. Branch on the code, not on the description.
| Code | Reason | Do |
|---|---|---|
| 1000 | Normal | Reconnect on the schedule. |
| 1001 | Restarting | Reconnect after a random 0–30 s. |
| 1009 | Too big | A message was over 64 KB. Fix the sender. |
| 1011 | Server error | Reconnect on the schedule. |
| 4001 | Superseded | The same client connected again. Repeated, it means shared credentials. |
| 4002 | Revoked | Drop the token; the next login says what happened. |
| 4003 | Throttled | Wait a random 30–60 s and send less. |
| 4000from client | Updating | Sent by a client closing to install firmware. Shown as updating, not offline, for 5 minutes. |