# Обзор

## Что это

**Флоуграф** (flowgraph) — граф обработки сигнала в GNU Radio: цепочка блоков,
через которые проходят отсчёты от приёмника до декодированного кадра телеметрии.
В этом репозитории каждый флоуграф описан файлом `.grc` (YAML, формат GNU Radio
Companion), а при сборке `grcc` превращает его в исполняемый Python-скрипт
`satnogs_<имя>.py`.

`soniks-flowgraphs` содержит два слоя:

1. **Флоуграфы** — `.grc` в каталогах [`generic/`](flowgraphs/generic.md) (режимы
   общего назначения: FM, FSK, BPSK, CW, APT, SSTV) и
   [`satellites/`](flowgraphs/satellites.md) (декодеры под конкретные спутники и
   протоколы, включая Geoscan и USP).
2. **Запускатор** — `flowgraph_dispatcher/`: Python-скрипт, который выбирает
   нужный флоуграф по названию режима, поднимает его и три процесса-подписчика,
   пишущих результаты на диск.

## Место в инфраструктуре Соникс

```
   ┌──────────────────┐
   │  soniks-network  │  планирует наблюдение: спутник, время, частота, режим
   └────────┬─────────┘
            │ задание наблюдения
            ▼
   ┌──────────────────┐        ┌──────────┐
   │ soniks-client-new│───────▶│ rotctld  │  наведение антенны
   └────────┬─────────┘        └──────────┘
            │
            │ flowgraph_dispatcher --mode <MODE> --rx-freq=… --soapy-rx-device=…
            ▼
   ┌─────────────────────────────────────────────────────────┐
   │  flowgraph_dispatcher            (этот репозиторий)     │
   │                                                         │
   │   ├── satnogs_<mode>.py  ── GNU Radio ──┐               │
   │   │        ▲                            │ ZMQ           │
   │   │        │ доплер                     ▼               │
   │   │   ┌────┴────┐            ┌──────────────────────┐   │
   │   │   │ rigctld │            │ zmq_frame_decoder_sub│   │
   │   │   └─────────┘            │ zmq_iq_sub           │   │
   │   │                          │ zmq_audio_sub        │   │
   │   └── SoapySDR ◀── антенна   └──────────┬───────────┘   │
   └──────────────────────────────────────────┼──────────────┘
                                              ▼
                            кадры (JSON) · аудио (OGG) · IQ (raw) · водопад
                                              │
                                              ▼
                                   soniks-client-new → soniks-network
```

Клиент станции не знает про отдельные флоуграфы — он вызывает один бинарник
`flowgraph_dispatcher` и передаёт ему режим модуляции строкой `--mode`.
Соответствие «режим → флоуграф» описано в [](modes.md).

## Что происходит во время наблюдения

1. Клиент запускает `flowgraph_dispatcher` с параметрами приёмника, частотой и
   путями к выходным файлам.
2. Диспетчер по `--mode` выбирает скрипт флоуграфа, переписывает часть аргументов
   (подробности — [](dispatcher.md)) и **сначала** поднимает процессы-подписчики,
   чтобы не потерять первые сообщения.
3. Флоуграф открывает SDR через SoapySDR, компенсирует доплеровский сдвиг по
   данным от `rigctld`, демодулирует сигнал и публикует результаты в три
   ZMQ-сокета на localhost.
4. Подписчики пишут кадры, аудио и IQ в файлы; водопад флоуграф пишет сам.
   Форматы — [](outputs.md).
5. По `SIGINT` диспетчер гасит флоуграф и подписчиков и завершается.

## Отношение к апстриму SatNOGS

Проект — форк
[satnogs-flowgraphs](https://gitlab.com/librespacefoundation/satnogs/satnogs-flowgraphs)
Libre Space Foundation. Вся апстримовая функциональность сохранена; последнее
слияние с апстримом — коммит `9079469`.

Изменения форка относительно апстрима:

| Изменение | Где |
|---|---|
| Декодер Geoscan (GFSK) | `satellites/geoscan_gfsk_decoder.grc`, режим `GFSK_GEOSCAN` |
| Декодер USP / Спутникс | `satellites/usp_fsk_decoder.grc`, режим `GMSK USP` |
| Режим `SSTV` переключён на `satnogs_fm.py` (аудио вместо картинки) | `flowgraph_dispatcher.py` |
| Добавлен отдельный режим `SSTV_PD120` для старого поведения | `flowgraph_dispatcher.py` |
| Кадр записывается даже при пустых метаданных | `zmq_frame_decoder_sub.py` |
| Нижняя граница децимации `max(4, …)` | флоуграфы Geoscan и USP |

Подробный разбор двух новых декодеров — [](flowgraphs/geoscan.md) и
[](flowgraphs/usp.md).

:::{note}
«Спутникс» встречается только в сообщениях коммитов. В коде, в названиях файлов
и в строке режима используется «USP» — по названию протокола Unified
SPUTNIX Protocol.
:::

## Что дальше

- Установить и собрать: [](install.md)
- Запустить вручную, без клиента: [](quickstart.md)
- Понять внутреннее устройство: [](dev/architecture.md)