Lab064: measure OTA level linearity at TX VGA 10 dB

docs/lab064_current_state.md

@@ -0,0 +1,141 @@
+# Lab064: измерение уровня и линейности RF-тракта
+
+Lab064 проверяет, следует ли мощность согласованной принятой составляющей
+заранее заданной цифровой лестнице TX. Это измерительный опыт с известным
+PRBS7/BPSK-сигналом, а не пакетный тест. FEC, CRC, T2, JPEG и packet output в
+нём не используются.
+
+На текущем этапе сформирован сигнал, подготовлены RX-first runner, офлайн-
+анализатор и полный учёт сообщений overruns/underruns. Перед аппаратным
+preflight и будущим RF-сеансом исходные параметры не меняются.
+
+## Физические условия
+
+| Условие | Значение |
+|---|---|
+| Центральная частота | 1400000000 Гц |
+| Расстояние TX–RX | примерно 1,2 м |
+| Геометрия | прямая видимость, помещение |
+| TX | плата и антенна возле окна |
+| RX | плата и антенна на столе пользователя |
+| Антенны | имеющиеся антенны на 1400 МГц |
+| Поляризация | одинаковая |
+| Тактирование | 10 МГц TCXO → MASTER → MASTER CLKOUT → SLAVE CLKIN |
+
+Антенны, платы, длинный кабель общей опоры, USB-подключение и остальные
+кабели не перемещаются. Во время опыта не меняются частота, усиления,
+ориентация и форма сигнала.
+
+## Подготовленный измерительный сигнал
+
+Параметры сигнала: BPSK/PRBS7, 20000 символов/с, Fs 8000000 комплексных
+отсчётов/с, 400 отсчётов/символ, цифровая несущая +50000 Гц и существующий RRC
+с roll-off 0,35 и span 10 символов. TX VGA равен 10 дБ. RX LNA/VGA равны
+24/24 дБ. RF amplifier и Bias-Tee выключены.
+
+Один файл содержит 100 мс нулей, четыре одинаковых по содержанию участка по
+100 мс, три нулевых промежутка по 50 мс и 100 мс нулей в конце. Общая длина:
+6000000 комплексных отсчётов, 12000000 байт, 0,75 с. Нулевые участки являются
+цифровыми нулями IQ; они не означают аппаратного выключения TX посреди файла.
+
+SHA-256 подготовленного CS8:
+`fa260719659b2984fe29588238415622cd75c6daefec6cc9130ba1bf851bd3f9`.
+
+| Уровень | Задано, дБ | Фактически, дБ | TX RMS, код | max \|I\| / \|Q\|, код | Шаг мощности, дБ | Clipping |
+|---|---:|---:|---:|---:|---:|---|
+| L0 | −18 | −17,973685 | 5,556137 | 9 / 9 | — | нет |
+| L1 | −12 | −11,996415 | 11,056978 | 17 / 17 | +5,977270 | нет |
+| L2 | −6 | −5,998257 | 22,056892 | 34 / 35 | +5,998157 | нет |
+| L3 | 0 | 0 | 44,000457 | 69 / 69 | +5,998257 | нет |
+
+Небольшое отклонение L0 от −18 дБ вызвано квантованием CS8. Каждый шаг
+укладывается в заранее установленный допуск ±0,1 дБ.
+
+## Анализ будущей записи
+
+Для каждого L0…L3 анализатор отдельно выдаёт полный и AC RMS, средние I/Q,
+max |I|, max |Q| и максимальную комплексную амплитуду. По соседнему нулевому
+окну оценивается фон. По известному TX оцениваются комплексный коэффициент
+передачи `h`, `|h|²`, мощность согласованной составляющей, мощность остатка и
+их отношение.
+
+Для каждой соседней пары вычисляются:
+
+```text
+TX INPUT DIFFERENCE
+RX MATCHED POWER DIFFERENCE
+LINEARITY ERROR = RX difference − TX difference
+```
+
+Критерии зафиксированы до RF:
+
+- линейный участок: максимальная абсолютная ошибка шага не более 1,0 дБ;
+- признак компрессии: ошибка верхнего шага не более −1,5 дБ;
+- `LINEAR_BUT_WEAK`: шаги линейны, фон стабилен, а L3 ниже 3 дБ над остатком;
+- `HEALTHY_LINEAR_RANGE`: шаги линейны, фон стабилен, а L3 не менее 6 дБ над
+  остатком;
+- неоднозначный результат получает статус `NOT_LOCALIZED`.
+
+Эти границы являются правилами данного опыта, а не абсолютной калибровкой
+RF-мощности. Абсолютную выходную и принятую мощность без измерительного прибора
+установить нельзя.
+
+Синтетическая проверка известного линейного комплексного канала с DC и шумом
+восстановила три цифровых шага с максимальной ошибкой меньше 0,0001 дБ. Это
+проверяет вычисления анализатора, но не подтверждает аппаратные свойства
+HackRF или эфирного канала.
+
+## Управление аппаратным сеансом
+
+Preflight допускает только RX-команды. Он проверяет MASTER/SLAVE reg29=0x26,
+SLAVE CLKIN=DETECTED, процессы, инвентаризацию, 0,1 с фона, rail-коды,
+overruns, AC RMS и максимумы |I|/|Q|. Усиления автоматически не меняются.
+
+Будущий runner запускает RX раньше TX. Передача требует отдельного явного
+флага, создаёт одноразовый маркер до обращения к SDR и допускает ровно один
+TX-вызов. Полные stdout и stderr сохраняются раздельно. В итог попадают все
+промежуточные и финальные счётчики потерь, их максимум и последнее значение.
+Любой underrun, overrun, clipping или аппаратная ошибка завершает опыт без
+повтора. Анализатор при этом может сохранить диагностические метрики, но
+выдаёт только `INVALID_CAPTURE`: варианты A/B/C запрещены. Проверка использует
+все строки счётчиков и их максимум, поэтому последний ноль не может скрыть
+предыдущее ненулевое значение.
+
+После исправления строгой проверки счётчиков quick gate прошёл: 984 теста
+ядра, 37 функциональных проверок выполнены, 13 пропущены. Полный pytest:
+984 passed, 0 failed. Независимая read-only проверка подтвердила подготовленный
+CS8, программные метрики и запрет классификации невалидной записи.
+
+## Аппаратный preflight
+
+14 сентября 2026 года выполнена одна разрешённая аппаратная проверка при
+выключенном передатчике. MASTER/SLAVE reg29 равны `0x26`, SLAVE CLKIN имеет
+состояние `DETECTED` при первом опросе через 66,793 мс. RX-only запись длиной
+800000 отсчётов дала AC RMS 0,832038 кода, max |I|/|Q| 4/5 кодов, clipping 0 и
+overruns 0. Неожиданно сильного сигнала нет. После отключения CLKOUT процессы
+имеют состояние `CLEAR`, ошибок очистки нет. Подробности приведены в
+[отчёте preflight](lab064_rx_preflight.md).
+
+`RF TX = 0`. На этом этапе Lab064 не коммитируется. Push не выполняется.
+Lab065 автоматически не начинается.
+
+## Фактический RF-результат
+
+14 сентября 2026 года выполнен один разрешённый RF-сеанс без повторов. TX
+underruns 0, RX overruns 0, clipping 0; RX содержит 16000000 комплексных
+отсчётов за 2,0 с. Согласованная мощность выросла на 17,809077 дБ при цифровом
+росте 17,973685 дБ. Общая ошибка линейности равна −0,164609 дБ. Верхняя ступень
+дала +6,020420 дБ при ожидаемых +5,998257 дБ, признака компрессии нет.
+
+Фон стабилен: AC RMS 0,718264…0,728217 кода, разброс мощности 0,119530 дБ.
+Даже L3 остаётся на −12,133336 дБ относительно остатка. Итог по заранее
+заданным критериям: `LINEAR_BUT_WEAK`. Подробные значения приведены в
+[RF-отчёте](lab064_rf_result.md).
+
+После сеанса `RF TX = 0`, процессы `CLEAR`. Усиления не менялись, второй TX не
+выполнялся. Lab064 не коммитировалась, push не выполнялся, Lab065 не создана.
+
+Независимый пересчёт непосредственно по TX/RX CS8 подтвердил SHA, аппаратные
+счётчики, все четыре matched/residual/`h`, пять окон фона, три ступени и общий
+результат L3/L0. Расхождений нет, вердикт проверки: `чисто`. После сеанса quick
+gate и полный pytest дали 986 passed, 0 failed; `git diff --check` прошёл.