awe/radar_system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ad2b3e555a8848e5e9c072c96fe35895cb378d04
radar_system/docs/development.md
T
Ayzen ad2b3e555a added docs
2026-10-16 18:35:02 +03:00

12 KiB
Raw Blame History

Разработка

Сборка

C++ собирается командой make из корня проекта; Eigen и nlohmann/json лежат в data_acq_and_processing/third_party/, других внешних библиотек нет.

Цель Что собирает или делает
all (по умолчанию) build/bin/data_preprocessor, build/bin/data_processor
rph_radar_collector build/bin/rph_radar_collector; в all не входит
check-native тесты C++: кадры, кольца, конфигурация, наборы, режекторный фильтр, локатор, псевдотерминал коллектора (на поддельной библиотеке L-Card)
check-sar3d 3D SAR на настоящем CUDA-бэкенде против эталона
check-gpr GPR на CPU, без видеокарты, против эталона
clean удаляет каталог сборки
Переменная По умолчанию Что задаёт
BUILD_DIR build каталог сборки. Программа запускает процессы только из build/bin/, другой каталог нужен для проверок
CUDA_ROOTS пакеты nvidia/* в .venv и /usr/local/cuda где искать nvrtc.h, cuda.h, libnvrtc
PYTHON .venv/bin/python интерпретатор для check-sar3d и check-gpr
NATIVE_SANITIZERS не задана санитайзеры для тестов C++, например address,undefined
CXX, CXXFLAGS, LDFLAGS g++, -std=c++20 -O2 …, -pthread -lrt компилятор и флаги

BUILD_DIR, CUDA_ROOTS, CXX, CXXFLAGS и LDFLAGS задаются в командной строке make, а не через окружение; PYTHON и NATIVE_SANITIZERS можно задать и переменной окружения. CXXFLAGS в командной строке заменяет весь набор флагов, вместе с -std=c++20 и отслеживанием зависимостей -MMD -MP. make сам пересобирает нужное, если изменились найденная CUDA или санитайзеры. Сборка с CUDA и без неё описана в главе Установка и запуск.

Тесты

QT_QPA_PLATFORM=offscreen .venv/bin/python -m unittest discover -s python_app/tests
make check-native
ASAN_OPTIONS=detect_leaks=0 make check-native NATIVE_SANITIZERS=address,undefined
make check-sar3d
make check-gpr
Набор Что нужно
Python, python_app/tests .venv с пакетами, QT_QPA_PLATFORM=offscreen (дисплея у тестов нет), запись в /dev/shm, псевдотерминалы, UDP на loopback. Железо не нужно
C++, make check-native g++ с C++20
3D SAR, make check-sar3d сборка с CUDA и пригодная видеокарта; без неё проверяются только предупреждение и правила рамок, остальное пропускается
GPR, make check-gpr numpy

Особые случаи:

  • test_processor_history запускает настоящий build/bin/data_processor и пропускается, если он не собран.
  • Тесты окна строят настоящее окно на временном профиле из run_config_examples/run_config_simulator.example.json и не зависят от корневого run_config.json (python_app/tests/gui_test_support.py).
  • test_deploy_scripts гоняет deploy/update.sh во временном каталоге с заглушками systemctl и make.
  • test_cart_firmware компилирует прошивку тележки на компьютере и пропускается без g++.
  • data_acq_and_processing/tests/test_backprojection.py в общий прогон не входит: его запускают make check-sar3d и make check-gpr.
  • test_documentation проверяет документацию: docs/configuration.md называет каждый ключ профиля и processing_live.json, главы называют каждую подпись окна и диалогов (жирным, кодом или заголовком), а относительные ссылки ведут на существующие файлы. Новый ключ или кнопка без описания роняет этот тест.

Внимание. Не запускайте тесты от root: созданные ими кольца в /dev/shm станут принадлежать root, и программа от обычного пользователя получит отказ в доступе.

Проверка на старой видеокарте (NVRTC 13 не компилирует под карты старее sm_75):

make check-sar3d BUILD_DIR=/tmp/radar_build_nvrtc12 CUDA_ROOTS="$HOME/.cache/radar_nvrtc12/nvidia/cuda_nvrtc $HOME/.cache/radar_nvrtc12/nvidia/cuda_runtime"

Эталоны 3D SAR и GPR

data_acq_and_processing/tests/sar3d_reference.npz и gpr_reference.npz строит генератор, который выполняет неизменённые функции ноутбука Multi_depthnorm_clean.ipynb (ячейки 1 и 5) и скрипта Horns_motion_4x4_ground.py с заменёнными параметрами. В эталоне 3D SAR десять случаев: шесть объёмов (ширина отклика, вычитание среднего предыдущих коллекций для каждого кадра апертуры, отношение к фону) и четыре сцены точечных отражателей в шуме для CLEAN с объектами и рамками. Правила рамок проверяются по одному на синтетических объектах. Архивы записывают хеши SHA-256 исходников и версии NumPy и SciPy.

Перегенерировать эталоны нужно только при правке алгоритма; ноутбук и скрипт хранятся вне репозитория:

.venv/bin/python data_acq_and_processing/tests/generate_backprojection_reference.py \
    --notebook /путь/к/Multi_depthnorm_clean.ipynb \
    --gpr-script /путь/к/Horns_motion_4x4_ground.py

Другую сборку можно проверить так: make check-sar3d BUILD_DIR=/путь/к/сборке или BACKPROJECTION_FIXTURE=/путь/к/сборке/native_tests/backprojection_fixture при запуске test_backprojection.py Sar3dTest.

Утилиты

Команда Что делает
.venv/bin/python -m python_app.scripts.rph_radar_calibrate --config <профиль> --sweeps 200 [--warmup 10] [--apply] фазовая калибровка радиофотонного радара (глава Оборудование)
.venv/bin/python -m python_app.scripts.per_point_switching_check --config <профиль> [--collections 3] [--switch-connected] проверка переключения стимула на железе; выход 0 — норма, 1 — сбой
./start.sh --producer-only --profile <профиль> только процесс сбора с выводом в терминал — для отладки железа

Правила кода

  • Обязателен только функциональный контракт: программа в правильном порядке собирает коллекции, предобрабатывает, обрабатывает и показывает результат в окне и в вебе, даёт выбрать настройки предобработки и выполнить действия пользователя. Внутреннее устройство можно менять под этот контракт.
  • Код — читаемый и без лишнего: понятные имена, без мёртвых опций и «умных» трюков.
  • Наименьшая версия Python — 3.10 (код использует dataclass(slots=True) и match).
  • .venv/bin/pyright python_app — 0 ошибок, без подавлений и расширения исключений (режим basic).
  • Нумерацию антенн и портов задаёт профиль: она уточняется по железу, менять её самостоятельно нельзя.
  • Корневой run_config.json остаётся профилем симулятора.
  • Изменив поведение, исправьте документацию в том же изменении (таблица «Где что править» в главе Устройство программы); полноту ключей и подписей проверяет test_documentation. Документ описывает, как устроено сейчас; числа перепроверяются по коду.

Прошивки

Внимание. top_master.bin и combined.vnafw — единственные копии рабочего битстрима мастера и рабочего образа; битстрим заново не воспроизводится. Не перезаписывайте их, новые сборки кладите под новыми именами.

  • VHDL — только ASCII: любой другой символ, даже длинное тире в комментарии, ломает GHDL (invalid character, even in a comment).

  • В VNA.xise закреплено Starting Placer Cost Table (1-100) Map spartan6 = 2; не сбрасывайте его в 1: ограничение MCU_MOSI OFFSET hold и в стоковой прошивке проходит с запасом всего +0,458 нс.

  • После правки FPGA прогоните тестбенч и мутационный тест — внесите ошибку и убедитесь, что тестбенч падает:

    ghdl -a --std=93 Sweep.vhd Test_Sweep.vhd && ghdl -r --std=93 Test_Sweep --assert-level=error

  • Изменение объёма логики FPGA сравнивайте по Timing Score с контрольной сборкой стоковой прошивки.

Порядок сборки прошивок — reproduce/README.md.

Git

  • Основная ветка — main.
  • Правила build* и build/ в корневом .gitignore скрывают и файлы комплекта сборки прошивок (в том числе build.sh и эталонные бинарники STM32); для них добавлены исключения, а часть файлов скрывает ещё и вложенный .gitignore LibreVNA. Добавляя файлы в device_firmware/, проверяйте git status --ignored и при необходимости git add -f.
  • В репозиторий не входят: .venv, build/, python_app/data*, python_app/runtime, ноутбуки *.ipynb, локальные инструменты разработчиков.
Reference in New Issue View Git Blame Copy Permalink