sound-analyze/services/collector/README.md

services/collector

Назначение

Сервис, который читает бинарные пакеты с STM32 через USB CDC, валидирует и логирует их, пишет данные в TimescaleDB и рассылает в реальном времени по WebSocket.

Основные компоненты

• serial_reader.py — асинхронное чтение порта SERIAL_PORT (/dev/ttyACM0 по умолчанию), non‑blocking read, reconnect‑логика.
• protocol_parser.py — парсер протокола: поиск SOF, проверка длины, CRC‑8/ATM, конвертация rms_db_x10 → float.
• audio_validator.py — проверка диапазонов: rms_db ∈ [-50.0, 0.0], frequency_hz ∈ [100, 8000], детекция и пометка тишины.
• db_writer.py — batch‑запись в PostgreSQL/TimescaleDB (audio_data), батч по количеству/таймеру.
• ws_app.py + ws_manager.py — WebSocket сервер, который бродкастит последние метрики всем подписчикам.
• monitor.py — вывод статистики: пакетов/с, CRC‑ошибки, length‑ошибки, range‑ошибки.

Формат данных в WebSocket

{
  "time": "2025-12-25T19:00:00Z",
  "rms_db": -18.5,
  "freq_hz": 440
}

Время берётся по хосту при приёме пакета, а не из MCU‑таймстампа, чтобы быть в одной временной зоне с БД.

Конфигурация

Через переменные окружения (см. .example.env и docker-compose.yml):

• SERIAL_PORT, BAUDRATE.
• DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD.
• WS_HOST, WS_PORT (по умолчанию 0.0.0.0:8000, наружу проброшен как 8001).