Alarm Audio Streaming Protocol

Overview

The Raspberry Pi streams alarm audio to the ESP32-S3 over a dedicated WebSocket connection on port 8766. The protocol uses mixed text and binary frames — text for control messages, binary for raw PCM data.

Connection

Parameter	Value
Port	8766
Transport	WebSocket
Direction	Pi (server) → ESP32 (client)

The ESP32 connects and stays connected. The server initiates alarm playback when needed.

Message Sequence

Pi                          ESP32
 │                            │
 │◄──── WS connect ──────────│
 │                            │
 │  (idle until alarm fires)  │
 │                            │
 ├─ alarm_start (text) ──────►│  → open codec
 ├─ PCM chunk (binary) ──────►│  → queue + play
 ├─ PCM chunk (binary) ──────►│
 │  ...                       │
 ├─ alarm_stop (text) ────────►│  → drain + close codec
 │                            │

Control Messages (Text Frames)

alarm_start

Sent before the first PCM chunk. The ESP32 uses these parameters to configure the DAC.

{
  "type": "alarm_start",
  "sample_rate": 24000,
  "channels": 2,
  "bits": 16
}

alarm_stop

Sent after the last PCM chunk.

{
  "type": "alarm_stop"
}

PCM Data (Binary Frames)

Format: Raw signed 16-bit little-endian, interleaved stereo (L, R, L, R, ...)
Chunk size: 4096 bytes (1024 stereo samples at 16-bit)
Pacing: Chunks sent at ~90% real-time speed to maintain buffer without overflow
Byte order: Little-endian (native for both Pi and ESP32)

At 24kHz / 2ch / 16-bit:

Bytes per second: 96,000
Chunk duration: ~42.7 ms
Send interval: ~38.4 ms (90% pacing)

ESP32 Buffering

FreeRTOS queue: 10 slots of pointer-to-chunk
Total buffer capacity: ~427 ms of audio
Overflow policy: drop chunk and log warning

Future: Alarm Scheduling

Not yet implemented. Planned JSON format for alarm configuration:

{
  "alarm_time": "070000",
  "alarm_days": ["Mon", "Tue", "Wed"],
  "alarm_audio": "path/to/file.wav"
}

2.2 KiB Raw Blame History