2024-08-20 18:09:20 +02:00
|
|
|
This file documents the websocket /api/ws
|
|
|
|
|
|
|
|
|
|
## Format
|
|
|
|
|
Packet id then arguments \
|
|
|
|
|
Some packets don't have arguments so send just the packet id \
|
2024-08-21 18:01:37 +02:00
|
|
|
There can be multiple packets in one message, those with variable length arguments have to be terminated \
|
|
|
|
|
Numbers are signed
|
2024-08-20 18:09:20 +02:00
|
|
|
|
|
|
|
|
## Authentication
|
|
|
|
|
The first message from the server is:
|
|
|
|
|
- `0x6d 0x73`
|
|
|
|
|
|
|
|
|
|
The client should reply, in a single message:
|
|
|
|
|
1. `0xb6 0xc4`
|
|
|
|
|
2. client version (byte), right now it's 0
|
|
|
|
|
3. length of access key (byte)
|
|
|
|
|
4. access key, decoded from base64
|
|
|
|
|
|
|
|
|
|
Authentication complete, the server will send a disconnect if something's wrong, otherwise it will pong. \
|
2024-08-21 18:01:37 +02:00
|
|
|
No commands are handled during this time
|
|
|
|
|
|
|
|
|
|
# Commands
|
|
|
|
|
### Server bound (Client -> Server)
|
|
|
|
|
| Code | Name | Data | Notes |
|
|
|
|
|
|--------|----------|------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
|
|
|
|
|
| `0x00` | Ping | | the server replies with pong<br/>must be sent by client every at most 30 seconds, otherwise the server disconnects |
|
|
|
|
|
| `0x01` | Settings | 1. byte: setting id<br/>2. value<br/>3. and so on (terminated by 0xFF) | see below for IDs, value type varies |
|
|
|
|
|
|
|
|
|
|
### Client bound (Server -> Client)
|
|
|
|
|
|
|
|
|
|
| Code | Name | Data | Notes |
|
|
|
|
|
|--------|------|----------------------|----------------------------------------------------------------------|
|
|
|
|
|
| `0x00` | Pong | 1. long: unix millis | A response to ping, also sent by server on successful authentication |
|
2024-08-20 18:09:20 +02:00
|
|
|
|
|
|
|
|
## Disconnect reasons
|
2024-08-21 18:01:37 +02:00
|
|
|
On every disconnect there's a human-readable message the client should display
|
|
|
|
|
|
|
|
|
|
| Code | Name | Notes |
|
|
|
|
|
|--------|--------------------|-------------------------------------------------|
|
|
|
|
|
| `3000` | reserved | |
|
|
|
|
|
| `3001` | unauthorized | used during authentication phase |
|
|
|
|
|
| `3002` | version mismatch | incompatible client |
|
|
|
|
|
| `3003` | timeout | client wasn't sending pings |
|
|
|
|
|
| `3004` | access key revoked | when the access key was revoked while connected |
|
|
|
|
|
| `3005` | server error | |
|
2024-08-20 18:09:20 +02:00
|
|
|
|
|
|
|
|
## Settings
|
2024-08-21 18:01:37 +02:00
|
|
|
| Code | Name | Notes |
|
|
|
|
|
|--------|------------|-------------------------------------------------|
|
|
|
|
|
| `0x00` | reserved | |
|
|
|
|
|
| `0xFF` | terminator | not a setting, just used to terminate sequences |
|
