SDR-Rover/docs/lab043_pluto_to_rtlsdr_spec.md

# Lab043. Передача JPEG с Pluto+ на независимый RTL-SDR

## 1. Цель лабораторной

Передать тот же подготовленный JPEG, который использован в Lab042, с
Pluto+ на отдельный RTL-SDR и восстановить его побайтово.

В Lab042 передатчик и приёмник находились в одном Pluto+ и использовали
общий опорный генератор. Lab043 должна убрать это упрощение и раздельно
измерить три эффекта:

1. рассогласование несущих частот передатчика и приёмника;
2. относительное рассогласование частот дискретизации двух устройств;
3. начальную фазу выбора отсчёта символа внутри символьного интервала.

Лабораторная считается успешной только при выполнении радиокритериев,
прикладных критериев и программных проверок, определённых в разделе 11.
Запуск программы сам по себе успехом не считается.

## 2. Границы работы

Lab043 остаётся кабельной. Эфир добавил бы многолучёвость, внешние сигналы
и неконтролируемые потери, хотя предмет этой работы состоит в
синхронизации независимых устройств.

В Lab043 не входят:

- передача через антенны;
- выбор рабочего диапазона 200-250 МГц;
- ARQ и повторная передача;
- исправление стираний и новая FEC;
- потоковое видео;
- скачки по частоте;
- изменение логики управления и безопасности ровера.

Эфирный тракт остаётся предметом следующей лабораторной.

## 3. Подтверждённое оборудование и окружение

Состояние оборудования проверено непосредственным опросом. Перед
реализацией и перед каждым аппаратным прогоном его необходимо проверить
повторно.

### 3.1. Передатчик

- Pluto+;
- устройство должно открываться успешным `iio.Context`, а не проверяться
  только командой `ping`;
- чип AD9361;
- используется первый передающий канал.

Конкретный рабочий URI IIO определяется повторным опросом перед опытом и
сохраняется в метаданных запуска. Исторически работали сетевой URI
`ip:192.168.2.1` и прямой USB IIO, но ни один из них нельзя считать
доступным без текущей проверки.

### 3.2. Приёмник

- USB ID `VID_0BDA&PID_2838`;
- имя библиотеки: `Generic RTL2832U OEM`;
- тюнер, сообщённый библиотекой: Fitipower FC0013;
- основной интерфейс `MI_00` использует WinUSB от libwdi;
- устройство открыто из Python через `pyrtlsdr` и `librtlsdr`;
- установка 435 МГц подтверждена чтением значения обратно;
- частота дискретизации 2 400 000 отсчётов/с работает;
- получены комплексные отсчёты;
- доступные аппаратные усиления находятся в диапазоне от -9,9 до
  19,7 дБ и задаются дискретными ступенями устройства.

Ошибка второго USB-интерфейса не считается отказом SDR. Основной
интерфейс `MI_00`, через который работает `librtlsdr`, исправен.

### 3.3. Зафиксированное программное окружение

- Python 3.13.1 x64;
- `pyrtlsdr` 0.5.0;
- `pyrtlsdrlib` 0.0.5;
- поставляемая пакетом нативная `librtlsdr` v0.9.0;
- `pyadi-iio` и `pylibiio` для Pluto+.

Принятый способ доступа к RTL-SDR: API `pyrtlsdr` с поставляемой
`pyrtlsdrlib` нативной библиотекой. Малый собственный DLL-адаптер не
нужен. Реализация должна проверять версии и выдавать понятную ошибку, если
библиотека или устройство недоступны. Пользовательский путь к DLL
зашивать в код запрещено.

## 4. Физическая схема и безопасность

Схема:

`Pluto+ TX -> SMA-кабель -> AT30S 30 дБ -> переходник/кабель -> RTL-SDR RX`

Обязательные условия перед каждым включением TX:

1. Антенны Pluto+ и RTL-SDR сняты.
2. AT30S включён последовательно в тракт, а не подключён к свободному
   порту.
