pi-dashboard/pi/README.md

# Pi Dashboard Servers

WebSocket servers that feed system stats, alarm audio, and status images to the ESP32-S3 RLCD dashboard.

## File Structure

```
pi/
  run_all.py            # Launches both servers as child processes
  stats_server.py       # Real system stats over WebSocket (port 8765)
  contents_server.py    # Alarm audio + status images over WebSocket (port 8766)
  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)
```

## Requirements

Python 3.10+

```
pip install -r requirements.txt
```

Dependencies: `websockets`, `psutil`, `Pillow`

## Running

Start both servers:

```
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 --config path/to.json  # port 8766, custom config
python mock_server.py                        # port 8765, random data (no psutil needed)
```

## Servers

### stats_server.py -- port 8765

Pushes a JSON object every 2 seconds with real system metrics from `psutil`:

- `cpu_pct`, `mem_pct`, `mem_used_mb`, `disk_pct`
- `cpu_temp` (reads `/sys/class/thermal/` as fallback)
- `uptime_hrs`, `net_rx_kbps`, `net_tx_kbps`
- `services` (mocked until systemd integration)
- `local_time` fields for RTC sync (`y`, `mo`, `d`, `h`, `m`, `s`)

### contents_server.py -- port 8766

Serves alarm audio and status images. Protocol:

**Status image:**
1. Text frame: `{"type":"status_image","width":120,"height":120}`
2. Binary frame: 1-bit monochrome bitmap (1800 bytes)

**Alarm audio:**
1. Text frame: `{"type":"alarm_start","sample_rate":N,"channels":N,"bits":N}`
2. Binary frames: raw PCM chunks (4096 bytes each, paced at ~90% real-time)
3. Text frame: `{"type":"alarm_stop"}`

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

Same JSON schema and 2-second push interval as `stats_server.py`, but all values are randomized. No `psutil` dependency -- useful for development on non-Pi machines.

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(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

### image_handler.py

- `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