docs: добавлены README.md

README.md

@@ -0,0 +1,56 @@
+# STM32 Audio Analyzer
+
+STM32 Audio Analyzer — система реального времени для измерения уровня звука и доминантной частоты на базе STM32F103C8T6 (Blue Pill) с веб‑дашбордом и хранением истории в TimescaleDB.
+
+Микроконтроллер оцифровывает сигнал с MAX4466, считает RMS (dBFS) и FFT (512 точек), отсылает метрики по USB CDC; на ПК коллектор пишет данные в PostgreSQL/TimescaleDB, FastAPI отдаёт REST/WS, React‑фронтенд показывает текущие значения и историю.
+
+## Архитектура
+
+- **MCU (firmware)**
+  - STM32F103C8T6, FreeRTOS, TinyUSB, CMSIS‑DSP.
+  - ADC1 + DMA (circular, double‑buffer 2×512) с триггером от TIM3, частота дискретизации 22.05 кГц.
+  - Обработка: удаление DC, RMS в dBFS, Hann‑окно, RFFT 512, поиск пика 100–8000 Гц.
+  - Передача каждые 100 мс пакетом 12 байт по USB CDC.
+
+- **Collector (Python)**
+  - Читает бинарный протокол с /dev/ttyACM0, ресинхронизация по SOF=0xAA.
+  - Проверка CRC‑8/ATM, диапазонов, подсчёт статистики ошибок.
+  - Запись в TimescaleDB (`audio_data`), параллельно пушит JSON по WebSocket (`ws://…/ws/live`).
+
+- **API (FastAPI)**
+  - REST `/api/v1/audio/latest|range|export/csv`, `/api/v1/stats/summary`, `/api/v1/events/loud`.
+  - База: `audio_data` + непрерывный агрегат `audio_data_1min` (avg/max/min/доминирующая частота, доля тишины).
+
+- **Frontend (React + Vite)**
+  - Live‑дашборд: вертикальный аудио‑метр, peak‑hold за 3 секунды, история частоты, текущая нота.
+  - Источник данных — WebSocket `VITE_WS_URL`, REST для исторических запросов при необходимости.
+
+## Структура репозитория
+
+```text
+.
+├── README.md
+├── docker-compose.yml
+├── db/
+│   └── init.sql          # схема TimescaleDB + агрегаты/retention
+├── firmware/             # прошивка STM32 (FreeRTOS + TinyUSB + CMSIS-DSP)
+└── services/
+    ├── collector/        # serial→WS→DB
+    ├── api/              # FastAPI REST + DB
+    └── frontend/         # React/Vite дашборд
+```
+
+## Быстрый старт
+
+```
+git clone --recurse-submodules <repo>
+```
+```bash
+cp .example.env .env
+docker compose up --build
+```
+
+- БД: TimescaleDB на `localhost:5432` (`DB_NAME=audio_analyzer` по умолчанию).
+- API: `http://localhost:8000/api/v1`.
+- WebSocket коллектора: `ws://localhost:8001/ws/live`.
+- Frontend: `http://localhost:3000` (dev‑режим Vite).