Pluto-SDR/docs/NOTES.md

NOTES.md — грабли, ограничения и почему так

Здесь собрано всё, что не является кодом, но экономит дни отладки.

1. Плата: Pluto+ ≠ ADALM-Pluto

Наши платы — клоны «Pluto+» (Zynq-7020). Отличия от стокового ADALM-Pluto (7010), которые влияют на проект:

	Pluto+ (у нас)	ADALM-Pluto сток
SoC	Zynq-7020	Zynq-7010
Ядра ARM	2 активных	1 (второе — через хак)
RAM	1 ГБ	512 МБ
Ethernet	есть гигабитный	нет (только USB)

Следствия: бюджет «одно ядро на DSP, второе на IO» валиден только на наших платах; на стоковом Pluto весь тракт не поместится. Все замеры (docs/BENCHMARK.md) сделаны на Pluto+.

Особенности прошивки v0.38:

• нет sftp-server → только scp -O (legacy protocol);
• rootfs в RAM → всё в /tmp и /root пропадает при ребуте; бинарники заливаются заново (make deploy), «установить навсегда» = пересборка прошивки, нам не нужно;
• BogoMIPS 333 в /proc/cpuinfo — артефакт таймера, реальная частота 667 МГц;
• пароль root: analog.

2. FDD и самоглушение (главный риск этапа «в воздух»)

План FDD: A TX 915 / RX 868; B TX 868 / RX 915 (разнос 47 МГц). Проблема: дуплексеров нет. Собственный передатчик платы в паре сантиметров от собственного приёмника:

• широкополосный шум TX попадает в полосу RX даже при разносе 47 МГц;
• сильный сигнал TX блокирует (десенсибилизирует) входной каскад RX.

Характерный симптом: симплекс и loopback работают идеально, а в дуплексе RX платы «глохнет», как только её TX активен. Это не баг кода.

Меры (по нарастанию):

1. максимальный tx_attenuation, какой позволяет линия;
2. физический разнос TX/RX антенн + кросс-поляризация;
3. SAW-фильтр 868 МГц на RX-вход (копеечный, SRD-диапазон);
4. если ничего не помогает — честный TDD на одной частоте.

Поэтому порядок работ: сначала симплекс (обе платы 915 МГц, полудуплекс по очереди), FDD — отдельным этапом с замерами деградации RX при активном TX.

2.1. Предварительные замеры (этап 1, §10 п.7 — FDD-водопровод)

Числа сняты на сконфигурированном, но молчащем обратном тракте (LO 868 поднят, hardwaregain выставлен, но DMA обратного TX ничего не пушит). Полноценный gate с реальным STATUS-трафиком — этап 2, числа уйдут в §2.2.

• Самоглушения от «просто включённого» обратного тракта не видно. Форвард A→B под FDD (1 МБ, -p 4000, group-FEC) байт-в-байт и при fb-TX -g -89 (≈выкл), и при -g -20 (штатное). Активный обратный LO 868 в 47 МГц от RX 915 приёмник данных не глушит — на кабеле+аттенюаторе. Это ответ на вопрос PER₁ (десенс от включённого тракта), но НЕ на PER₂ (десенс от реального излучения STATUS) — тот снимается в этапе 2.
• Диагностика: пустой файл на выходе RX ≠ самоглушение. Симптом «0 кадров, RSSI −100» — это НЕ глушение, а мёртвый вход: остаточный процесс держит RX-DMA (cf-ad9361-lpc) от неубитого прошлого запуска. Глушение выглядит ИНАЧЕ — сильный RSSI (−48) при разрушенном EVM (−2.5). Различать по RSSI. Лечение: killall -9 receiver transmitter перед каждым стартом (уже в scripts/test_fdd_fwd.sh).
• Ридбэк LO округляется PLL. AD9361 — дробный-N синтезатор с шагом ~2 Гц: 868000000 читается как 867999998. Это норма, не ошибка; сверка ридбэка идёт с допуском FDD_LO_TOL_HZ=100 Гц (common.c).
• Канал деградировал против этапа 0. Эталон регрессии сдвинут -p 3000 → -p 4000 (на 3000/3500 теперь Overrun+потери). Направление B→A флапает даже на -p 4000 при СИЛЬНОМ RSSI (−33…−35) — вероятна компрессия входа RX (усиление 50 дБ избыточно). Проверить снижением RX/TX gain до свипа частот.