3. Все разъёмы затянуты, кабель не отсоединяется при включённом TX.
4. Пользователь отдельно подтверждает эту физическую схему.
5. Первый заранее определённый рабочий режим: TX -30 дБ, RTL-SDR
   19,7 дБ, несущая 435 МГц, номинально 2,4 Мвыб/с на обоих устройствах.
6. Автоматический перебор усилений, частот, порогов и способов
   синхронизации запрещён.
7. Если первый режим не проходит, программа сохраняет исходные данные и
   диагностику и останавливается. Следующий прогон разрешён только после
   разбора причины и с изменением ровно одного заранее названного
   параметра.

При TX -30 дБ расчётный уровень после AT30S составляет около -53 дБм.
Это значение следует из бюджета Lab042: около +7 дБм при TX 0 дБ,
минус 30 дБ настройки TX и минус 30 дБ аттенюатора. Расчёт не заменяет
проверку наличия аттенюатора и правильности схемы.

## 5. Номинальные параметры сигнала и обязательное чтение обратно

| Параметр | Запрошенное значение | Происхождение |
|---|---:|---|
| Несущая TX и RX | 435 МГц | Кабельная рабочая точка Lab042 |
| Символьная скорость | 20 000 симв/с | Lab018-Lab023 и Lab042 |
| Частота дискретизации TX | 2 400 000 отсчётов/с | Поддерживается Pluto+ и проверена на RTL-SDR |
| Частота дискретизации RX | 2 400 000 отсчётов/с | Проверена непосредственным опросом RTL-SDR |
| Номинальное число отсчётов на символ | 120 | 2 400 000 / 20 000 |
| Полоса TX | 200 кГц | Минимальная полоса AD9361, использованная в Lab042 |
| Размер данных фрагмента | 512 байт | Lab042 |
| Модуляция | BPSK | Lab018-Lab023 и Lab042 |

Одинаковое номинальное значение 2,4 Мвыб/с выбрано специально. Lab043
измеряет физическую ошибку генераторов, а не искусственно созданную
разницу номинальных частот дискретизации.

Перед аппаратным опытом программа обязана установить и прочитать обратно:

- частоту дискретизации TX Pluto+;
- частоту дискретизации RX RTL-SDR;
- центральную частоту TX Pluto+;
- центральную частоту RX RTL-SDR;
- усиление TX Pluto+;
- фактически выбранную ступень усиления RTL-SDR.

Для каждого параметра в отчёте и метаданных хранятся отдельные поля
`requested` и `actual`. Если API не предоставляет независимого чтения
обратно, поле `actual` имеет значение `N/A`, а не копию запрошенного
значения. Передача не начинается, если частота дискретизации или несущая
не прочитаны обратно либо отличаются от запрошенных больше, чем допускает
API устройства и заранее установленная проверка.

## 6. Двухтоновая калибровка

Перед BPSK Pluto+ передаёт два комплексных тона, симметричных относительно
несущей:

`-Fcal` и `+Fcal`, где `Fcal = 50 кГц`.

50 кГц выбраны до измерения: оба тона находятся внутри полосы 200 кГц,
не сливаются около нуля и дают разнос 100 кГц для оценки масштаба частот.
RTL-SDR измеряет положения двух пиков относительно своей настроенной
несущей: `f_low` и `f_high`.

### 6.1. Рассогласование несущей

`carrier_offset_hz = (f_low + f_high) / 2`

`carrier_offset_ppm = carrier_offset_hz / 435000000 * 1e6`

Положительный результат означает, что принятый спектр сдвинут вверх по
частоте. Для компенсации сырые комплексные отсчёты умножаются на:

`exp(-j * 2*pi*carrier_offset_hz*n/Fs_rx_actual)`

Знак поправки проверяется независимо: после компенсации среднее положение
двух тонов должно стать ближе к нулю. Рассогласование несущей не должно
подменяться оценкой ошибки частоты дискретизации.

### 6.2. Относительная ошибка частот дискретизации

`clock_scale = (f_high - f_low) / (2*Fcal)`

`sample_clock_error_ppm = (clock_scale - 1) * 1e6`

Здесь положительная ошибка означает, что масштаб передающего такта больше
масштаба приёмного. Для перехода принятых отсчётов на временную сетку
передатчика ожидаемая длина после передискретизации равна:

