Pi Servers -- Roadmap

Alarm Configuration

Replace the current randint(30, 60) test loop in contents_server.py with real schedule-driven alarms.

Config schema

File: pi/alarm_config.json

{
  "alarm_time": "0700",
  "alarm_days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
  "alarm_dates": ["07/20", "10/21"],
  "alarm_audio": "assets/alarm/alarm_test.wav",
  "alarm_image": "assets/img/on_alarm.png"
}

Field definitions

Field	Type	Description
`alarm_time`	`string`	4-digit HHMM (24-hour). Triggers on the 0th second of the minute, or as soon as Python detects it.
`alarm_days`	`string[]`	(Optional) 3-letter day abbreviations: `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, `Sat`, `Sun`. Alarm only fires on listed days. If not supplied, alarms every day.
`alarm_dates`	`string[]`	(Optional) Strings of `MM/DD` format. If both `alarm_days` and `alarm_dates` are set, only `alarm_days` is effective.
`alarm_audio`	`string`	(Optional) Path to WAV file. Relative paths resolve from `pi/`. If not supplied, defaults to `assets/alarm/alarm_test.wav`.
`alarm_image`	`string`	(Optional) Path to status PNG shown during alarm. Relative paths resolve from `pi/`. If not supplied, defaults to `assets/img/on_alarm.png`.

Behavior

On startup, load and validate alarm_config.json
Each tick (~5s), check if current local time matches alarm_time and today's day name is in alarm_days, or if today's date is in alarm_dates.
Fire alarm once per matched minute (debounce so it doesn't re-trigger within the same minute)
After alarm completes, return to idle image and resume schedule checking

Docker Compose

Containerize the pi servers for easier deployment.

Options

Single service -- run_all.py as the entrypoint, both servers in one container
Split services -- separate containers for stats_server.py and contents_server.py

Single service is simpler. Split services allow independent scaling and restarts.

Configuration

Volume mount assets/ and alarm_config.json so they're editable without rebuilding
Expose ports 8765 and 8766
Network mode host or a bridge with known IPs for ESP32 discovery
Restart policy: unless-stopped

Repository Extraction

The pi/ directory will become its own git repository.

Steps

Extract pi/ into a standalone repo with its own README.md, requirements.txt, and CI
Add it back to this project as a git submodule
The interface contract between the two repos is the WebSocket protocol -- JSON schemas and binary frame formats documented in docs/ALARM_PROTOCOL.md

Benefits

Independent versioning and release cycle
Pi-side contributors don't need the ESP-IDF toolchain
CI can test the Python servers in isolation
Cleaner separation of concerns between embedded firmware and host services

2.8 KiB Raw Blame History