From e96149697356651fc4274311b62d5ef3b300673a Mon Sep 17 00:00:00 2001 From: Camden Dixie O'Brien Date: Sun, 21 May 2023 20:52:16 +0100 Subject: [PATCH] Come up with TCP control protocol --- README.md | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index c1b792c..9e03808 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ Networked bedside clock utilising an ESP32-SOLO-1. - [x] 7 segment display - [x] WiFi networking - [x] Console for configuration -- [ ] TCP API for configuration +- [ ] TCP control protocol - [x] SNTP synchronisation - [x] Snooze and dismiss buttons - [x] Multiple alarms @@ -20,3 +20,83 @@ Networked bedside clock utilising an ESP32-SOLO-1. The firmware is a standard ESP-IDF v5.0 project; refer to [Espressif's ESP-IDF docs](https://docs.espressif.com/projects/esp-idf/en/release-v5.0/esp32/index.html). + +## TCP Control Protocol + +Simple, binary, command / reponse protocol. + +Capabilities: +- Get firmware version +- Set time +- List, add and remove alarms +- List and modify settings + +Clients should wait for a response before sending another command. + +### Message Format + +The command and response message formats are the same, except commands +have an instruction where responses have a status code: + +| Offset (bytes) | Description | Length (bytes) | +|----------------|---------------------------|----------------| +| 0 | Instruction / status code | 1 | +| 1 | Parameter count | 1 | +| 2 | Parameters | *Variable* | + +Parameters are structured as a sequence of type, value tuples: + +| Offset | Description | Length (bytes) | +|--------|----------------|------------------------------| +| 0 | Type | 1 | +| 1 | Value | *Determined by length field* | + +A maximum of 16 parameters is permitted. + +### Instructions + +| Instruction | Description | Command parameters | Response parameters | +|-------------|---------------|------------------------------|----------------------------------| +| 0 | Get version | None | Major (u8), Minor (u8) | +| 1 | Set time | UNIX Timestamp (u64) | None | +| 2 | List alarms | None | Sequence of ID (u8), Alarm pairs | +| 3 | Add alarm | Alarm (alarm) | Alarm ID (u8) | +| 4 | Remove alarm | Alarm ID (u8) | None | +| 5 | List settings | None | Sequence of key (string), value | +| 6 | Set setting | Key (string), value (string) | None | + +### Status codes + +| Code | Description | Parameters | +|------|-----------------|-------------------------| +| 0 | OK / Success | *Instruction-dependent* | +| 1 | Busy | None | +| 2 | Invalid command | None | +| 3 | Internal error | None | +| 4 | Out of memory | None | + +### Types + +| Code | Name | Length (bytes) | Structure | +|------|--------|----------------|------------------------------------------| +| 0 | U8 | 1 | | +| 1 | U16 | 2 | | +| 2 | U32 | 4 | | +| 3 | U64 | 8 | | +| 4 | String | - | Length (u8), UTF-8 | +| 5 | Alarm | 3 | Hour (u8), minute (u8), day bitmask (u8) | + +All integers are big-endian. + +#### Day Bitmask + +| Bit (0 is least-significant) | Day | +|------------------------------|-----------| +| 0 | Monday | +| 1 | Tuesday | +| 2 | Wednesday | +| 3 | Thursday | +| 4 | Friday | +| 5 | Saturday | +| 6 | Sunday | +| 7 | *Unused* |