`len_corrected = round(len_received * clock_scale)`

Направление этой операции не принимается на веру. Оно подтверждается
машинными тестами из раздела 8. После передискретизации накопленная ошибка
символьного времени должна уменьшаться.

### 6.3. Начальная фаза выбора отсчёта символа

После грубой CFO-коррекции и передискретизации приёмник отдельно ищет
начальную фазу выбора отсчёта в диапазоне от 0 до 119 номинальных
отсчётов на символ. Это не CFO и не ошибка такта. В результатах отдельно
хранятся:

- `carrier_offset_hz` и `carrier_offset_ppm`;
- `clock_scale` и `sample_clock_error_ppm`;
- `symbol_sample_phase` и остаточная ошибка символьного времени.

### 6.4. Формальное определение шумового фона

Шумовой фон и превышение пиков вычисляются одинаковым детерминированным
алгоритмом:

1. Из комплексных отсчётов вычитается среднее.
2. Оценивается спектральная плотность мощности методом Welch с окном Hann,
   `nfft = nperseg = 65536` и перекрытием 50 процентов.
3. Разрешение одного БПФ вычисляется по прочитанной обратно частоте как
   `delta_f = Fs_rx_actual / 65536`. При 2,4 Мвыб/с оно равно
   `36,62109375 Гц`.
4. Анализируется полоса от -100 до +100 кГц относительно настроенной
   несущей.
5. Нижний пик ищется в диапазоне от -80 до -20 кГц, верхний от +20 до
   +80 кГц. Эти непересекающиеся окна заданы до измерения.
6. После нахождения кандидатов ожидаемых тонов из оценки шума исключаются
   защитные зоны шириной +/-2 кГц вокруг измеренного положения каждого
   кандидата. Каждая полузона занимает около 55 разрешающих элементов БПФ
   при 2,4 Мвыб/с, поэтому утечка основного лепестка и ближайших боковых
   лепестков тона не попадает в медиану шума.
7. Шумовая мощность `P_noise` равна медиане линейных значений мощности
   всех оставшихся спектральных элементов анализируемой полосы.
8. Для каждого тона вычисляется
   `peak_excess_db = 10*log10(P_peak/P_noise)`.

Оба пика должны превышать шумовой фон не менее чем на 10 дБ. Порог 10 дБ,
полоса анализа, окна поиска и защитные зоны зафиксированы до аппаратного
измерения. Если нет двух конечных пиков, недостаточно элементов шума или
хотя бы один пик не проходит порог, оценка этого захвата недействительна.

### 6.5. Повторы и представление недействительных оценок

Без изменения схемы выполняются три отдельных калибровочных захвата. Для
каждого захвата отдельно сохраняются:

- `f_low_hz` и `f_high_hz`;
- `low_peak_excess_db` и `high_peak_excess_db`;
- `carrier_offset_hz` и `carrier_offset_ppm`;
- `clock_scale` и `sample_clock_error_ppm`;
- остаточная CFO после коррекции;
- остаточная ошибка разноса тонов в герцах и ppm;
- признак достоверности и причина отказа.

По трём захватам вычисляются среднее, минимум, максимум и стандартное
отклонение каждой конечной оценки, а также число недействительных
захватов. Стандартное отклонение считается по совокупности всех конечных
оценок с `ddof=0`. Недействительное значение записывается как `NaN` в CSV
и как `N/A` в текстовом отчёте. Оно никогда не заменяется нулём. Если
конечных значений нет, все агрегаты этой величины равны `N/A`.

## 7. Диагностическая последовательность передачи

Аппаратная часть выполняется по ступеням. Переход к следующей ступени
разрешён только после сохранения результатов предыдущей:

1. двухтоновые калибровочные захваты;
2. известная короткая BPSK-последовательность;
3. символьная синхронизация и измерение BER известной последовательности;
4. один пакет с CRC;
5. десять пакетированных фрагментов JPEG;
6. сборка JPEG;
7. проверка размера и SHA-256.

