CLOCK-001: validate independent-clock QPSK receiver

This commit is contained in:
LittleSam129
2026-09-17 15:05:44 +03:00
parent 6df5f8aa39
commit 3c31bac0da
12 changed files with 4458 additions and 1 deletions

166
docs/rf/CLOCK_001.md Normal file
View File

@@ -0,0 +1,166 @@
# CLOCK-001: независимые такты перед RF-001
17 сентября 2026 года. Статус **PARTIAL**: программный приёмник прошёл основную
сетку до ±50 ppm, но потерял длинные пакеты при ±100 ppm. Последняя точка
служит только стресс-тестом. Частоты реальных генераторов Auron HackRF Plus
не измерялись. SDR не открывался, `RF TX = 0`. Данные каждого запуска
сохранены в `data/processed/clock001/results.json`.
## Модель и вход приёмника
TX строит QPSK/FEC 2/3/RRC при номинальных 8 Мвыб/с и 500 ксимв/с. Для
приёмника с независимой частотой `Fs_RX = Fs_TX · (1 + ε)`, где
`ε = ppm · 10⁻⁶`, программа берёт комплексную TX-волну в моменты
`n / (1 + ε)` по её исходной сетке. Дробные отсчёты получаются линейной
интерполяцией. Поэтому ошибка момента **накапливается по времени**, а не
подменяется одним постоянным сдвигом. Интерполяция не описывает аналоговый
тракт АЦП, шум генераторов или аппаратное квантование.
CFO добавляется отдельно как поворот с частотой в герцах физического времени
RX; начальная фаза и AWGN задаются отдельными параметрами. Даже при нулевом
внешнем CFO цифровая несущая 125 кГц из-за изменения частоты выборки даёт
остаток `(125000 + CFO) / (1 + ε) − 125000` Гц относительно номинального
цифрового смесителя. Отчёт хранит и заданный CFO, и этот ожидаемый остаток;
один не выдаётся за другой. Частотный тест проверяет оба эффекта раздельно.
Программа `tools/clock001.py` строит по три пакета каждого размера с паузой
5 мс и seed `20260917`. Нагрузка 256 байт совпадает с RF-001; для 512 и
1012 байт та же SHA-последовательность продлена. **1012 байт** заполняют
допустимый PHY-пакет 1024 байта с 12 байтами заголовка и CRC. Во всех
39 точках ppm-сетки приёмник получает только полученный IQ и номинальный
радиорежим. TX-границы, исходные пакеты, заданный ppm/CFO и число пакетов
используются только после декодирования для оценки.
```powershell
python -B -X utf8 tools/clock001.py `
--numba-packages C:\Users\user\Desktop\projects\SDR_Rover\.lab053_cpu_runtime\packages
```
Параметр с локальным путём к Numba нужен на этом ПК; в обычном окружении с
зависимостями проекта он не требуется. Команда отказывается перезаписывать
готовый отчёт.
## Строгие результаты
В таблице каждая ячейка означает число **точных пакетов из трёх** после
PHY/FEC/CRC. CFO, фаза и AWGN в этой сетке равны нулю/отсутствуют.
| Payload | 0 | ±1 ppm | ±5 ppm | ±10 ppm | ±20 ppm | ±50 ppm | ±100 ppm, стресс |
|---|---:|---:|---:|---:|---:|---:|---:|
| 256 байт | 3/3 | 3/3 в обе стороны | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 |
| 512 байт | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 |
| 1012 байт | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | 3/3 | **0/3** |
Основная сетка 0, ±1, ±5, ±10, ±20 и ±50 ppm: **99/99**. Наибольшая
симметричная проверенная точка со 100% точных пакетов для всех размеров:
**±50 ppm**. Для 256 и 512 байт стресс ±100 ppm тоже дал 3/3 в обе стороны.
Одиночный пакет 1012 байт при −100 и +100 ppm дал 0/1; в обоих случаях
найден один корреляционный кандидат, но CRC-пакета нет. Значит, новый поиск
преамбулы перед следующим пакетом не устраняет эту потерю внутри текущего
длинного пакета. При ±100 ppm модель накапливает по нему ±0,7572 символа.
Контроль с отдельной кубической интерполяцией повторил для одиночного
1012-байтного пакета 1/1 при ±50 и 0/1 при ±100 ppm. Вывод не зависит
только от выбора линейного интерполятора в основном опыте.
Текущий приёмник оценивает начало **каждого** пакета заново, затем выбирает
его символы с постоянным шагом 16 отсчётов. Для 1012 байт при −50 ppm
медианная ошибка в начале/расчётная ошибка в конце составили
−0,0325 / +0,3461 символа; при +50 ppm +0,0322 / −0,3464. Разность по
модели равна ±0,3786 символа. Начальную ошибку считаем по началу принятого
CRC-пакета и известной **после приёма** TX-шкале. Конечная ошибка
экстраполирована из заданного ppm при фиксированном шаге приёмника; это не
независимое измерение последнего символа. Для потерянного пакета эти оценки
равны `null`, а введённый моделью дрейф указан отдельно.
В JSON `correlation_candidates` считает кандидатов поиска. Поле
`detected_packets` равно числу CRC-valid пакетов: нынешний API не выдаёт
отдельное число пакетов, распознанных до CRC. Поля точности и потерь
считаются отдельно по TX-ведомости после приёма.
Отдельно проверены шесть сочетаний для **256 байт**, каждое с тремя пакетами:
| ppm | CFO | Фаза | Eb/N0 | Точные пакеты |
|---:|---:|---:|---:|---:|
| +5 | +20 Гц | +15° | 9 и 12 дБ | 3/3 при каждом уровне |
| +10 | +100 Гц | +90° | 9 и 12 дБ | 3/3 при каждом уровне |
| +20 | +100 Гц | −45° | 9 и 12 дБ | 3/3 при каждом уровне |
Итого **18/18**. Шум задан прежней программной AWGN-моделью VIDEO-005;
это не оценка реального RF-канала.
## Компенсация и скорость
Для основной сетки повторной оценки момента по преамбуле каждого пакета
хватило. **Непрерывное слежение в рабочий приёмник не добавлялось.** Для
расширения диапазона до ±100 ppm на пакете 1012 байт потребовалась бы
коррекция внутри пакета, например отдельное исследование детектора ошибки
момента [Gardner для BPSK/QPSK](https://doi.org/10.1109/TCOM.1986.1096561)
с интерполяцией и петлёй. [Документация GNU Radio](https://www.gnuradio.org/doc/doxygen/classgr_1_1digital_1_1symbol__sync__cc.html)
показывает такой класс синхронизатора и его параметры. Перед включением
понадобятся строгие CRC-тесты на всей сетке, проверка без истинного ppm и
новый замер скорости. Старый BPSK-детектор сюда не переносился.
На каноническом потоке VIDEO-005 из 32 длинных пакетов с добавленными
+20 ppm, +20 Гц CFO, фазой +15° и Eb/N0 9 дБ получено **32/32** при каждом
из трёх прогретых запусков. Времена приёмника: 0,272 / 0,262 / 0,262 с;
длительность IQ 0,485764 с; медианный **RADIO RECEIVER REALTIME FACTOR =
0,540**. Построение канала и ресемплирование в это время не входят. Для
сравнения, сохранённый ориентир VIDEO-005 равен 0,578 на другом входе;
разница не доказывает ускорения. Первый запуск ppm-сетки включал JIT и не
использован для оценки скорости. Порог 0,67 на этом ПК выполнен.
## Code quality audit
Рабочий `receive_iq_stream()` и его защитные проверки не менялись. Новый
пересчёт временной шкалы, сравнение с эталоном и запись JSON остаются вне
пути приёма. Отдельный `cProfile` того же 32-пакетного IQ занял 0,293 с;
его время включает накладные расходы профилировщика и не подставляется в
фактор 0,540. Основные этапы:
| Этап | Время, мс | Доля профиля | Вызовы | Основные массивы и копии |
|---|---:|---:|---:|---|
| Цифровое смещение несущей | 16,4 | 5,6% | 1 | Осциллятор и baseband |
| Согласованный RRC | 62,1 | 21,2% | 1 | Выход и внутренние FFT-буферы |
| Поиск преамбул | 47,6 | 16,2% | 1 | Две корреляции и массивы энергии |
| Восстановление момента | 9,9 | 3,4% | 32 | Индексы и символы каждого кандидата |
| Оценка CFO и фазы | 12,2 | 4,2% | 32 | Исправленные символы |
| PHY-заголовок | 0,8 | 0,3% | 32 | Короткие массивы заголовка |
| Слежение за фазой тела | 78,4 | 26,8% | 32 | Копия символов пакета и блоки решений |
| Строгий PHY/FEC/CRC | 54,8 | 18,7% | 32 | Мягкие биты и рабочие массивы декодера |
Число аллокаций NumPy не измерялось; в таблице перечислены видимые по коду
массивы. Resampling создаёт один выходной complex64 IQ и временные массивы
до миллиона отсчётов за блок; в измеренное время приёмника он не входит. Проверки
размеров и конечности IQ оставлены как защита входа; диапазон ppm и длина
пакета проверяются при создании опыта. Проверка эталона находится после
приёмника. Ruff не нашёл неиспользуемых импортов, временных compatibility
wrappers и лабораторных ветвей в новом коде нет. Канонический генератор
32-пакетного VIDEO-005 входа также строит сигнал с нарушениями канала,
который CLOCK-001 не использует; это один офлайн-вызов, не приёмный hot path.
Удалять или переписывать его здесь нет оснований. Поведение VIDEO-005
проверено его неизменённым шлюзом: 178 тестов прошли.
| Предмет | Место | Почему проверен | Решение |
|---|---|---|---|
| Дополнительный IQ от канонического генератора | `tools/clock001.py`, `run()` | Создаётся, но не участвует в CLOCK-входе | **KEEP**: однократная офлайн-цена за неизменный эталон VIDEO-005 |
| Длинная оркестрация опыта | `tools/clock001.py`, `run()` | Собирает сетку, сочетания и замер | **KEEP**: не исполняется в рабочем приёмнике; шаги явно разделены |
| Проверка конечности всего TX IQ | `tools/clock001.py`, `sample_independent_clock()` | Один проход по большому массиву | **KEEP**: защита от повреждённого входа до интерполяции |
В CLOCK-001 нет внешнего erasure FEC и видеотранспорта: это опыт с PHY-пакетами,
поэтому их время нельзя включать в фактор радиоприёмника.
## Следующий аппаратный план
План RF-001 разделён на **RF-001A** с проводной общей опорой 10 МГц как
лабораторным baseline и **RF-001B** с независимыми тактами. В B провод
CLKOUT → CLKIN отключён. Остальные параметры и TX-волна должны совпасть;
оба режима сохраняют исходный RX IQ и полные наблюдения счётчиков. В B
нужны последовательности оценок CFO и моментов пакетов, чтобы после
приёма оценить их изменение во времени и фактическую разницу частот
дискретизации. Моделируемые ppm не считаются характеристикой плат.
**Готовность A и B: да, только к подготовке контролируемого опыта.**
Фактические частоты, соединения, gain и RF-условия ещё не проверены. Для
каждого аппаратного сеанса потребуется отдельный preflight и прямое
разрешение. CLOCK-001 не открывала SDR, не меняла аппаратную конфигурацию
и не выполняла RF TX/RX. Коммита и push для этого этапа нет.

185
docs/rf/RF_001_PLAN.md Normal file
View File

@@ -0,0 +1,185 @@
# RF-001 — подготовка первого QPSK-пакетного опыта
**Статус: PREPARED / NOT_RUN.** Это программная подготовка после коммита
VIDEO-005 `6df5f8a`. SDR не открывался; приёма и передачи через него не было.
`RF TX = 0`. Первый аппаратный сеанс требует отдельной постановки и прямого
разрешения.
## Цель и граница
Будущий опыт проверит известные PHY-пакеты через два Auron HackRF Plus.
Утверждён один начальный режим: QPSK, **500 000 символов/с**, внутренний FEC
**2/3**, прикладная нагрузка **256 байт**, пауза **5 мс**, **100 пакетов** с
номерами 0–99 и seed `20260917`. H.264, камера, видеотранспорт, внешний
erasure FEC и адаптивное переключение не участвуют. До первого аппаратного
результата нагрузку не увеличивать, а паузу не уменьшать.
```text
TX: payload(seed, sequence) → build_frame(QPSK, 2/3) → shape_packet(RRC)
→ IQ-файл → [будущий аппаратный IQSink]
RX: [будущий аппаратный IQSource] → исходный raw IQ-файл
→ receive_iq_stream() VIDEO-005 → CRC-valid пакеты
→ отдельное сравнение с TX-ведомостью и отчёт
```
PHY-приёмник не получает TX-границы, payload, истинную фазу, CFO, момент
выборки или ожидаемое число пакетов. SHA и ошибки сравниваются после строгого
декодирования. `receive_iq_stream()` для RF-001 не менялся. Исторический
`build_frame()` ставит в пакет тип 3; здесь содержимое — тестовые байты,
видеосборщик не вызывается.
## Файловые инструменты
`tools/qpsk_rf_tx.py` создаёт весь IQ без аппаратных импортов в новом
каталоге `data/raw/rf001/offline_qpsk_100_packets/`. Существующие файлы он
не перезаписывает. Нагрузка каждого номера получается из SHA-256 по seed,
номеру и счётчику блока, без зависимости от версии генератора NumPy.
```powershell
python -B -X utf8 tools/qpsk_rf_tx.py
```
`tx_waveform.c64le` — сырые little-endian complex64, 8 байт на комплексный
отсчёт, без заголовка. `tx_metadata.json` содержит `test_id`, UTC-время,
режим, номинальный цифровой сдвиг несущей 125 кГц, seed, номера и SHA-256
payload/пакетов, паузу, dtype, число/длительность отсчётов, SHA IQ и
TX-границы. Последние остаются только в ведомости. Форма каждого пакета
включает по 64 защитных отсчёта на концах; между массивами вставлены
39 872 нулевых отсчёта. Итого пауза вместе с защитными участками — ровно
**40 000 отсчётов = 5 мс**. Это цифровая форма без аппаратной калибровки
амплитуды и преобразования к формату TX устройства.
`tools/qpsk_rf_rx.py` читает `c64le` и вызывает существующий приёмник
VIDEO-005. Необязательная TX-ведомость читается **после** вызова приёмника.
Для будущего сохранённого аппаратного файла предусмотрен вход
`--iq-format cs8`: чередующиеся знаковые байты I/Q преобразуются в
complex64 для анализа, исходный файл не меняется; отдельно считаются
коды насыщения −128/127. Это файловый конвертер, не аппаратный адаптер.
```powershell
python -B -X utf8 tools/qpsk_rf_rx.py `
--iq-file data/raw/rf001/offline_qpsk_100_packets/tx_waveform.c64le `
--truth-metadata data/raw/rf001/offline_qpsk_100_packets/tx_metadata.json `
--report data/processed/rf001/offline_roundtrip.json `
--numba-packages C:\Users\user\Desktop\projects\SDR_Rover\.lab053_cpu_runtime\packages
```
Путь `--numba-packages` относится к текущему ПК; на втором ноутбуке Numba
берётся из его окружения. Без TX-ведомости инструмент сообщает кандидатов
преамбулы и CRC-пакеты, номера, повторы и оценки CFO/фазы/такта, но не
объявляет точность или потери относительно неизвестного ожидаемого списка.
## Программный круг на 100 пакетах
| Показатель | Результат |
|---|---:|
| IQ | 8 833 828 отсчётов; 1,1042285 с; 70 670 624 байта |
| SHA-256 IQ | `7cd81395efaa88b623b7e4e5a02e3a80b52185007397ea56ceaacc13353974b2` |
| Кандидаты корреляционного поиска / отвергнутые | 557 / 457 |
| CRC-valid / точные пакеты | 100 / 100 |
| Пропущенные / дубли | 0 / 0 |
| Raw BER по всем 100 принятым пакетам | 0 / 322 500 кодированных битов |
| Ошибки после FEC | 0 в сопоставленных пакетах |
**557 — кандидаты корреляции, а не 557 принятых преамбул.** Только 100
прошли PHY/FEC/CRC. Raw BER получен отдельным повтором штатных PHY-функций
после первого приёма. При потере пакетов полный raw BER неизвестен: API
VIDEO-005 не отдаёт мягкие решения отвергнутых кандидатов. Тогда отчёт
покажет BER на CRC-valid пакетах отдельно, а `raw_ber` оставит `null`.
Условный BER нельзя выдавать за BER всего канала.
Полный машинный отчёт сохранён в `data/processed/rf001/offline_roundtrip.json`;
исходный IQ и TX-ведомость лежат в игнорируемом Git `data/raw/rf001/`.
## Будущий захват и аппаратная граница
Следующий этап сначала сохраняет **исходные** байты аппаратного RX, затем
анализирует их офлайн. Небольшая граница `IQSource` создаёт raw IQ-файл и
`capture_metadata.json`; файловый анализатор читает сохранённый файл.
`IQSink` сможет принять заранее проверенный TX-файл только после отдельного
допуска. PHY-модули не знают о HackRF API; собственный libusb-слой не нужен.
Предлагаемый файловый контракт capture: `capture.cs8` без заголовка, пары
знаковых байтов `I0,Q0,I1,Q1,…`; исходный файл не нормализовать и не
перезаписывать. `capture_metadata.json` создаётся рядом. Неизвестные поля
остаются `null` или `NOT_RUN`, а не заполняются нулями:
```json
{
"schema_version": 1,
"status": "NOT_RUN",
"raw_iq_file": "capture.cs8",
"iq_format": "cs8_interleaved_signed_iq",
"sample_rate_hz": 8000000,
"sample_count": null,
"raw_iq_sha256": null,
"capture_started_utc": null,
"center_frequency_hz": null,
"nominal_digital_carrier_offset_hz": 125000,
"clock_mode": "NOT_RUN",
"clock_link": "NOT_RUN",
"estimated_sample_clock_offset_ppm": null,
"cfo_series_hz": null,
"timing_drift_series_symbols": null,
"receiver_serial": null,
"gain_settings": null,
"common_clock": "NOT_RUN",
"tx_underrun_observations": [],
"rx_overrun_observations": [],
"rx_clipping_rail_codes": null,
"counter_observation_complete": false,
"capture_validity": "NOT_RUN",
"command_log": []
}
```
В metadata захвата потребуются время, путь/формат/SHA raw IQ, частота
дискретизации, центр RF, номинальный цифровой сдвиг, число отсчётов,
серийные номера, gain, состояние общей опоры, журнал команд и **все**
наблюдения underrun/overrun/clipping по ходу сеанса. Неполный или нечистый
счётчик делает результат непригодным для PASS; конечный ноль не отменяет
промежуточную потерю. Сейчас аппаратного источника/стока и фактического
capture metadata нет — это будущая отдельно разрешённая работа.
Дрейф частоты дискретизации не моделировался в VIDEO-005 и остаётся отдельным
риском для реального захвата.
RF-001 делится на два будущих режима с отдельным разрешением на каждый выход
в эфир. **RF-001A** использует проводную общую опору 10 МГц только как
лабораторный baseline: TCXO → MASTER → MASTER CLKOUT → SLAVE CLKIN. Предыдущие
лабораторные проверки фиксировали MASTER и SLAVE `reg29 = 0x26`, `SLAVE CLKIN =
DETECTED`. Это **исторические данные**, а не свежая проверка подключения.
**RF-001B** использует независимые такты: провод CLKOUT → CLKIN снят. Именно
этот вариант соответствует архитектуре ровера и НСУ без проводной опоры.
Для сравнения A/B одинаковыми остаются RF-частота, 500 ксимв/с, FEC 2/3,
payload 256 байт, пауза 5 мс, 100 пакетов, TX-уровень, RX-усиления,
геометрия, антенны и TX-волна. Оба сеанса сначала сохраняют исходный RX IQ и
полный журнал счётчиков. В RF-001B по принятой преамбуле каждого пакета и
известным TX-номерам нужно оценить CFO по времени и наклон ошибки момента
выборки, затем разницу частот дискретизации. Эти оценки делаются **после**
строгого PHY/FEC/CRC; потери и пропуски не подменяются известными границами
передатчика. Программная сетка CLOCK-001 проверила до ±50 ppm, но фактический
ppm плат ещё не измерен. Частота RF, gain, кабели, антенны и уровень сигнала
для нового опыта не утверждены здесь; они войдут в отдельный аппаратный
preflight.
## Форма отчёта и следующий критерий
Будущий отчёт содержит `RF-001 STATUS`, режим, число кандидатов преамбулы,
CRC-valid и точных пакетов, долю точных, raw BER с областью расчёта,
ошибки после FEC, дубли/пропуски, медиану CFO и P95 |CFO|, оценки фазы/такта,
TX underruns, RX overruns, RX clipping, общую опору
`DETECTED / NOT_DETECTED`, SHA capture и причины отказа. Сейчас аппаратные
поля — `NOT_RUN`, а не нули.
Для будущего короткого OTA smoke test, если захват и счётчики чисты:
не менее 99 точных из 100 — GOOD; 95–98 — DIAGNOSTIC/PARTIAL; менее 95 —
не переходить к видео. Это предварительная классификация, не
эксплуатационная норма. Программные 100/100 не доказывают RF PASS.
Только после отдельного аппаратного PASS: сравнение пауз 5 → 2 → 1 → 0,5
→ 0 мс при 256 байтах. После выбора паузы — отдельно 256 → 512 →
максимально допустимый рабочий payload. Здесь матрица не выполняется.
**RF-001 HARDWARE STATUS = NOT_RUN. SDR HARDWARE = NOT_ACCESSED. RF TX = 0.**
Следующий шаг — отдельное согласование preflight и одного контролируемого
сеанса; автоматического перехода к эфиру нет.

View File

@@ -0,0 +1,48 @@
# Второй ноутбук для будущего RF-001
Это список подготовки Windows 10/11. В текущей задаче второй ноутбук,
USB-драйвер и HackRF не проверялись. Никакой пункт ниже не запускается
автоматически.
## Программы и проект
1. Зафиксировать выпуск Windows и имеющийся USB-драйвер для каждого Auron
HackRF Plus. Сначала инвентаризация; Zadig не запускать без отдельного
решения. Прошивку устройства не обновлять автоматически.
2. Установить Git и VS Code. Установить **Python 3.13.1**, как на основном
ПК при подготовке RF-001; проверить `python --version` и `git --version`.
3. Получить согласованный коммит и ветку `video-development`, сверить HEAD.
Создать отдельное виртуальное окружение Python и установить зависимости
из `requirements-video.txt`; для разработки также
`requirements-video-dev.txt`. Проверить импорты NumPy, SciPy и Numba,
затем запустить целевые программные тесты.
4. Установить совместимые HackRF host tools/libhackrf, но до отдельного
аппаратного разрешения не открывать устройство. Позже, во время
согласованной инвентаризации, проверить `hackrf_info` и сведения
о каждом устройстве, не выполняя TX/RX. Не заменять драйвер только ради
ошибки команды без проверки текущего состояния USB.
5. Сверить SHA-256 программного `tx_waveform.c64le` с TX-ведомостью RF-001.
Локально повторить файловый RX: 100/100 точных пакетов до аппаратного
этапа.
## Перед будущим аппаратным сеансом
- Зафиксировать серийные номера MASTER/SLAVE, версии firmware и host tools,
идентификаторы USB и состояние драйверов. Само наличие `hackrf_info` не
означает исправную общую опору или готовность к передаче.
- Сверить физическую схему TCXO 10 МГц → MASTER → MASTER CLKOUT → SLAVE
CLKIN для лабораторного RF-001A; не создавать петлю через SLAVE CLKOUT.
Для отдельного RF-001B провод CLKOUT → CLKIN отключается при неизменных
прочих параметрах. Исторические проверки
`reg29 = 0x26` на обеих платах и `SLAVE CLKIN = DETECTED` нужно подтвердить
в новом preflight, если он будет отдельно разрешён.
- Записать согласованные RF-частоту, усиления, антенны/кабели, геометрию,
формат TX и лимиты уровня. Цифровой файл complex64 не является готовым
аппаратным потоком до отдельного преобразования и проверки уровня.
- Настроить сохранение исходного RX IQ и metadata **до** офлайн-декодирования.
Сохранить полный журнал команд и значения underrun/overrun/clipping,
включая промежуточные наблюдения. Неполный захват не считать PASS.
Команды `python --version`, `git --version` и `hackrf_info` приведены как
будущий чеклист. В рамках программной подготовки RF-001 аппаратные команды
не выполнялись, RF TX = 0.