2.2. Gate-замер самоглушения (этап 2, 2026-07-16) — вердикт: FDD принят

Условия: кабель+аттенюатор, данные A→B 915 (TXGAIN −30, -p 4000, GROUPFEC=0 — сырой PER без маскировки), STATUS B→A 868 (10 Гц), 1 МБ = 1024 кадра на прогон. Полные числа — README §12.8.

• PER₀ (симплекс, 3×): потерь 3/5/14 → 0.29–1.37%, среднее 0.72% (канал флапает, см. выше).
• PER₂ (FDD, STATUS в эфире, FBGAIN −80…0, 8 прогонов): потерь 1–11, среднее 0.51%. PER₂−PER₀ ≈ −0.2 п.п. — излучение STATUS форвард-линк не трогает вообще, ни при каком усилении. PER₁≈PER₀ снят ранее (§2.1).
• Доставка STATUS B→A: 0% при FBGAIN ≤ −40 (не пробивает аттенюатор); плато ~50% при −20…0 (47/52/52/50/51%) — от усиления НЕ зависит.
• FBGAIN=0 дал первые «RS битых: 3» на RX данных платы B → лёгкий самодесенс B на максимуме fb-TX. Рабочее окно fb-TX на кабеле: −20…−10.

Плато 50% — структурное, не RF. Гипотеза: fb-RX платы A десенсится её же TX-бёрстом (механизм §2, но на стороне A). Duty данных при -p 4000 = 57% (кадр 5.33 мс + пауза 4 мс); STATUS ~1.4 мс выживает только попав в паузу — доля доставки ≈ доле тихого времени и потому не зависит от FBGAIN. Проверка при случае: PAUSE=8000 должен поднять доставку. Приятное следствие: в фазе ретрансмитов и END-хендшейка ARQ плата A передаёт мало → доставка растёт именно там, где обратная связь критична.

Вердикт gate. Исходный критерий «≥99% доставки» был перестрахован и пересмотрен: STATUS кумулятивен по построению (потеря безвредна — следующий несёт то же состояние), 50% доставки = эффективные ~5 Гц фидбэка, для ARQ с rate-limit 2× периода и TX-окном ~19 с этого с большим запасом достаточно. Рабочий критерий: доставка стабильна (≥30%) И PER₂−PER₀ ≤ +0.3 п.п. И PER₁≈PER₀ — выполнен, этап 5 (fallback TDD, цена ~8% throughput) не нужен.

Замечание к методике: у приёмника НЕТ флага усиления RX данных (константа RX_GAIN=50 в коде; -g приёмника — усиление fb-TX). Переменная окружения RX_GAIN скриптами не читается — прогоны «RX_GAIN=40/30/20» были репликами FBGAIN=0 (они и дали три точки плато). Гипотеза компрессии входа при RSSI −33…−35 (см. §2.1) остаётся непроверенной, но gate она не блокирует.

2.3. Находки этапа 3 (ARQ, 2026-07-16)

Клифф канала на кабеле — свипу PER здесь не место. TXGAIN −30 даёт PER 0.4%, −38 — уже CRC: 0 при живых Заголовках: 3322. Порог заголовка и порога payload разнесены: заголовок ofdmflexframe идёт BPSK с собственным FEC, payload — QPSK+RS(255,223), и падает он первым. Практический смысл: живой счётчик «Заголовков» при нулевом CRC — это не «плохой канал», а его отсутствие; диагностику по такому прогону строить нельзя, ARQ там нечего вытягивать. Аттенюатор даёт слишком грубый шаг — карта PER снята свипом в README §12.4.

Направления несимметричны. На одном и том же кабеле A→B даёт RS битых: 0, B→A — RS битых: 20…28 на 1024 кадрах. Разброс устойчив между прогонами, то есть это не статистика, а свойство пары плат/тракта. Для ARQ безразлично (ретрансмит закроет), но при выборе направления для чувствительного трафика и при трактовке PER-замеров это надо помнить: цифры одного направления не переносятся на другое.

Ловушка «битый кадр выпадает из NACK». miss_ack(seq) по факту приёма кадра (до декода) — тихо ломает ARQ: кадр, не прошедший RS/CRC, снимался с NACK навсегда, A его не досылал, а RX считал файл собранным → A рапортовал успех с битым md5. Учёт NACK обязан идти ПОСЛЕ декода: ok → miss_ack, !ok → miss_add_sorted. Битый кадр — такая же дыра, как непришедший, просто обнаруженная не детектором seq. Не выстрелило на приёмке 3a лишь потому, что там случились RS битых: 0.