Известная последовательность задаётся до измерения как PRBS11 длиной
2047 бит с полиномом `x^11 + x^9 + 1` и фиксированным ненулевым начальным
состоянием, записанным в метаданные. BER вычисляется прямым сравнением
каждого принятого бита с ожидаемым до упаковки в пакет и до проверки CRC.
CRC не может использоваться вместо измерения BER.

### 7.1. Контрольный опыт PRBS11 после проверки непрерывного async-приёма

Короткая запись S и длинная запись L являются двумя отдельными аппаратными
захватами. Каждый захват выполняется одним непрерывным
`rtlsdr_read_async()` и содержит в этой последовательности: входной запас,
двухтоновую калибровку, фиксированный защитный участок 0,10 с, один
начальный маркер, непрерывную PRBS11 и выходной запас. Полезная PRBS11
длится 0,25 с в S и не менее 2,0 с в L. Внутри полезной PRBS11 нет
периодической повторной синхронизации.

Оценки CFO и масштаба частоты дискретизации для обработки PRBS11 берутся
только из двух тонов в той же самой IQ-записи. Оценку из предыдущего
двухтонового опыта или из другой записи применять запрещено. Если тоны в
текущем захвате недостоверны, PRBS11 этой записи не интерпретируется.

Для обоих захватов заранее фиксируются 435 МГц, номинальные 2 400 000
отсчётов/с TX и RX, 20 000 символов/с, TX -30 дБ, запрос усиления RTL-SDR
19,7 дБ и `Fcal = 50 кГц`. Асинхронный приём использует callback 262144
байта, 15 буферов и отбрасывает первый callback как разогревочный без
перезапуска сеанса. Автоматический подбор параметров запрещён.

Одна и та же IQ-запись обрабатывается режимами A, B и C. В B и C грубая
CFO берётся из тонов этой записи; в C дополнительно применяется
`clock_scale` этих же тонов. Разрешённая защищённая тонкая CFO-коррекция не
заменяет двухтоновое измерение. Для длинной записи SRO дополнительно
оценивается независимо по накопленному дрейфу символьной фазы.

## 8. Обязательные программные проверки до аппаратного опыта

На синтетических комплексных данных проверяются четыре ошибки частоты
дискретизации: +20, -20, +100 и -100 ppm. Для каждого случая тест обязан
проверить:

- знак оценки `sample_clock_error_ppm`;
- величину оценки в заранее заданном допуске;
- направление изменения длины при передискретизации;
- уменьшение остаточной накопленной ошибки символьного времени после
  поправки.

Для положительной ошибки длина должна изменяться в направлении,
предписанном формулой `round(N * clock_scale)`, для отрицательной в
противоположном. Тест должен упасть, если вместо `clock_scale` применена
обратная величина. Допуск оценки и критерий уменьшения остаточной ошибки
задаются в тесте до аппаратного измерения и печатаются в его результате.

Дополнительно синтетические тесты проверяют:

- знак грубой CFO-коррекции для положительной и отрицательной CFO;
- уменьшение остаточной CFO после поправки;
- отдельное восстановление начальной фазы выбора отсчёта символа;
- явный `N/A`, если два тона не найдены достоверно;
- формулу шумового фона и порог 10 дБ;
- BER известной последовательности до CRC;
- отсутствие ложного успеха при неполном пакете или изображении;
- формирование кода возврата только по полному набору критериев.

До прохождения этих проверок передатчик включать нельзя.

## 9. Порядок аппаратного эксперимента

1. Открыть Pluto+ успешным `iio.Context` и записать URI и идентификаторы.
2. Открыть RTL-SDR через `pyrtlsdr` и записать имя устройства и тюнера.
3. Установить и прочитать обратно параметры из раздела 5.
4. Получить отдельное подтверждение пользователя, что кабельная схема из
   раздела 4 собрана и AT30S находится в разрыве.
5. Запустить один непрерывный приём RTL-SDR за 0,5 с до передачи Pluto+.
6. Выполнить три отдельных двухтоновых калибровочных захвата.
7. Сохранить оценки каждого захвата, агрегаты и не менее одного
   эталонного сырого IQ-захвата.
8. Передать известную BPSK-последовательность и измерить BER.
9. Принять один пакет и проверить CRC.
10. Передать десять фрагментов JPEG и проверить критерии раздела 11.

