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