# 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` прошёл.