docs cleanup and disk usage target change

pi/README.md

@@ -12,7 +12,10 @@ pi/
   mock_server.py        # Drop-in replacement for stats_server with random data
   audio_handler.py      # WAV loading, PCM chunking, alarm streaming
   image_handler.py      # PNG to 1-bit monochrome conversion, alpha compositing
+  alarm_scheduler.py    # Loads and validates alarm config, checks firing schedule
   requirements.txt
+  config/
+    alarms.json         # Alarm schedule configuration
   assets/
     alarm/              # WAV files for alarm audio
     img/                # Status images (idle.png, on_alarm.png)
@@ -33,15 +36,16 @@ Dependencies: `websockets`, `psutil`, `Pillow`
 Start both servers:
 
 ```
-python run_all.py
+python run_all.py                        # both servers, default config
+python run_all.py --config path/to.json  # both servers, custom config
 ```
 
 Or run individually:
 
 ```
-python stats_server.py      # port 8765 only
-python contents_server.py   # port 8766 only
-python mock_server.py       # port 8765, random data (no psutil needed)
+python stats_server.py                       # port 8765 only
+python contents_server.py --config path/to.json  # port 8766, custom config
+python mock_server.py                        # port 8765, random data (no psutil needed)
 ```
 
 ## Servers
@@ -69,7 +73,7 @@ Serves alarm audio and status images. Protocol:
 2. Binary frames: raw PCM chunks (4096 bytes each, paced at ~90% real-time)
 3. Text frame: `{"type":"alarm_stop"}`
 
-On connect, sends `idle.png` as the status image. Alarm cycles switch to `on_alarm.png` during playback, then back to `idle.png`.
+Loads alarm config from `config/alarms.json` (override with `--config`). Checks schedule every 5 seconds, fires once per matched minute. If no config or empty config, sends idle image and blocks forever. On alarm: switches to alarm image, streams audio, switches back to idle.
 
 ### mock_server.py -- port 8765
 
@@ -77,11 +81,43 @@ Same JSON schema and 2-second push interval as `stats_server.py`, but all values
 
 Does not include `local_time` fields.
 
+## Alarm Configuration
+
+Config file: `config/alarms.json` -- a single alarm object or an array of alarm objects.
+
+Example with two alarms:
+
+```json
+[
+  {
+    "alarm_time": "0730",
+    "alarm_days": ["Mon", "Tue", "Wed", "Thu", "Fri"],
+    "alarm_audio": "assets/alarm/alarm_test.wav",
+    "alarm_image": "assets/img/on_alarm.png"
+  },
+  {
+    "alarm_time": "2300",
+    "alarm_audio": "assets/alarm/sleep.wav",
+    "alarm_image": "assets/img/sleep.png"
+  }
+]
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `alarm_time` | `string` | Yes | 4-digit HHMM, 24-hour. Fires on the matched minute. |
+| `alarm_days` | `string[]` | No | 3-letter abbreviations: `Mon`–`Sun`. If omitted, fires every day. |
+| `alarm_dates` | `string[]` | No | `MM/DD` strings. Ignored if `alarm_days` is also set. |
+| `alarm_audio` | `string` | No | WAV path, relative to `pi/`. Default: `assets/alarm/alarm_test.wav`. |
+| `alarm_image` | `string` | No | Status PNG path, relative to `pi/`. Default: `assets/img/on_alarm.png`. |
+
+If both `alarm_days` and `alarm_dates` are present, `alarm_days` takes priority.
+
 ## Modules
 
 ### audio_handler.py
 
-- `find_wav()` -- finds the first `.wav` in `assets/alarm/`
+- `find_wav(path=None)` -- uses the given path if it exists, otherwise falls back to glob in `assets/alarm/`
 - `read_wav(path)` -- reads WAV, returns `(pcm_bytes, sample_rate, channels, bits)`
 - `stream_alarm(ws, pcm, sr, ch, bits)` -- streams one alarm cycle over WebSocket
 
@@ -89,3 +125,8 @@ Does not include `local_time` fields.
 
 - `load_status_image(path)` -- loads PNG, composites transparency onto white, converts to 1-bit 120x120 monochrome bitmap (black=1, MSB-first)
 - `send_status_image(ws, img_bytes)` -- sends status image header + binary over WebSocket
+
+### alarm_scheduler.py
+
+- `load_config(path)` -- reads and validates alarm JSON; returns list of alarm dicts or `None`
+- `should_fire(config)` -- checks a single alarm entry against current local time