Prepare coordinated RF-001A OTA test

docs/rf/RF_001A_PREPARATION.md

@@ -0,0 +1,75 @@
+# RF-001A: подготовка опыта с общей опорой 10 МГц
+
+Текущее состояние: **PREPARED_NOT_RUN**. Передача в эфир, общий такт и двухузловой захват в этой задаче не проверялись. Единый источник параметров: [rf001a_common_clock.json](../../configs/rf/rf001a_common_clock.json). Перед каждым опытом оба узла сверяют с ним настройки. Проверка `tools/rf001a_prepare.py` отвергает расхождение spec с действующими константами TX и VIDEO-005 RX. Новый PHY не добавлен.
+
+## Подготовленные файлы на основном ПК
+
+`python -B -X utf8 tools/rf001a_prepare.py --output-dir data/raw/rf001/<новый_уникальный_каталог>` создаёт исходный `tx_waveform.c64le`, прежнюю TX-ведомость `tx_metadata.json` с seed, порядком 0…99 и SHA каждого пакета, `tx_waveform.cs8` и `rf001a_metadata.json`. Каталог должен быть новым. Файлы лежат в игнорируемом Git `data/raw/`; их нельзя добавлять в коммит. Текущий локальный экземпляр: `data/raw/rf001/rf001a_common_clock_001/`.
+
+| Параметр | Проверенное значение |
+|---|---:|
+| TEST ID | `RF001A_COMMON_CLOCK_001` |
+| Идентификатор прежнего TX/RX формата metadata | `RF001_QPSK_500K_R23_256B_100P_GAP5MS` |
+| QPSK, FEC, payload, packets, gap | 500000 симв/с, 2/3, 256 байт, 100, 5 мс |
+| Seed | 20260917 |
+| Центр RF / частота отсчётов | 1400000000 Гц / 8000000 отсчётов/с |
+| Цифровое смещение | +125000 Гц: `RF_001_PLAN.md` и `protocol/video005_iq_waveform.py` |
+| Длина TX | 8833828 комплексных отсчётов; 1,1042285 с |
+| Исходный c64le | 70670624 байта; SHA256 `7cd81395efaa88b623b7e4e5a02e3a80b52185007397ea56ceaacc13353974b2` |
+| Компонентный peak / комплексный RMS | 0,3949069381 / 0,1854172647 в исходных единицах |
+| HackRF cs8 | 17667656 байт; SHA256 `75f3fa39bfa4ee419f0676c54e4b9c486d7ff64bd0fe2fc06343b20c9d117ecd` |
+| cs8 | signed int8, чередование I/Q, множитель 256 кодов на единицу источника |
+| Проверка cs8 | 0 кодов -128/127; обратное чтение совпало с ожидаемыми квантованными отсчётами; максимальная ошибка компоненты 0,001953125 |
+| Офлайн-приём именно cs8 | 100/100 CRC-valid, 100/100 exact, существующий `qpsk_rf_rx.py` → VIDEO-005 receiver |
+
+Проверить файлы повторно: `python -B -X utf8 tools/rf001a_prepare.py --verify-dir data/raw/rf001/rf001a_common_clock_001`. Затем `python -B -X utf8 tools/qpsk_rf_rx.py --iq-file data/raw/rf001/rf001a_common_clock_001/tx_waveform.cs8 --iq-format cs8 --truth-metadata data/raw/rf001/rf001a_common_clock_001/tx_metadata.json --report data/raw/rf001/<новый_отчёт>.json`. Отчёт нельзя перезаписывать. Метаданные TX сохраняют прежний идентификатор, который проверяет существующий RX; `rf001a_metadata.json` связывает их с новым ID опыта. Истина применяется после работы приёмника.
+
+## Настройки оборудования для следующего, отдельно разрешённого сеанса
+
+Предусмотрены TX VGA 20 дБ (`-x 20`), RX LNA 24 дБ (`-l 24`), RX VGA 24 дБ (`-g 24`), RF amplifier OFF (`-a 0`), питание антенны OFF (`-p 0`). Это baseline Lab066; назначения флагов и шаги проверены по установленному `hackrf_transfer -h`. На основном ПК `hackrf_info` обнаружил HackRF One r9, serial `000000000000000097c063dc323b97d3`, libhackrf/firmware 2024.02.1, API 1.08. Название устройства в задаче: Auron HackRF Plus. RX serial надо заново снять на ноутбуке; не переносить serial TX на RX.
+
+Общая опора: 10 МГц reference → MASTER → MASTER CLKOUT → SLAVE CLKIN. Старые `reg29=0x26` на обоих устройствах и `SLAVE CLKIN=DETECTED` из `RF_001_PLAN.md` не доказывают текущую синхронизацию. Перед будущим TX требуется ручная отметка `COMMON CLOCK VERIFIED = YES` после свежей проверки MASTER/SLAVE, проводов и признака CLKIN на SLAVE. Также вручную подтвердить подключённые антенны, оба USB, согласованную поляризацию и безопасную дистанцию. Если прежняя геометрия применима, около 1,2 м, LOS, одинаковая поляризация. Прямой кабель TX RF → RX RF допустим лишь с нужным ослаблением. Геометрию A/B не менять.
+
+**Будущая команда TX, только для подготовки, не запускать сейчас:**
+
+```powershell
+& 'C:\Users\user\Tools\HackRF\Library\bin\hackrf_transfer.exe' -d 000000000000000097c063dc323b97d3 -t data/raw/rf001/rf001a_common_clock_001/tx_waveform.cs8 -f 1400000000 -s 8000000 -n 8833828 -x 20 -a 0 -p 0 -B
+```
+
+Она однократная, без `-R`. Прежде чем дать отдельное разрешение на TX, сверить SHA cs8, RX READY, физический checkpoint и общую опору. Пока `RF TX = 0`.
+
+RX готовит новый каталог и конечный захват 20 с: 160000000 комплексных отсчётов cs8, ровно 320000000 байт (около 320 MB или 305,2 MiB). До захвата проверить свободное место с запасом. RX запускается первым, пользователь видит активный захват, затем отдельно разрешённый TX делает одну передачу; оба процесса завершаются, raw IQ и полные stdout/stderr сохраняются, тот же raw IQ анализируется офлайн. Не принимать неизвестные промежуточные или конечные underrun/overrun за ноль.
+
+## Форма отчёта будущего опыта
+
+```text
+TEST ID =
+CLOCK MODE = COMMON 10 MHz
+CENTER FREQUENCY =
+SAMPLE RATE =
+MODULATION = QPSK
+SYMBOL RATE = 500 ksymbol/s
+INNER FEC = 2/3
+PAYLOAD = 256 bytes
+GAP = 5 ms
+TX PACKETS = 100
+DETECTED PREAMBLES =
+CRC VALID PACKETS =
+EXACT PACKETS =
+PACKET SUCCESS RATE =
+RAW BER =
+POST-FEC ERROR RATE =
+MISSING PACKETS =
+DUPLICATES =
+CFO MEDIAN =
+CFO P95 =
+TIMING OFFSET =
+TIMING DRIFT =
+TX UNDERRUNS =
+RX OVERRUNS =
+RX CLIPPING =
+RAW IQ SHA256 =
+RESULT = GOOD / PARTIAL / FAIL
+```
+
+Для первого smoke test 99–100 exact = GOOD, 95–98 = PARTIAL/DIAGNOSTIC, <95 = FAIL FOR VIDEO PROGRESSION. Один прогон не подтверждает статистическую надёжность. Неизмеренное поле помечать `NOT_MEASURED`, отсутствующий счётчик `NOT_REPORTED`. RF-001B сейчас только план: повторить опыт без общей опоры при тех же частотах, sample/symbol rate, FEC, payload, gap, gain, антеннах и геометрии. RF-001B не запускать.