Ловушка «COMPLETE съеден снимком». STATUS на A забирается снимком (latest-wins, fb_take гасит флаг свежести). Если бы COMPLETE читался из снимка, arq_service съел бы тот самый STATUS, в котором он приехал, и A ушёл бы в 10-секундный таймаут на ЦЕЛОМ файле. COMPLETE поэтому — отдельная монотонная защёлка, взводимая прямо в fb_callback.

Переполнение MISS_CAP — тупик без пересборки. miss_add при переполнении молча теряет seq, и вернуть его в NACK уже некому: детектор дыр по нему второй раз не сработает (highest_seq ушёл вперёд). В тяжёлом канале это заклинивало приём насмерть. Лечится тем, что кольцо reorder знает точно, каких кадров нет: miss_rebuild() пересобирает NACK из кольца на каждом END (A шлёт их 10 Гц до самого COMPLETE, скан ≤1024 — сотые доли ядра).

3. Регуляторика (868/915 МГц в регионе ETSI)

• 868 МГц — SRD-диапазон: ограничения на полосу канала (сотни кГц), ЭИИМ и duty cycle. Наш сигнал 1.5 МГц в них не вписывается.
• 915 МГц — в Европе это uplink GSM-900, не ISM (ISM 902–928 — регион США).

Практический вывод: разработка и демо — кабель с аттенюатором или антенны на столе с минимальной мощностью (TX gain от −40) и без внешних усилителей. Это ограничение прототипа фиксируется в отчёте проекта; у целевой системы по ТЗ предполагается лицензированный канал.

4. RF-безопасность

• Кабельный тест только через аттенюатор 30–40 дБ + -g -40. Прямое соединение TX→RX выжигает входной каскад AD9361.
• Диапазон DAC/ADC — 12 бит (±2047 в int16). Клиппинг при амплитуде TX > ~0.5 виден как рост EVM на RX.

5. Особенности liquid-dsp, найденные в бою

• Заголовок пользователя по умолчанию 8 байт. Наш формат — 12 байт. Без ofdmflexframegen_set_header_len(fg,12) / ofdmflexframesync_set_header_len(fs,12) байты 8–11 (nblocks, last_block_bytes) в эфир не уходят, RX читает мусор за границей буфера.
• fec_decode() не сообщает об ошибках: RS-декодер liquid всегда «успешен», неисправимый блок просто отдаёт мусор. Единственный надёжный критерий целостности — CRC/md5 поверх декодированных данных.
• Без FFTW liquid молча деградирует на встроенный FFT. Проверка после сборки обязательна: grep HAVE_LIBFFTW3F config.log.
• ofdmflexframesync сам оценивает и компенсирует CFO по преамбуле; внешний NCO-контур поверх него (как в раннем receiver.c) не нужен и с set_phase(0) на границах буферов — вреден.

6. Почему архитектурные решения именно такие

• Статическая линковка: независимость от libc прошивки, деплой одним файлом, нет возни с sysroot ADI. Цена ~2 МБ — ничто при 1 ГБ RAM.
• rate 1.92, а не 3.84 MSPS: замер (BENCHMARK.md) — 2.34 Msps потолок синхронизатора на кадрах. 3.84 даёт отказ «работает на демо, падает под нагрузкой» — худший для радиолинии вид отказа.
• OFDM оставлен, несмотря на цену CPU: код написан и проверен; single-carrier QPSK дал бы ту же полезную скорость дешевле, но потребовал бы написать и отладить синхронизацию заново. Решение можно пересмотреть, если понадобится rate > 1.92 MSPS (см. резервы в BENCHMARK.md).
• Симплекс раньше FDD: изолирует проблемы кода от проблем RF (п. 2).

7. Быстрые команды-шпаргалки

# что видит плата
iio_info -u ip:192.168.2.1 | less
iio_attr -u ip:192.168.2.1 -c ad9361-phy altvoltage1 frequency   # TX LO

# загрузка CPU на плате во время линии (busybox top)
ssh root@192.168.2.1 top

# логи TX/RX после test_file_link.sh
ssh root@<ip> 'cat /tmp/tx.log /tmp/rx.log'