Добавление флоуграфа и режима¶

Рецепт на примере нового декодера спутника. Ни один из шагов не выполняется автоматически: списки в CMake явные, таблицы режимов — руками.

1. Создать `.grc`¶

Отправная точка — ближайший по смыслу существующий декодер, а не пустой лист:

Задача	С чего копировать
ЧМн с фреймингом AX.25	`generic/fsk_ax25.grc`
ЧМн с дефреймером gr-satellites	`satellites/geoscan_gfsk_decoder.grc`
Фазовая манипуляция	`generic/bpsk.grc`
Только аудио	`generic/fm.grc`
Минимальный каркас	`generic/example_flowgraph.grc`

Положить в satellites/ (декодер конкретного аппарата) или generic/ (модуляция или протокол общего назначения).

Обязательное при копировании:

поменять id на satnogs_<имя файла> — по нему называется выходной скрипт;
сохранить общий набор параметров и фрагмент rig_pathname;
сохранить три ответвления ZMQ, водопад и UDP-сток.

Всё это подробно — в Соглашения в .grc.

2. Внести файл в CMake¶

set(flowgraphs
    …
    my_decoder.grc
)

satellites/CMakeLists.txt или generic/CMakeLists.txt. Списки явные, не по маске — без этой строки файл не соберётся и никакой ошибки не будет.

Проверить, что цель появилась:

cd build && cmake .. && make my_decoder

3. Зарегистрировать скрипт и режим¶

В flowgraph_dispatcher/flowgraph_dispatcher.py — две таблицы.

SATNOGS_FLOWGRAPH_SCRIPTS = {
    # … существующие режимы …
    'MY_MODE': 'satnogs_my_decoder.py',
}

SATNOGS_FLOWGRAPH_MODES = {
    # … существующие режимы …
    'MY_MODE': {
        'script_name': SATNOGS_FLOWGRAPH_SCRIPTS['MY_MODE'],
        'has_baudrate': True,
        'has_framing': False,
        'outputs_frames': True,
    },
}

Что означают флаги:

has_baudrate: принимать --baud и передавать его как --baudrate. Если False, значение клиента отбрасывается с предупреждением в stderr.
has_framing: диспетчер сам подставит --framing из ключа framing того же словаря (добавьте его, если ставите True). Значение клиента отбрасывается всегда, поэтому при False во флоуграфе параметра framing быть не должно.
outputs_frames: поднять подписчика кадров. Ставьте True, только если во флоуграфе действительно есть zeromq_pub_msg_sink, иначе процесс будет висеть впустую.

Строка режима — это то, что пришлёт soniks-client-new; согласуйте её с сетью. Пробелы допустимы (GMSK USP), но потребуют кавычек в командной строке.

4. Новый параметр — в две стороны¶

Если флоуграфу нужен параметр, которого нет в общем наборе, недостаточно объявить его в .grc. Добавьте соответствующий аргумент в client_argument_parser():

parser.add_argument('--frame-size', type=int, help='Set frame size in bytes')

Имена обязаны совпадать: --frame-size ↔ блок parameter с именем frame_size. Иначе либо флоуграф завершится с кодом 2 на неизвестном аргументе, либо тихо возьмёт значение по умолчанию — то и другое ловит tests/test_dispatcher.py, см. Контракт 2: имена аргументов.

Если параметр нужен только одному режиму и не приходит от клиента, его можно подставлять в конструкторе диспетчера — так сделано для GFSK Pkst (frame-size=192).

5. Собрать и проверить¶

Сначала тесты — они не требуют ни GNU Radio, ни приёмника и сразу скажут, если .grc разошёлся с CMake, диспетчером или соглашениями по портам:

python3 tests/test_flowgraphs.py
python3 tests/test_dispatcher.py
flake8 flowgraph_dispatcher tests

Затем сборка и прогон:

cd build && cmake .. && make && sudo make install

# набор параметров сгенерированного скрипта
satnogs_my_decoder.py --help

# прогон целиком, через диспетчер
mkdir -p /tmp/.satnogs/data
rigctld -m 1 &
flowgraph_dispatcher --mode MY_MODE --baud 9600 \
    --soapy-rx-device=driver=rtlsdr --rx-freq=435000000 \
    --file-path=/tmp/.satnogs/data/audio.ogg \
    --decoded-data-file-path=/tmp/.satnogs/data/data

Без эфира сигнал можно подать по петле генераторами из test_flowgraphs/ или скормить ранее записанный IQ-файл.

Само дерево процессов — подписчики, разведение по портам, код возврата и завершение по сигналу — проверяется без приёмника и без gr-satnogs:

python3 tests/e2e_check.py

Скрипт подставляет вместо флоуграфа заглушку, публикующую в те же три порта, и поднимает два диспетчера с разными --zmq-base-port. Нужны pmt из GNU Radio, pyzmq, numpy и soundfile — поэтому в CI он идёт в джобе flowgraphs, а не в test: python:3.11-slim этого не даёт, образ GNU Radio даёт. На станции с реальными флоуграфами те же проверки прогоняются по установленным скриптам: E2E_FLOWGRAPH_BIN=/usr/bin python3 tests/e2e_check.py.

6. Обновить документацию¶

Изменение поведения без правки документации не принимается. Что затрагивается:

Что сделали	Что править
новый `.grc`	Справочник флоуграфов — сводная таблица; плюс разбор в `generic.md`, `satellites.md` или на отдельной странице
новый режим	Справочник режимов — таблица режимов
новый аргумент	flowgraph_dispatcher — таблица аргументов
новый формат выхода	Выходные данные
новый инвариант `.grc`	`tests/test_flowgraphs.py`
новая зависимость	Установка и сборка и `debian/control`

7. Закоммитить¶

Требования CI — в Как вносить изменения. Коротко: атомарные коммиты, императивный заголовок не длиннее 50 символов, обязательный Signed-off-by:. Никаких бинарников и сгенерированных .py.

Разумное разбиение: отдельный коммит на .grc вместе со строкой в CMake, отдельный — на регистрацию режима в диспетчере, отдельный — на документацию.