# SDR Rover Link

## 1. Назначение проекта

**SDR Rover Link** — учебно-исследовательский проект по разработке цифрового радиоканала для наземного робототехнического комплекса с использованием программно-определяемого радио — SDR, Software Defined Radio.

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

Основная задача — не только получить работающую систему, но и последовательно изучить все этапы цифровой радиосвязи: формирование данных, разбиение на пакеты, контроль целостности, исправление ошибок, цифровую модуляцию, формирование IQ-сигнала, передачу через SDR, приём, демодуляцию и восстановление исходных данных.

---

## 2. Целевой сценарий

| Параметр | Требование |
|---|---|
| Дальность связи | до 10 км |
| Скорость ровера | до 25 км/ч |
| Прямая радиовидимость | может отсутствовать |
| Рабочий диапазон | 200–250 МГц, см. Запись 018 журнала |
| Основной тип данных | телеметрия, команды и изображения |
| Формат изображения | JPEG |
| Действие при потере связи | безопасная остановка ровера |

Дальность 10 км без прямой видимости — целевое исследовательское требование, а не гарантированная характеристика первой версии.

---

## 3. Почему не используется обычное FPV-видео

Типовые FPV-системы работают в диапазонах 2,4 и 5,8 ГГц. Для наземного робота это плохо: велики потери у поверхности земли, сильное затенение рельефом и растительностью, а главное — на таких частотах практически нет дифракции, поэтому за препятствием связь пропадает.

В этом проекте вместо непрерывного видеопотока передаются отдельные сжатые изображения, что резко снижает требуемую скорость канала.

---

## 4. Текущее состояние

**Выполнено:** лабораторные Lab001–Lab041. Пройден путь от структуры пакета до сеансов связи с защитой от пакетов предыдущего сеанса.

Что реализовано и проверено:

- пакетный протокол с CRC32, фрагментация и сборка изображений;
- модуляция и демодуляция BPSK, формирующий фильтр, кадровая синхронизация, оценка и коррекция ухода несущей;
- блочное исправление стираний над GF(256), перемежение, подбор параметров;
- приоритетное обслуживание команд, телеметрии и видео;
- двухступенчатая безопасная остановка, сторожевой таймер, постоянное аварийное намерение, безопасный сброс;
- идентификаторы сеанса, безопасный запуск, отклонение пакетов предыдущего сеанса.

**Что ещё не сделано:** передатчик ни разу не включался. Весь тракт проверен на моделях и на приёме, но не в эфире.

**Ближайшая работа:** Lab042 — передача JPEG через кабельную петлю на одном PlutoSDR. Техническое задание: [docs/lab042_hardware_loopback_spec.md](docs/lab042_hardware_loopback_spec.md).

Хронология решений и результатов: [PROJECT_LOG.md](PROJECT_LOG.md).

---

## 5. Оборудование

| Позиция | Состояние |
|---|---|
| **Pluto+** — приёмопередатчик, чип AD9361, 70 МГц – 6 ГГц | есть |
| RTL-SDR — приёмный донгл | есть |
| Аттенюатор AT30S, 30 дБ, SMA | есть |
| Кабели SMA, штыревые антенны | есть |
| Усилитель мощности около 1 Вт | планируется после первых испытаний |
| Raspberry Pi как бортовой вычислитель | планируется |

Устройство подключается по USB и появляется в системе как сетевой адаптер с адресом `192.168.2.1`.

**Проверять связь с Pluto командой `ping` бесполезно.** При активном VPN трафик уходит в туннель, и «успешный» отклик приходит даже от несуществующего адреса. Достоверна только успешная установка контекста `iio.Context("ip:192.168.2.1")`.

---

## 6. Установка окружения

Расчётная часть работает на компьютере без SDR:

```bash
python -m pip install -r requirements.txt
```

Для лабораторных, работающих с устройством, дополнительно:

```bash
python -m pip install -r requirements-hardware.txt
```

Версии зафиксированы по проверенному окружению, Python 3.13.

---

## 7. Как запускать

**Быстрые проверки ядра** — секунды, оборудование не нужно:

```bash
python -m pytest tests/ -q
```

**Дешёвый шлюз** — синтаксис, импорт `protocol`, функциональные проверки лабораторных:

```bash
python tools/quick_gate.py
```

**Лабораторный эксперимент** — минуты, пишет результаты в `data/processed/`:

```bash
python -m experiments.lab041_session_restart_safety
```

---

## 8. Структура репозитория

```text
SDR_Rover
├── protocol/        реализация протокола и радиотракта
├── experiments/     лабораторные Lab001–Lab041
├── tests/           быстрые автоматические проверки
├── tools/           вспомогательные программы и шлюз
├── docs/            технические задания и исследования
├── data/            исходные данные и результаты
├── rover/           пока пусто
├── ground_station/  пока пусто
└── gnuradio/        пока пусто
```

### `protocol`

Ядро системы. Пакет с CRC32, фрагментация изображений, кадр канала, исправление стираний, приоритеты, аварийная логика, сеансы связи, примитивы BPSK-радиотракта.

### `experiments`

Лабораторные работы. Это исследовательские программы: они моделируют канал, выполняют сотни повторов, строят CSV, графики и отчёты. **Быстрыми тестами они не являются.** При импорте создают каталоги и пишут файлы, поэтому импортировать их не следует — для повторного использования кода служит `protocol/`.

### `tests`

Настоящие быстрые проверки `protocol/`. Выполняются за доли секунды, оборудования не требуют, запускаются через `pytest`.

### `rover`, `ground_station`, `gnuradio`

Каталоги созданы под будущую прикладную часть и пока пусты. Бортовая программа ровера, программа наземной станции и схемы GNU Radio появятся после того, как радиоканал заработает в эфире.

---

## 9. Данные

- `data/raw` — исходные данные. Крупные записи отсчётов и видео в репозиторий не помещаются, исходные изображения лабораторных хранятся.
- `data/processed` — результаты лабораторных: CSV, отчёты и графики.

**Ограничение воспроизводимости.** Исходное видео `data/raw/lab026_rover_source.mp4` (около 7,8 МБ) в репозитории не хранится. Без него Lab026 и Lab027 не запускаются, файл нужно получить отдельно.

---

## 10. Принципы разработки

1. Каждый новый термин сначала объясняется, затем используется.
2. Каждый этап завершается работающим результатом.
3. Радиоканал и пакетный протокол разрабатываются отдельно.
4. Код проверяется автоматическими тестами.
5. Все существенные решения фиксируются в журнале.
6. Сложность увеличивается постепенно.
7. Испытания по эфиру начинаются только после проверки через модель.
8. Передатчик сначала проверяется через аттенюатор или эквивалент нагрузки.
9. **Каждое число в отчёте должно вычисляться из измерений текущего запуска.** Перенесённые из других лабораторных величины сопровождаются указанием источника. Вписанные вручную результаты недопустимы.

Девятое правило добавлено после аудита достоверности, см. Запись 017 журнала.

---

## 11. Автор

Антон

НИЯУ МИФИ

2026