Если любая ступень не проходит, переход к следующей запрещён. Исходные
данные и отрицательный результат сохраняются без подгонки. Изменение
одного параметра для следующего запуска оформляется как отдельное заранее
объяснённое действие.

Весь опыт принимается RTL-SDR как одна непрерывная временная
последовательность. Продолжительность приёма вычисляется из фактически
сформированной передаваемой последовательности:

`T_rx = 0,5 с + N_tx / Fs_tx_actual + 0,5 с`.

Здесь `N_tx` является фактическим числом комплексных отсчётов всей
сформированной TX-последовательности. Общая длительность опыта не задаётся
произвольной константой. Поток разрешено читать блоками, например около
262144 отсчётов, но блоки объединяются без пропусков и перестановок в одну
последовательность. Размер блока чтения является параметром реализации, а
не физическим защитным интервалом. Десять отдельных запусков приёмника для
десяти кадров запрещены, потому что они уничтожили бы наблюдаемое
накопление ошибки тактов.

Между BPSK-кадрами не добавляются новые интервалы. Используется структура
Lab042: `GUARD_SYMBOL_COUNT` импортируется из её текущей конфигурации без
копии числовой константы в Lab043, а формирование кадра повторяет ту же
последовательность переднего интервала, символов, заднего интервала и RRC.
Готовая функция Lab042 жёстко связана с 128 отсчётами на символ, поэтому
при 120 отсчётах Lab043 переиспользуются её параметры, а не скрытая копия
её глобальной частоты дискретизации. Если в дальнейшем отдельный интервал
исчезнет из Lab042, Lab043 не создаёт новый без отдельного диагностического
решения.

## 10. Три режима обработки одной записи

Одна и та же сохранённая BPSK/IQ-запись обрабатывается тремя режимами:

- режим A: без грубой CFO-коррекции и без коррекции частоты
  дискретизации;
- режим B: только грубая CFO-коррекция из двухтоновой калибровки;
- режим C: грубая CFO-коррекция, коррекция частоты дискретизации и
  защищённая тонкая CFO-коррекция.

Во всех режимах начальная фаза выбора отсчёта символа оценивается и
записывается отдельно. Для каждого режима сохраняются BER известной
последовательности, остаточная CFO, остаточная временная ошибка,
корреляция маркера, число найденных кадров, число разобранных заголовков и
CRC пакетов.

В режиме C защищённая функция `should_apply_cfo_correction` из
`protocol/bpsk_radio.py` остаётся тонкой коррекцией после грубого
измерения. Она не используется как единственный способ поиска сдвига в
десятки килогерц, поскольку символьная оценка неоднозначна за пределами
половины символьной скорости.

Провал режимов A или B не считается провалом лабораторной. Они являются
контрольными измерениями. Критерии передачи применяются к режиму C.

## 11. Критерии приёмки

### 11.1. Радиокритерии режима C

- найдены все 10 кадров;
- разобраны все 10 пакетов;
- CRC32 сошлась у всех 10 пакетов.

### 11.2. Прикладные критерии режима C

- восстановлены все 10 уникальных фрагментов;
- JPEG собран без заполнения отсутствующих данных;
- размер принятого JPEG совпадает с размером переданного;
- SHA-256 принятого JPEG совпадает с SHA-256 переданного.

### 11.3. Общий результат

Код возврата 0 разрешён только при одновременном выполнении:

- всех радиокритериев;
- всех прикладных критериев;
- всех обязательных программных проверок раздела 8.

Для подтверждения воспроизводимости заранее выбранная рабочая точка
запускается три раза подряд без изменения схемы и параметров. Каждый
повтор сохраняется отдельно. Три повтора являются проверкой
воспроизводимости, а не статистической оценкой вероятности отказа.

Отрицательный результат допустим и сохраняется полностью. Запрещено
автоматически поднимать усиление, менять частоту, пороги или алгоритм
синхронизации после неудачного прогона.

## 12. Измерения и артефакты

### 12.1. Измерения передачи

Для каждого запуска и каждого режима обработки сохраняются:

