RF-001: add hardware test plan

docs/rf/RF_001.md

@@ -0,0 +1,152 @@
+# RF-001: аппаратная подготовка и результаты
+
+17 сентября 2026 года. **Аппаратная подготовка не завершена; RF-001A и
+RF-001B не проводились. RF TX = 0.** Этот файл фиксирует уже выполненную
+инвентаризацию основного ПК и оставшиеся проверки. Числа из программных
+RF-001/CLOCK-001 не выдаются за результат эфира.
+
+## Версия проекта и граница работы
+
+| Поле | Значение |
+|---|---|
+| Ветка | `video-development` |
+| HEAD | `3c31bac0da5d4f7eca5e1fbf9cf3b2eb32b5d650` |
+| Коммит | `CLOCK-001: validate independent-clock QPSK receiver` |
+| Основной ПК после коммита | рабочее дерево чистое |
+| Push | не выполнялся |
+| Основной режим будущего теста | QPSK, 500 ксимв/с, FEC 2/3, payload 256 байт, 100 пакетов, пауза 5 мс |
+| Видео / внешний FEC | выключены |
+
+Коммит содержит также файловую подготовку RF-001, от которой зависит
+CLOCK-001. На RX-ноутбуке этот же HEAD **ещё не подтверждён**. До его
+проверки и локального файлового круга 100/100 RF-эксперимент не начинается.
+
+Для передачи коммитов **без push** создан проверенный Git bundle
+`data/raw/rf001/bringup_main_20260917/video005_clock001_from_95f6640.bundle`:
+89 319 байт, SHA-256
+`1d63e918f02f5f6e683f768496f586890dcddf7462c03c37afbab75f2c1bbe39`.
+Он содержит точный `video-development` HEAD и требует, чтобы на RX-ноутбуке
+уже был базовый коммит `95f664076a225b083d5bacee0135831f3c992c93`.
+Файл лежит в игнорируемом Git `data/raw` и **не передан** на второй ноутбук.
+После копирования сначала сверить SHA и `git bundle verify`; при отсутствии
+базового коммита остановиться, а не перестраивать историю. При чистом
+дереве переход на полученный HEAD возможен только fast-forward.
+
+## Инвентаризация основного ПК: TX-узел
+
+Один раз запущен `hackrf_info` из локального комплекта host tools, без RX/TX.
+Исходный вывод сохранён в игнорируемом Git файле
+`data/raw/rf001/bringup_main_20260917/hackrf_info.txt` (SHA-256
+`2f025656208646c0e4bf7df411ca765436ddfc3bfc1942d00643224d9df48f50`).
+Команда завершилась с кодом 0 и обнаружила **одно** устройство:
+
+| Поле | Прочитанное значение |
+|---|---|
+| `hackrf_info` / host library | `2024.02.1` / `2024.02.1 (0.9)` |
+| Board ID | `4 (HackRF One)` |
+| Hardware revision | `r9` |
+| Firmware / API | `2024.02.1` / `1.08` |
+| Serial | `000000000000000097c063dc323b97d3` |
+| Part ID | `0xa000cb3c 0x00744f5a` |
+| USB speed | `NOT_REPORTED_BY_HACKRF_INFO` |
+
+`hackrf_info` также сообщил, что плата не выглядит произведённой Great
+Scott Gadgets. Обозначение Auron HackRF Plus взято из постановки; команда
+определяет совместимый Board ID HackRF One и сама по себе не подтверждает
+изготовителя. Успешное перечисление доказывает доступность устройства по
+USB для управляющей команды, но не пропускную способность 8 Мвыб/с, не
+отсутствие потерь RX и не готовность к TX. Запрос Windows PnP в этой сессии
+вернул отказ доступа (`0x80041003`); скорость USB пока не установлена.
+Прошивка, CPLD, драйвер и конфигурация общей опоры не менялись.
+
+После коммита на основном ПК повторно прочитан сохранённый программный
+`tx_waveform.c64le`: 70 670 624 байта, SHA-256
+`7cd81395efaa88b623b7e4e5a02e3a80b52185007397ea56ceaacc13353974b2`.
+Файловый приём с TX-ведомостью дал **100 CRC-valid и 100 точных пакетов**,
+raw BER 0. Это контроль основного ПК, не проверка второго ноутбука.
+
+## Незавершённые проверки RX-ноутбука
+
+Пользователь сообщил, что удалённый доступ настроен. На основном ПК запущен
+AnyDesk, но доступного в этой сессии канала команд к RX-ноутбуку пока нет:
+единственное устройство в Remote Desktop Commander имеет статус `offline`,
+а интерактивные окна удалённого сеанса здесь не доступны. Принадлежность
+зарегистрированного устройства RX-ноутбуку не подтверждена. Поэтому локальные
+выводы второго ноутбука пока не получены.
+Следующие поля остаются `NOT_RUN`: `hackrf_info` второго SDR, host/firmware,
+serial и USB-подключение; ветка/HEAD/чистота Git; Python и зависимости;
+локальный файловый круг 100/100; RX-only захват 8 Мвыб/с, скорость записи,
+счётчики overruns, размер и SHA исходного IQ, clipping. Значения нельзя
+заменять историческими результатами Lab064 или нулями.
+
+На RX-ноутбуке сначала сохранить полный вывод команд `git status --short`,
+`git branch --show-current`, `git rev-parse HEAD`, `python --version`,
+`git --version`, `hackrf_info`. Затем создать новый каталог для файлового
+TX dry-run и запустить `tools/qpsk_rf_rx.py` на сохранённом IQ с TX-ведомостью.
+Требование: 100 сгенерированных, 100 CRC-valid и 100 точных пакетов. Эти
+команды не открывают SDR, кроме отдельно названного `hackrf_info`.
+
+После проверки Git и установки зависимостей файловый круг можно запустить
+на RX-ноутбуке из корня проекта так, чтобы не перезаписать старый результат:
+
+```powershell
+$run = Get-Date -Format 'yyyyMMdd_HHmmss'
+$directory = Join-Path 'data/raw/rf001' "rx_laptop_offline_$run"
+python -B -X utf8 tools/qpsk_rf_tx.py --output-dir $directory
+python -B -X utf8 tools/qpsk_rf_rx.py `
+  --iq-file (Join-Path $directory 'tx_waveform.c64le') `
+  --truth-metadata (Join-Path $directory 'tx_metadata.json') `
+  --report "data/processed/rf001/rx_laptop_offline_${run}.json"
+```
+
+Полный JSON и stdout обеих команд нужно сохранить. Нельзя делать вывод
+«100/100 на втором ноутбуке» по готовому отчёту основного ПК.
+
+RX-only проба на втором ноутбуке допустима только после этих проверок.
+Сначала сохранить **исходный** `cs8` IQ и stdout/stderr инструмента, затем
+сверить число отсчётов и SHA, все промежуточные и финальные наблюдения
+overrun, насыщение кодов I/Q и скорость записи. Ненулевой, нечистый или
+неполный счётчик запрещает PASS и переход к RF TX. Формат захвата и поля
+metadata описаны в `RF_001_PLAN.md`. Пока RX-only проба **не выполнялась**.
+
+## Будущие RF-001A и RF-001B
+
+| Метрика | RF-001A, общая 10 МГц | RF-001B, независимые такты | Разница |
+|---|---|---|---|
+| Захват, состояние счётчиков | NOT_RUN | NOT_RUN | NOT_ESTIMATED |
+| Точные пакеты из 100 / доля успеха | NOT_RUN | NOT_RUN | NOT_ESTIMATED |
+| Raw BER / ошибки после FEC | NOT_RUN | NOT_RUN | NOT_ESTIMATED |
+| Отказы CRC / пропуски / дубли | NOT_RUN | NOT_RUN | NOT_ESTIMATED |
+| CFO, изменение CFO, timing drift | NOT_RUN | NOT_RUN | NOT_ESTIMATED |
+| Оценка разницы sample clocks | NOT_RUN | NOT_RUN | NOT_ESTIMATED |
+| Время приёмника | NOT_RUN | NOT_RUN | NOT_ESTIMATED |
+
+RF-001A возможен после завершения bring-up и свежей проверки общей опоры.
+RF-001B требует отдельного сеанса с отключённым проводом CLKOUT → CLKIN;
+остальные RF-параметры, уровни, антенны и геометрия должны совпасть с A.
+Каждый сеанс сохраняет свой raw IQ, metadata, ожидаемые SHA пакетов, полные
+логи и результат файлового приёмника. Реальный ppm оценивать только по
+фактическим данным B; если оценка ненадёжна, писать
+`NOT_RELIABLY_ESTIMATED`. Программный результат CLOCK-001 не задаёт ppm плат.
+
+Для каждого выхода в эфир нужны свежий аппаратный preflight и отдельное
+прямое разрешение на TX. Одного успешного `hackrf_info`, программных 100/100
+или исторической проверки общей опоры недостаточно. Критерий первого
+короткого опыта: 99–100 точных пакетов — GOOD, 95–98 — PARTIAL, менее 95 —
+не переходить к видео. Один прогон не даёт статистического доказательства;
+повторы требуют отдельного согласования и сохранения каждого захвата.
+
+## Текущее решение
+
+| Поле | Статус |
+|---|---|
+| RF-001 hardware bring-up | **INCOMPLETE**: основной узел перечислен, RX-узел не проверен |
+| RF-001A common clock | **NOT_RUN**, exact packets `null` |
+| RF-001B independent clocks | **NOT_RUN**, exact packets `null` |
+| Measured CFO / sample-clock offset / timing drift | **NOT_MEASURED** |
+| Common-clock advantage | **NOT_ESTIMATED** |
+| Independent-clock architecture | **UNDECIDED** по аппаратным данным |
+| Следующий шаг | RX-ноутбук: инвентаризация → тот же HEAD → офлайн 100/100 → RX-only проба |
+| RF TX / video / push | **0 / OFF / NOT PERFORMED** |
+
+RF-002 не начинается автоматически.