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

2025-12-29 03:43:25 +03:00
parent 804527133c
commit e61f4720bc
4 changed files with 204 additions and 0 deletions
--- a/firmware/README.md
+++ b/firmware/README.md
@@ -0,0 +1,74 @@
+# firmware/
+
+## Цель
+
+Прошивка для Blue Pill, которая снимает аудио с MAX4466, считает уровень в dBFS и доминантную частоту, мигает LED с частотой звука и публикует метрики по USB CDC в формате фиксированного бинарного пакета.
+
+## Железо
+
+- STM32F103C8T6 (Blue Pill, 72 МГц, 64К Flash, 20К RAM).
+- Микрофон: MAX4466 (выход → **PA1 / ADC1_IN1**, питание 3.3 В).
+- USB FS через TinyUSB CDC (Virtual COM).
+- Светодиод: PC13 (on = 0, off = 1).
+
+## Обработка аудио (DSP)
+
+- Частота дискретизации: 22050 Гц (`AUDIO_SAMPLE_RATE`).
+- DMA‑буфер: 2×512 выборок `uint16_t` (двойная буферизация через half/full interrupt).
+- RMS считается по формуле \(\mathrm{RMS} = \sqrt{\frac{1}{N}\sum\_{i=1}^{N} x_i^2}\) после удаления среднего и нормализации к диапазону около \([-1, 1]\).
+- Перевод в dBFS: \(\mathrm{dBFS} = 20 \log\_{10} (\mathrm{RMS} + \varepsilon)\), где \(\varepsilon\) — малый стабилизатор для нуля.
+- FFT: `arm_rfft_fast_f32` на 512 точках, Hann‑окно рассчитывается “на лету” через `arm_cos_f32`.
+- Поиск пика по модулю `mag[k]` в диапазоне частот 100–8000 Гц, шаг частоты \( \Delta f = \frac{22050}{512} \approx 43 \text{ Гц} \).
+
+## Протокол
+
+Пакет фиксированного размера 12 байт:
+
+```c
+// firmware/App/Inc/protocol.h + protocol.c
+[SOF=0xAA][TYPE=0x02][LEN=0x08]
+[timestamp_ms: uint32]
+[rms_db_x10: int16]      // dBFS * 10, ожидается -50.0 .. 0.0
+[frequency_hz: uint16]   // 100 .. 8000
+[crc8: uint8]            // CRC-8/ATM
+```
+
+- CRC: CRC‑8/ATM (poly=0x07, init=0x00, без отражения), считается по байтам с индексами 1..10.
+
+## FreeRTOS задачи
+
+- `audio_process_task`
+  - Ждёт уведомление от ISR DMA, обрабатывает последний буфер (512 сэмплов).
+  - Вычисляет метрики, обновляет режим LED, отправляет метрику в очередь для USB‑задачи.
+
+- `cdc_task`
+  - Читает из очереди, упаковывает в `protocol_pack_v1`, пишет в USB CDC, целевая частота ~10 Гц.
+
+- `health_led_task`
+  - Настраивает PC13 и мигает в зависимости от частоты/уровня сигнала, плюс подкармливает watchdog.
+
+## Сборка и прошивка
+
+- Зависимости: `arm-none-eabi-gcc`, `make`, `st-flash`.
+- Сборка:
+
+```bash
+cd firmware
+make
+```
+
+- Прошивка (через ST‑Link):
+
+```bash
+make flash
+```
+
+## Зависимости
+
+| Библиотека          | Путь                                         | Репозиторий                                                         |
+| ------------------- | -------------------------------------------- | ------------------------------------------------------------------- |
+| **CMSIS-Core**      | `firmware/Drivers/CMSIS/Core`                | [ST GitHub](https://github.com/STMicroelectronics/cmsis_core)
+| **CMSIS-Device F1** | `firmware/Drivers/CMSIS/Device/ST/STM32F1xx` | [ST GitHub](https://github.com/STMicroelectronics/cmsis_device_f1)  |
+| **FreeRTOS**        | `firmware/Middlewares/FreeRTOS`              | [FreeRTOS-Kernel](https://github.com/FreeRTOS/FreeRTOS-Kernel)      |
+| **TinyUSB**         | `firmware/Middlewares/TinyUSB`               | [hathach/tinyusb](https://github.com/hathach/tinyusb)               |
+| **CMSIS-DSP**       | `firmware/Middlewares/CMSIS-DSP`             | [ARM-software/CMSIS-DSP](https://github.com/ARM-software/CMSIS-DSP) |