From 51609ccae7c41188ab4ac8a924f97fbf3f0f83f7 Mon Sep 17 00:00:00 2001 From: Maxim Date: Wed, 15 Jul 2026 15:00:49 +0300 Subject: [PATCH] =?UTF-8?q?docs/USAGE.md=20=E2=80=94=20=D1=80=D1=83=D0=BA?= =?UTF-8?q?=D0=BE=D0=B2=D0=BE=D0=B4=D1=81=D1=82=D0=B2=D0=BE-=D0=BA=D0=BE?= =?UTF-8?q?=D0=BC=D0=BF=D0=B0=D0=BD=D1=8C=D0=BE=D0=BD=20=D0=BA=20README=20?= =?UTF-8?q?=D1=81=20=D0=BF=D1=8F=D1=82=D1=8C=D1=8E=20=D1=80=D0=B0=D0=B7?= =?UTF-8?q?=D0=B4=D0=B5=D0=BB=D0=B0=D0=BC=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 ++ docs/USAGE.md | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 89 insertions(+) create mode 100644 docs/USAGE.md diff --git a/README.md b/README.md index 8dc7e3f..ec201d3 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ PHY: OFDM (liquid-dsp) + RS(255,223) FEC. Весь сигнальный трак бинарей и снятия логов. Прототип в рамках ОКР «R-Link» (двухранговая самоорганизующаяся сеть); данный репозиторий покрывает уровень PHY/линка. +**Быстрый старт (clone → сборка → приём/передача) — [docs/USAGE.md](docs/USAGE.md).** + --- ## 1. Аппаратная платформа (фактическая, проверено) diff --git a/docs/USAGE.md b/docs/USAGE.md new file mode 100644 index 0000000..3cba3b6 --- /dev/null +++ b/docs/USAGE.md @@ -0,0 +1,87 @@ +# USAGE.md — руководство пользователя pluto-link + +Практический быстрый старт к [README.md](../README.md). README — инженерный +журнал (бюджет CPU, история отладки, §12-этапы, техдолг); этот файл — короткий +путь «склонировал → собрал → залил → поднял приём/передачу». Детали и обоснования +цифр — в README §12 и [BENCHMARK.md](BENCHMARK.md). + +## 1. Что это + +Радиолиния точка-точка на двух ADALM-Pluto+ (клон, Zynq-7020, 2 × Cortex-A9). +Весь сигнальный тракт (OFDM + RS(255,223) FEC) исполняется на ARM **внутри** +Pluto; хост (Raspberry Pi, aarch64) нужен только для кросс-сборки, заливки +бинарей и снятия логов. Рабочая точка: симплекс 915 МГц, ~120 КБ/с (legacy) или +~95 КБ/с с групповым FEC 16+2 (`-G`), передача файлов байт-в-байт. + +## 2. Быстрый старт (5 команд) + +На свежем клоне репозитория (на хосте — Raspberry Pi): + +```bash +./scripts/build_deps.sh # 1. один раз: кросс-либы в ~/xarm +make # 2. собрать tx/rx/bench → build/ +make deploy PLUTO_A=192.168.2.1 PLUTO_B=192.168.3.1 # 3. scp -O на обе платы в /tmp +ssh root@192.168.3.1 '/tmp/receiver -f 915000000 -r 1920000 -b 1500000 -c rs8 -u local: > /tmp/out.bin' # 4. приём (B) +ssh root@192.168.2.1 'cat /tmp/file.bin | /tmp/transmitter -f 915000000 -r 1920000 -b 1500000 -g -30 -p 4000 -c rs8 -G -u local:' # 5. передача (A) +``` + +Или всё сразу: **`scripts/test_file_link.sh`** — генерит тестовый файл, гоняет +A → эфир → B и сверяет md5. + +- Пароль root на Pluto — `analog`. `apt install sshpass` убирает ручной ввод + пароля (скрипты подхватывают его автоматически). +- rootfs платы в RAM: после перезагрузки Pluto бинари из `/tmp` пропадают — + залить заново (`make deploy`). +- ⚠ Перед эфиром отлаживай по кабелю с аттенюатором 30–40 дБ и TX gain −40 + (`-g -40`), только потом антенны и дистанция (правило №7 CLAUDE.md). + +## 3. Типовые команды + +| Сценарий | Команда | +|---|---| +| Собрать всё | `make` | +| Залить на обе платы | `make deploy` (или `scripts/deploy.sh `) | +| E2E-тест с md5-сверкой | `scripts/test_file_link.sh` | +| Короткий файл ≤1 МБ | TX `-p 3000` (без `-G`) | +| Длинная / соук-передача | TX `-p 4000 -G` (групповой FEC 16+2, README §12.7) | +| Первый эфир по кабелю | `TXGAIN=-40 scripts/test_file_link.sh` | +| OTA на антенны | `TXGAIN=-20 scripts/test_file_link.sh` | +| Соук 10 МБ | `GROUPFEC=1 PAUSE=4000 scripts/test_file_link.sh 10240` | +| Бенчмарк PHY на плате | `make bench && scripts/deploy.sh bench && ssh root@ '/tmp/ofdm_bench 1.92'` | +| Без FEC (отладка PHY) | `-c none` на обеих сторонах | + +## 4. Параметры + +Флаги передатчика: `-f -r -b -g -a -p -u -c -G`. Приёмник понимает только общие: +`-f -r -b -u -c`. Колонка «Сторона» отмечает передатчик-специфичные (`-g/-a/-p/-G`). + +| Флаг | Значение | По умолч. | Сторона | Примечание | +|---|---|---|---|---| +| `-f` | несущая, Гц | 915000000 | TX + RX | одинаково на обеих | +| `-r` | sample rate, Гц | 1920000 | TX + RX | **не поднимать** — бюджет CPU (правило №5, BENCHMARK.md) | +| `-b` | полоса, Гц | 1500000 | TX + RX | — | +| `-g` | TX gain, дБ | −30 | TX | кабель −40, антенны от −20 | +| `-a` | амплитуда сигнала | 0.20 | TX | обычно не трогать | +| `-p` | пауза между кадрами, мкс | 2000 | TX | ≤1 МБ → 3000; длинные / `-G` → **4000** (§12.7) | +| `-c` | FEC: `rs8` \| `none` | rs8 | TX + RX | должно совпадать на обеих сторонах | +| `-G` | групповой FEC 16+2 | выкл | TX | RX автодетект по флагам в hdr[11] | +| `-u` | URI libiio | — | TX + RX | в тракте всегда `local:` (правило №2) | +| `-h` | справка | — | TX + RX | — | + +## 5. Troubleshooting + +| Симптом | Вероятная причина | Что делать | +|---|---|---| +| `out.bin` = 0 байт | RX ничего не поймал: частота / усиление / кабель | сверь `-f`, TX gain, аттенюатор или антенны | +| размер меньше исходного | потерянные кадры (симплекс, ARQ нет) | включи `-G`; смотри разрывы seq в `rx.log` | +| размер равен, md5 не сходится | header_len ≠ 12 (техдолг #1) или fec_decode (#3) | 12-байт заголовок на обеих сторонах; проверь `-c` | +| много `Overrun` в `rx.log` | ядро 0 срывается под нагрузкой | подними `-p` (3000 → 4000), см. §12.7 | +| 10 МБ-соук падает на `-p 3000` | overrun-пачки рвут стирающий FEC | только `-p 4000` — проверенная точка | +| `Invalid argument (22)` на rate | AD9361 без FIR не берёт 1.92 Msps | нужен FIR через `ad9361_set_bb_rate` (уже в коде) | +| `Reed-Solomon codes unavailable` | liquid собран без libfec | пересобрать liquid (`rm libliquid.a`, затем `make`) | +| `scp` виснет / `subsystem request failed` | в прошивке v0.38 нет sftp-server | только `scp -O` (deploy.sh уже так делает) | +| после ребута Pluto бинарей нет | rootfs в RAM, `/tmp` очищается | `make deploy` заново | +| ssh каждый раз просит пароль | не установлен sshpass | `apt install sshpass` (пароль `analog`) | + +Более глубокая диагностика линка — README §11; журнал этапов и рабочие точки — +README §12; бюджет CPU и модель паузы — [BENCHMARK.md](BENCHMARK.md).