Lab056: compare 20 and 500 ksymbol/s in controlled RF session

docs/lab056_current_state.md

@@ -0,0 +1,326 @@
+# Lab056 — подготовка сравнения 20 и 500 ксимв/с в одной сессии
+
+Подготовка 9 сентября 2026 года; корректировка OTA 10 сентября 2026 года.
+Lab056 завершила единственный разрешённый OTA ABAB-сеанс 10 сентября.
+Принятая мощность B/A +0,108895 дБ, коэффициент передачи по мощности
+−0,163042 дБ, энергия символа −13,870505 дБ. Прежний провал 15,41 дБ
+не воспроизвёлся. [Полный RF-отчёт](lab056_rf_result.md).
+Выполненных передач 1, повторов 0; **RF TX сейчас = 0, STOP**.
+Ниже сохранено описание этапов подготовки и preflight; актуальный итог
+приведён в RF-отчёте и в заключительном блоке состояния.
+
+Простыми словами: для будущего опыта создан файл, который дважды чередует
+медленную и быструю передачу с практически одинаковой цифровой амплитудой.
+Анализатор на искусственных записях различает равное усиление и падение на 6 дБ.
+Как изменятся полезный принятый сигнал и фон между A/B в реальном эфире,
+ещё не измерено; пока записан только RX-фон без TX.
+Одинаковый TX VGA и одинаковая цифровая мощность не доказывают одинаковую
+мощность на выходе HackRF. Для абсолютных ватт/dBm нужен калиброванный прибор.
+
+## Зафиксированная база и границы задания
+
+По новому явному разрешению пользователя создан коммит Lab055:
+
+`5add95ecb8865f59075bbbced08d97b183fb3b48`
+
+`Lab055: audit received signal energy across symbol rates`
+
+В коммите ровно семь файлов: анализатор и тесты Lab055, её отчёт, два JSON
+результата, только запись 046 журнала и только раздел Lab055 индекса.
+Предшествующие незакоммиченные изменения Lab054 сохранены в рабочем каталоге.
+Перед коммитом quick_gate: 823 теста, 28 функциональных проверок, 13 штатных
+пропусков; pytest: 823 passed, 0 failed. Push не выполнялся.
+
+Lab055 установила почти равную цифровую мощность активного TX
+(1950,308/1950,598 код²), снижение согласованной RX-компоненты на 15,413 дБ
+и сопоставимый фон в одинаковой полосе. Разные аппаратные сессии не позволяют
+приписать это снижение одной скорости. Lab054 остаётся **NOT_A, 0/16**.
+Повторно проверены все 34 SHA-256 входов Lab055: изменений нет.
+
+Пользователь осознанно изменил методику: необходимого SMA-переходника нет,
+поэтому сейчас выполняется подготовка контролируемого эфирного ABAB.
+Кабельный контроль TX → 30 дБ → RX отложен до получения переходника
+и будет отдельной проверкой, без автоматического запуска после Lab056.
+
+Схема: MASTER TX → TX-антенна → свободное пространство → RX-антенна → SLAVE RX.
+На всю ABAB сохраняются антенны, кабели, одинаковая поляризация, расстояние,
+ориентация, положение оборудования, частота, усиления и common clock.
+Антенны не трогают; по возможности исключают движение людей возле них.
+Внешние PA и LNA, в том числе TQP3M9037, не используются.
+
+`RF_FREQ = USER_AUTHORIZED_RF_HZ = 1400000000`: значение сообщил пользователь.
+Частоту, разрешённую для лаборатории, определяет пользователь. Страна и
+границы национальных диапазонов больше не являются обязательными полями
+runner; повторное исследование национальной регуляторики не проводилось.
+1400 МГц не подставляется по умолчанию. Mock-значения 915/916 МГц также
+не являются выбором частоты для аппаратного опыта.
+
+| Параметр эфирной схемы | Текущее значение |
+|---|---|
+| Центральная RF-частота | 1400000000 Гц, только лабораторная Lab056 |
+| TX-антенна / RX-антенна | Имеющиеся антенны 1400 МГц по описанию пользователя; модели/маркировка не сообщены |
+| Расстояние TX–RX | Примерно 3–5 м по заданию; точное измерение не сообщено |
+| Взаимная ориентация и поляризация | Одинаковые, антенны неподвижны, по заданию пользователя |
+| Прямая видимость LOS / отсутствие прямой видимости NLOS | LOS |
+
+После конкретного RF_FREQ выполнен аппаратный RX-only preflight, PASS.
+Сейчас STOP. TX — только после отдельного разрешения на один ABAB-сеанс.
+Само сообщение частоты не является разрешением на TX. Частота 1400 МГц
+не назначена рабочей частотой SDR_Rover: ориентир около 180 МГц и варианты
+50/144 МГц рассматриваются отдельно, вне Lab056.
+
+## Подготовленный TX
+
+Файл: `data/raw/lab056/tx_abab.cs8`, signed int8 IQ, 21 177 088 байт.
+SHA-256: `5b34bbe1a8e6d037d2d6d367a74e9eb84e8940db7da61600ffaa7f7497d4f600`.
+Параметры сохранены в `data/raw/lab056/tx_metadata.json` и
+[preparation.json](../data/processed/lab056/preparation.json).
+
+Используются прежние PRBS7, BPSK и RRC из тракта Lab043/Lab042:
+roll-off 0,35, span 10 символов, защитные участки по 16 символов.
+Fs = 8 000 000 комплексных отсчётов/с, цифровая несущая +50 кГц.
+Алгоритмы PHY/FEC/CRC, пороги и штатный приёмник не изменялись.
+
+| Параметр | A: 20 ксимв/с | B: 500 ксимв/с |
+|---|---:|---:|
+| Отсчётов на символ | 400 | 16 |
+| Полезных PRBS7-символов | 4096 | 102400 |
+| Длительность активных символов | 0,204800 с | 0,204800 с |
+| Длительность сегмента с защитными участками | 0,206900 с | 0,204884 с |
+| RMS всего сегмента после int8 | 44,004413 код | 44,001925 код |
+| Средняя мощность всего сегмента | 1936,388382 код² | 1936,169379 код² |
+| RMS активного участка | 44,227281 код | 44,010867 код |
+| Средняя мощность активного участка | 1956,052408 код² | 1936,956395 код² |
+| Клиппинг | 0 | 0 |
+
+Разница средней мощности B/A всего сегмента: **−0,000491 дБ**,
+критерий подготовки |разница| ≤ 0,01 дБ выполнен. Активные участки отличаются
+на −0,042606 дБ из-за разной доли защитных участков; это явно сохранено
+в метаданных и учитывается при сравнении коэффициента передачи.
+RMS указан в кодах, средняя мощность — RMS² в код².
+
+Последовательность: gap → A1 → gap → B1 → gap → A2 → gap → B2 → gap.
+Каждый gap длится 0,1 с. A1 и A2 совпадают побайтно; B1 и B2 тоже.
+Один файл содержит 10 588 544 комплексных отсчёта, **1,323568 с**.
+План RX: 24 000 000 отсчётов, **3 с**, запуск на 0,5 с раньше TX.
+
+Важно: gap — нулевые цифровые IQ при работающем TX-процессе.
+Это не выключение передатчика; утечка несущей и собственный фон возможны.
+Полная длительность файла включает эти участки.
+
+## Измерения сохранённого RX
+
+Анализатор `experiments/lab056_abab_energy.py` сначала ищет всю ABAB
+корреляцией с известным TX: шаг 32 отсчёта, сетка остаточного частотного
+смещения (CFO) от −2 до +2 Гц с шагом 0,25 Гц. Затем существующий метод
+Lab055 уточняет задержку, CFO, фазу, постоянное смещение и комплексный
+коэффициент на обучающих плитках; мощность компоненты и остатка проверяется
+на отдельных плитках. При недостаточном совпадении результат UNKNOWN.
+Порог 0,05 относится только к этой диагностической локализации;
+он не меняет пороги PHY/CRC и не даёт независимого приёма пакетов.
+
+Прореживание без фильтра используется только при грубом поиске. Мощности
+и спектры вычисляются по исходным полным отсчётам. RX не масштабируется
+для искусственного выравнивания A/B.
+
+Для каждого A1/B1/A2/B2 сохраняются:
+
+- Полная средняя IQ-мощность `mean(|r|²)` и мощность после удаления среднего
+  (AC), RMS, постоянное смещение, пик и клиппинг.
+- Два ближайших окна фона по 60 мс в соседних нулевых цифровых участках.
+  Дополнительно — доступные окна по 50 мс вне всей последовательности.
+  Внешние окна нельзя автоматически назвать RF OFF без проверки времён
+  запуска/остановки: в текущей подготовке аппаратного фона ещё нет.
+- Разность AC-мощности и среднего локального фона. Разброс оценивается
+  по неперекрывающимся блокам 4 мс, включая отличие фона до и после сегмента.
+  Если превышение не больше трёх оценок неопределённости, итоговая мощность
+  полезного сигнала `null`, а исходная разность сохраняется. Это критерий
+  численной устойчивости, не калиброванный доверительный интервал.
+- Комплексный коэффициент `h = sum(conj(s)*r) / sum(|s|²)` после согласования
+  и удаления постоянного смещения; сравнивается `|h|²`.
+- Мощность согласованной компоненты и остатка. Остаток включает шум и
+  искажения, которые не описывает модель; это не чистый тепловой шум.
+- Интегральная мощность спектра Welch в полосах 27 и 675 кГц вокруг
+  +50 кГц. Для A штатная полоса 27 кГц, для B — 675 кГц;
+  обе полосы записываются также для сравнения фона в одинаковых условиях.
+
+Отдельно для двух пар сохраняются B/A в дБ по принятой мощности после
+вычитания фона, по `|h|²`, по согласованной компоненте и по её энергии
+символа `P/Rs`. Единицы мощности — коды RX², энергии — код²·с;
+это относительные цифровые оценки, не калиброванные ватты и джоули.
+При одинаковой принятой мощности рост скорости в 25 раз даст уменьшение
+энергии символа на 13,9794 дБ. Равенство принятой мощности сначала проверяется.
+
+Корректировка добавляет явный вывод `h.real`, `h.imag` и фазы относительно
+начала активного участка. Он вычисляется на тех же обучающих плитках
+при уже найденном CFO; его модуль проверяется на совпадение с моделью
+Lab055. Алгоритм согласования и разделение обучения/проверки сохранены.
+
+Отдельно выводятся A2/A1 и B2/B1: полная raw-мощность, фон, полезная
+мощность после вычитания фона, `|h|²` и согласованная компонента.
+Итоговые X/Y/Z в `comparison_summary` используют отношение средних
+линейных мощностей двух B к двум A. X — полезная принятая мощность
+после вычитания фона, Y — `|h|²`, Z — энергия символа этой же полезной
+мощности. Если вычитание фона неустойчиво хотя бы в одном сегменте,
+X/Z остаются `null`; компонентные метрики и повторяемость сохраняются.
+
+## Проверка искусственными записями
+
+Созданы две явно синтетические записи CS8 по 3 с: одинаковое усиление
+обоих режимов и уменьшение амплитуды B вдвое (мощность −6,020600 дБ).
+В модель добавлены шум, постоянное смещение, CFO +0,2 Гц, фаза и неизвестное
+для поиска начало 4 160 013 отсчётов. Известное начало записано в результат
+после анализа и не передавалось алгоритму поиска.
+
+| Вход модели | Пара | Разница принятой мощности B/A | Разница `|h|²` B/A | Разница энергии согласованной компоненты |
+|---|---:|---:|---:|---:|
+| Одинаковое усиление | 1 | −0,051497 дБ | +0,001786 дБ | −14,019673 дБ |
+| Одинаковое усиление | 2 | −0,041310 дБ | −0,002894 дБ | −14,024352 дБ |
+| B: −6,020600 дБ | 1 | −6,050214 дБ | −6,014144 дБ | −20,035602 дБ |
+| B: −6,020600 дБ | 2 | −6,028048 дБ | −6,022175 дБ | −20,043634 дБ |
+
+Обе проверки PASS: ошибка коэффициента передачи в каждой паре меньше
+заданных 0,3 дБ. Разница принятой мощности включает небольшое различие
+цифровой мощности активных участков. Это результаты модели, не RF Lab056.
+Данные: [равное усиление](../data/processed/lab056/software_equal.json),
+[ослабление B](../data/processed/lab056/software_minus6db.json).
+
+При корректировке те же сохранённые IQ проанализированы без перегенерации.
+Прежние файлы результатов сохранены; новые сводки:
+[равное усиление, OTA summary](../data/processed/lab056/software_equal_ota_summary.json),
+[ослабление B, OTA summary](../data/processed/lab056/software_minus6db_ota_summary.json).
+
+| Искусственная запись | X: мощность B/A | Y: коэффициент передачи B/A | Z: энергия символа B/A | Повтор `|h|²`, A2/A1 | Повтор `|h|²`, B2/B1 |
+|---|---:|---:|---:|---:|---:|
+| Равное усиление | −0,046404 дБ | −0,000553 дБ | −14,025804 дБ | −0,002308 дБ | −0,006988 дБ |
+| B: −6,020600 дБ | −6,039124 дБ | −6,018156 дБ | −20,018524 дБ | −0,002308 дБ | −0,010340 дБ |
+
+Это по-прежнему результаты программной модели. Они не устанавливают
+величину эфирного различия Lab056.
+
+Повторный анализ существующего файла с новым именем результата:
+
+```powershell
+python experiments/lab056_abab_energy.py analyze --rx data/raw/lab056/synthetic_equal.cs8 --output data/processed/lab056/recheck_equal.json
+```
+
+Существующие выходные файлы не перезаписываются. Команды `prepare` и
+`software` создают данные только при отсутствии соответствующих файлов.
+
+## Подготовка однократного аппаратного запуска
+
+`experiments/lab056_capture_runner.py` не имеет аппаратного CLI. Без конкретного
+положительного целого RF_FREQ из задания пользователя аппаратные действия
+не начинаются. Частота одинакова для всех RX-команд и единственной TX-команды;
+цифровая несущая остаётся +50 кГц. Страна/регуляторная полоса не запрашиваются
+программой. Геометрия сохраняется вместе с частотой в отдельном OperatingPoint.
+
+Роли плат сохранены: MASTER/TX `000000000000000097c063dc323b97d3`,
+SLAVE/RX `000000000000000097c063dc2e5327d3`. Планируется прежнее тактирование
+10 МГц TCXO → MASTER → CLKOUT → SLAVE CLKIN. Требуются оба reg29 = 0x26
+и SLAVE CLKIN = DETECTED после короткого RX-start. Сначала логика проверена
+mock-вызовами; теперь эти значения подтверждены аппаратным preflight.
+
+Вызов `preflight_only` после получения RF_FREQ проверит инвентаризацию,
+common clock и сохранит 0,1 с RX без TX на заданной частоте при RX 24/24 дБ.
+Он проверит размер, явный нулевой счётчик потерь, уровень и клиппинг,
+запишет `preflight_result.json`, выключит CLKOUT и завершится с STOP.
+Любая TX-команда внутри этого этапа запрещена обёрткой runner.
+Файл попытки создаётся эксклюзивно; автоматического повтора нет.
+
+После отдельного разрешения `capture_once` потребует PASS preflight той же
+частоты, геометрии и SHA TX. Поскольку после preflight CLKOUT выключены,
+перед фактическим сеансом опора проверяется заново при запуске. Это проверка
+готовности перед единственным TX, а не повтор передачи.
+
+TX VGA 10 дБ, RX LNA/VGA 24/24 дБ, RF amplifier и Bias-Tee OFF,
+Fs 8 Мвыб/с фиксированы на всю ABAB. RX запускается первым; затем допускается
+один TX-процесс с конечным числом отсчётов, без `-R`. Маркер попытки создаётся
+эксклюзивно; ошибка расходует попытку, автоматического повтора нет.
+Требуются процессы CLEAR до/после, правильный размер RX, явные нулевые
+RX overruns/TX underruns и успешное выключение CLKOUT обеих плат.
+После упреждения RX проверяются последние 65 536 записанных отсчётов:
+при rail-кодах −128/127 TX не запускается, RF TX=0 и STOP. Полная запись
+проверяется также после ABAB. Если клиппинг появился только при передаче,
+фиксируется RF TX=1 и невалидное измерение без повтора. Уже выполненная
+передача не переобозначается нулём. В отчёте сохраняются RMS, пики I/Q,
+доли клиппинга; отсутствие rail-кодов само по себе не доказывает отсутствие
+аналоговой компрессии. Gain не меняется автоматически ни в одном сценарии.
+Аппаратные помощники переиспользованы из существующей Lab054; её файлы
+`experiments/lab054_hardware_control.py` и `tools/hackrf_process_check.py`
+включаются в фиксацию Lab056 как необходимые зависимости вместе с их
+двумя тестовыми файлами. Без них runner Lab056 не импортируется в чистой
+копии репозитория, что независимо воспроизведено verifier. Старые отчёты,
+данные и записи журнала Lab054 в эту фиксацию не входят. Реализации
+зависимостей не переписывались; аппаратная логика осталась проверенной.
+
+Verifier независимо подтвердил SHA/размеры TX, нулевые gaps, побайтную
+повторяемость A/B и пересчитал коэффициенты передачи вторым методом.
+Он воспроизвёл ошибку разбора журнала `1 RX overruns\n0 overruns`;
+исправленный разбор отклоняет ненулевые, неизвестные и неразобранные
+счётчики. Повторные mock-вызовы `capture_once` закрыли находку.
+Остаточных воспроизведённых находок нет. Оборудование verifier не использовал.
+
+Исходная подготовка: 34 целевых теста passed; quick_gate: 857 тестов,
+30 функциональных проверок, 13 штатных пропусков, PASS. Полный pytest:
+857 passed, 0 failed, 96,50 с (кеш отключён из-за прежнего отказа доступа).
+`git diff --check`: PASS. Машинная сводка:
+[acceptance.json](../data/processed/lab056/acceptance.json).
+
+Корректировка OTA: 44 целевых теста PASS; quick_gate 867 тестов /
+30 функциональных проверок / 13 штатных пропусков, PASS; pytest
+867 passed, 0 failed, 89,32 с. Verifier исполнил все 44 сценария
+в памяти без файлов и оборудования; остаточных находок нет.
+Новая сводка [ota_correction.json](../data/processed/lab056/ota_correction.json)
+дополняет исходную acceptance, не заменяя исторические 857 passed.
+
+## Как читать будущий эфирный результат
+
+Эфирный ABAB сравнит весь путь: TX, антенны, распространение, RX. Малое
+различие означает, что большой провал не воспроизведён в этом пути и этой
+сессии. Оно не доказывает равенство мощности непосредственно на выходе TX.
+Большое повторяемое различие тоже нельзя автоматически отнести внутрь
+HackRF: частотная избирательность антенн и многолучевого распространения
+остаётся частью измерения. Для отделения аппаратного эффекта пригодится
+отдельно согласованный кабельный или калиброванный измерительный опыт.
+
+Ни необходимость PA, ни изменение результатов Lab047/Lab054 из этой
+подготовки не следуют. Архитектура проекта сохраняется: управление через
+RadioMaster/ExpressLRS/CRSF, SDR — видеотракт с целью минимум 5 свежих кадров/с.
+
+## Состояние перед STOP
+
+```text
+LAB055 COMMIT = 5add95ecb8865f59075bbbced08d97b183fb3b48
+NEW HEAD = 5add95ecb8865f59075bbbced08d97b183fb3b48
+LAB056 RESULT = OTA_ABAB_VALID_LARGE_DROP_NOT_REPRODUCED_STOP
+PHYSICAL CONNECTION = OTA, LOS, fixed antennas, same polarization/orientation, approximately 3-5 m per user
+RF FREQUENCY = 1400000000 Hz (Lab056 test only)
+A SYMBOL RATE = 20 ksymbol/s
+B SYMBOL RATE = 500 ksymbol/s
+TX RMS A = 44.004413 code
+TX RMS B = 44.001925 code
+TX POWER DIFFERENCE B/A = -0.000491 dB (whole segment)
+ABAB TX DURATION = 1.323568 s
+RX PLANNED DURATION = 3 s, lead 0.5 s
+COMMON CLOCK PREFLIGHT = HARDWARE PASS, both reg29=0x26, SLAVE CLKIN=DETECTED
+RX PREFLIGHT = PASS, 800000 complex samples, 0.1 s, overruns=0
+CLIPPING = 0
+READY FOR ANOTHER TX = NO (authorized single attempt consumed)
+COMPLETED TX SESSIONS = 1
+AUTOMATIC TX REPEATS = 0
+RX ABAB RECORD = 24000000 complex samples, 3 s, clipping=0, overruns=0
+TX UNDERRUNS = 0
+RECEIVED POWER DIFFERENCE B/A = +0.108895 dB
+TX-MATCHED CHANNEL GAIN DIFFERENCE B/A = -0.163042 dB
+ENERGY PER SYMBOL DIFFERENCE = -13.870505 dB
+BASELINE pytest = 857 passed (сохранённый результат подготовки)
+quick_gate = PASS, 867 tests / 30 functional / 13 skipped
+pytest = PASS, 867 passed / 0 failed (после корректировки)
+git diff --check = PASS
+RF TX = 0
+LAB056 COMMIT = NOT_PERFORMED
+PUSH = NOT_PERFORMED
+CURRENT SINGLE-TX AUTHORIZATION = CONSUMED
+STOP
+```