- запрошенные и фактические усиления, несущие и частоты дискретизации;
- число принятых отсчётов;
- отдельные оценки CFO, ошибки частоты дискретизации и начальной
  символьной фазы;
- BER известной последовательности до CRC;
- число найденных кадров и разобранных заголовков;
- CRC каждого пакета;
- решение защищённой тонкой CFO-коррекции и его диагностические величины;
- корреляция маркера и корректно определённая EVM;
- число и номера восстановленных фрагментов;
- размер и SHA-256 переданного и принятого JPEG;
- длительность сигнала и полезная скорость.

Каждое число вычисляется из текущего запуска. Перенесённые константы
снабжаются ссылкой на лабораторную-источник. Невычислимая величина
записывается как `NaN` или `N/A`, но не как правдоподобный ноль.

### 12.2. План программных артефактов

Предполагаемые файлы после отдельного согласования реализации:

- `experiments/lab043_pluto_to_rtlsdr.py`;
- `tests/test_lab043_calibration.py`;
- `data/processed/lab043/lab043_calibration.csv`;
- `data/processed/lab043/lab043_frames.csv`;
- `data/processed/lab043/lab043_summary.csv`;
- `data/processed/lab043/lab043_report.txt`;
- графики калибровочного спектра, остаточной ошибки и доставки
  фрагментов.

### 12.3. Эталонный сырой IQ-захват

Не менее одного полного эталонного захвата до CFO- и SRO-коррекций
сохраняется в `data/raw/lab043/` и не добавляется в Git.

Формат отсчётов: NumPy `.npy`, одномерный массив `complex64` в порядке
приёма. Нормирование исходных 8-битных I/Q отсчётов и порядок I/Q должны
быть однозначно описаны в метаданных. Рядом сохраняется UTF-8 JSON с тем
же базовым именем и полями:

- локальная метка времени и UTC;
- идентификаторы устройств и модель тюнера;
- версии Python, `pyrtlsdr`, `pyrtlsdrlib`, `librtlsdr`, `pyadi-iio` и
  `pylibiio`;
- запрошенные и фактические частоты дискретизации, несущие и усиления;
- число отсчётов, длительность, dtype и порядок байтов;
- идентификатор и SHA-256 переданной формы сигнала;
- результаты калибровки, применённые к этой записи;
- SHA-256 файла `.npy`.

IQ-файл содержит всю единую последовательность приёма. Ожидаемое число
отсчётов вычисляется как `ceil(T_rx * Fs_rx_actual)`. Чтение выполняется
последовательными блоками до достижения этого числа, последний блок
обрезается только после получения требуемого количества отсчётов.

### 12.4. Разделение общего и лабораторного кода

Общие математические примитивы обнаружения двух известных тонов, оценки
грубой CFO и относительной ошибки частот дискретизации, грубой частотной
коррекции и передискретизации размещаются в `protocol/bpsk_radio.py` либо
в другом подходящем существующем модуле `protocol/`. Каждый такой перенос
сопровождается быстрым синтетическим тестом.

В `experiments/lab043_pluto_to_rtlsdr.py` остаются сценарий лабораторной,
конкретное `Fcal`, три калибровочных захвата, методика оценки шума Lab043,
режимы A/B/C, PRBS11, контрольный пакет, JPEG, отчётные артефакты,
критерии приёмки и аппаратная последовательность. Общий код не зависит от
конкретного JPEG и номера лабораторной.

## 13. Точка остановки перед аппаратным опытом

Программная реализация и синтетические проверки разрешены. Перед
аппаратным опытом необходимо отдельно:

1. пройти все обязательные программные проверки раздела 8;
2. повторно проверить доступность устройств и чтение параметров обратно;
3. получить подтверждение пользователя о схеме и отдельное разрешение на
   включение TX.

Способ Python-доступа к RTL-SDR уже выбран и не является вопросом точки
остановки.

До отдельного разрешения передатчик не включается, усиление Pluto+ не
изменяется, аппаратная калибровка и передача тонов, BPSK или JPEG не
выполняются. Операции `git add`, `commit`, `push`, `pull` и `fetch` также
не выполняются.