cdo/bedside-clock
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Come up with TCP control protocol

Browse Source
This commit is contained in:
Camden Dixie O'Brien 2023-05-21 20:52:16 +01:00
parent d2e2ea21df
commit e961496973
1 changed files with 81 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

82
README.md
View File

@ -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* |