103 lines
3.9 KiB
Markdown
103 lines
3.9 KiB
Markdown
# Bedside Clock
|
|
|
|
Networked bedside clock utilising an ESP32-SOLO-1.
|
|
|
|
## Planned Features
|
|
|
|
- [x] Audio alerts
|
|
- [x] 7 segment display
|
|
- [x] WiFi networking
|
|
- [x] Console for configuration
|
|
- [ ] TCP control protocol
|
|
- [x] SNTP synchronisation
|
|
- [x] Snooze and dismiss buttons
|
|
- [x] Multiple alarms
|
|
- [x] Alarm conditions (e.g. weekday / weekend)
|
|
- [x] IPv6 support
|
|
|
|
## Firmware
|
|
|
|
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. Port number 3498.
|
|
|
|
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* |
|