PLFM_RADARAERIS-10开源雷达项目贡献指南分支工作流、代码规范与四层 CI 回归体系详解【免费下载链接】PLFM_RADAROpen-source, low-cost 10.5 GHz PLFM phased array RADAR system项目地址: https://gitcode.com/GitHub_Trending/pl/PLFM_RADAR本文以 CONTRIBUTING.md 为核心骨架系统讲解 10.5 GHz 相控阵雷达开源项目 PLFM_RADAR代号 AERIS-10的贡献流程从develop分支开发、供应链安全约束sfw安全前缀、Python/Verilog/C 三语种代码规范到 FPGA、MCU、GUI 与跨层契约测试四套 CI 的本地复现方法。读完本文你将能按项目标准完成一次从分支创建、代码改动、对抗性测试到 PR 合并的全流程贡献并理解仓库中 run_regression.sh、tests/Makefile、test_cross_layer_contract.py 等关键测试设施的真实工作原理。项目背景与仓库布局速览PLFM_RADAR 是一个开源、低成本的 10.5 GHz 脉冲线性调频PLFM相控阵雷达系统分 AERIS-10N3 km8×16 贴片阵与 AERIS-10X20 km32×16 介质填充波导阵两个版本硬件采用 CERN-OHL-P 许可软件采用 MIT 许可。贡献指南将仓库划分为六个与责任边界一一对应的目录路径内容对应 CI 检查4_Schematics and Boards Layout/KiCad 原理图、Gerber、BOM/CPL硬件评审无自动化 CI9_Firmware/9_1_Microcontroller/STM32 MCU 的 C/C 固件与单元测试mcu-tests9_Firmware/9_2_FPGA/Verilog RTL、约束、测试台、构建脚本fpga-regression9_Firmware/9_3_GUI/Python 雷达控制台Tkinter/PyQt6与 CLI 工具python-tests9_Firmware/tests/cross_layer/跨层系统不变量/契约测试cross-layer-testsdocs/GitHub Pages 文档站点静态站点发布理解这一布局是贡献的第一步改动落在哪个目录就决定了你需要在本地跑通哪几条回归流水线。分支工作流与版本控制纪律贡献指南明确了严格的分支策略Fork 仓库并从develop分支创建主题分支topic branch。main分支仅用于生产发布任何开发改动都不应直接推送到main。不要将生成产物纳入版本控制包括 Vivado 工程、比特流bitstream和构建日志。这些内容体积大且不可 diff会污染仓库历史。此外仓库对产物落盘位置有明确政策见 README.md 的Repository File Placement Policy小节可发布、需追踪的报告放docs/如 docs/AERIS_Simulation_Report_v2.pdf仿真生成的临时输出放5_Simulations/generated/本地、gitignoreVivado/仿真临时产物放9_Firmware/9_2_FPGA/reports/本地、gitignore可复用的 FPGA 自动化脚本放9_Firmware/9_2_FPGA/scripts/纳入追踪。严禁在仓库根目录留下任何生成物。这条纪律保证了git diff永远只包含真正有意义的代码改动。供应链安全强制项所有包安装必须带sfw前缀这是本仓库贡献规范中最具特色的硬性约束。由于供应链攻击supply chain attack风险所有包安装命令都不得裸奔执行Pythonsfw uv pip install package禁止直接使用 pipNode/JSsfw npm install packageRust/Cargosfw cargo command仓库的 pyproject.toml 也印证了这一理念运行时依赖刻意留空dependencies []GUI 依赖被拆到9_Firmware/9_3_GUI/requirements_*.txt中按需本地安装从依赖面缩小攻击面。贡献者在本地新增依赖时必须同时遵守sfw前缀约束并更新对应的 requirements 文件或依赖组配置。代码规范与工具链按语言分层CONTRIBUTING.md 为仓库中的三类语言分别指定了工具链与规范PythonGUI、脚本、测试依赖管理统一使用uv严格使用ruff做静态检查提交前必须执行uv run ruff check .测试使用pytest。pyproject.toml 中的 ruff 配置非常值得关注——它几乎是专门为LLM 生成代码的常见缺陷设计的规则集包括T20禁止遗留print()调试输出、ERA禁止注释掉的死代码、A禁止遮蔽内置名id/type/list、ARG禁止定义却从不使用的参数、BLE禁止裸except、RET禁止else后冗余 return、UP强制使用目标 Python 版本的新语法等。贡献者提交 Python 代码前应对照这些规则自查。VerilogFPGA RTLradar_system_top.v是操作码opcode、位宽、复位默认值与合法取值范围的唯一事实来源single source of truth所有其它层MCU、GUI、测试台都必须与之对齐测试台必须包含对抗性验证adversarial validation主动测试边界条件、竞态条件、意外输入序列和运行中复位reset mid-operation仿真使用iverilog。C/CMCU使用make test运行宿主机侧单元测试基于 cpputest 风格。系统级不变量System-Level Invariants任何新增代码都必须验证跨模块、跨进程、跨芯片边界的系统级不变量仍然成立——这正是仓库中 cross-layer 测试存在的理由。AI 使用政策人的责任不可让渡项目允许使用 AI 辅助编码但设定了三条硬性约束本质是把代码质量与掌控权留在维护者/提交者手中Human Accountability人类担责——提交工程师对 AI 生成代码负全责视同亲手编写每个 PR 必须能被人类理解并为自己的代码辩护Mandatory Review强制评审——不允许未经阅读就把 AI 原始输出提交上去AI 代码必须与手写代码同标准评审Full CI Before Commit提交前完整 CI——所有 AI 辅助改动必须在本地完整通过 lint、单元、回归、跨层四套 CI 后才能提交。本地复现四套测试套件CIGitHub Actions在每个 PR 上运行四个主要任务贡献者推送前必须全部在本地跑通。以下命令均可在仓库根目录执行。1. Python 与 Lintuv run ruff check . cd 9_Firmware/9_3_GUI uv run pytest test_GUI_V65_Tk.py test_v7.py -v第一行执行全仓库 ruff 静态检查规则见 pyproject.toml 的[tool.ruff]段第二、三行运行 GUI 侧的两份核心测试。以 test_v7.py 为例它覆盖 V7 模块的modelsRadarTarget/RadarSettings 数据类、processing雷达数据解析与俯仰校正、workers极坐标转地理坐标以及hardwareSTM32USB 接口等纯逻辑组件不需要 Qt 事件循环即可运行。2. FPGA 回归cd 9_Firmware/9_2_FPGA bash run_regression.shrun_regression.sh 是项目的 FPGA 回归总闸脚本本身即一份高质量的文档包含五个阶段与两个可选参数--quick跳过耗时的集成测试receiver golden、系统级测试台--skip-lint跳过 Phase 0 的 lint 检查不推荐。各阶段职责如下Phase 0 — Vivado 风格 Lint双层Layer A用iverilog -g2001 -DSIMULATION -Wall对完整生产 RTL 编译文件清单PROD_RTL列出 28 个模块从radar_system_top.v到fpga_self_test.v将警告分类为Vivado 视为错误如 part-select 越界、端口宽度不匹配与信息级警告如 timescale、悬空端口Layer B自定义正则静态检查典型如用 awk 扫描case/casex/casez块是否缺少default对应 Vivado SYNTH-6 推断锁存器警告值得注意的是ad9484_interface_400m.v因使用 Xilinx 原语IBUFDS/BUFIO/BUFG/IDDR被 iverilog 排除仿真时改用tb/ad9484_interface_400m_stub.v。Phase 1 — 变更模块单元测试CIC 抽取器、Chirp 控制器、Doppler 处理器、阈值检测器、RX 增益控制、MTI 对消器、CFAR-CA 检测器、FPGA 自检等。Phase 2 — 集成测试DDC 链NCO→CIC→FIR、Doppler 实数据协同仿真对 ADI CN0566 数据的十六进制级精确比对、Full-Chain 实数据、receiver golden 生成/比对、系统级radar_system_tb、E2E 系统测试46 项严格检查TX/RX、USB 读写、CDC、安全、复位以及-DUSB_MODE_1FT2232H 生产接口变体。Phase 3 — 信号处理单元测试FFT 引擎、400 MHz NCO、FIR 低通、匹配滤波链。Phase 4 — 基础设施单元测试CDC 模块3 变体、边沿检测器、USB 数据接口、Range Bin 抽取器、雷达模式控制器。脚本的判定逻辑也值得注意测试台显式输出[PASS]/[FAIL]标记脚本用grep -Ec ^\[PASS([^]]*)\]统计若无标记则回退检查finish|complete|done关键字仍无法判定则记为 UNKNOWN 并按失败处理——这保证了静默通过不会发生。最终FAIL0时脚本以退出码 1 终止。3. MCU 单元测试cd 9_Firmware/9_1_Microcontroller/tests make clean maketests/Makefile 构建并运行宿主机侧无需硬件的固件测试采用 mock HAL spy/recording 模式测试真实固件代码。测试按依赖关系分为六组TESTS_WITH_REAL链接真实adf4382a_manager.c mock 对象如 bug1 初始化时序、bug10 SPI CS 未翻转、bug15 htim3 悬空 externTESTS_MOCK_ONLY仅需 mock如 bug2 AD9523 双重初始化、bug7 GPIO 引脚冲突TESTS_STANDALONE纯逻辑如 bug12 PA 校准循环反转、bug13 DAC/ADC 缓冲不匹配TESTS_WITH_PLATFORM需要platform_noos_stm32.o mockbug11 平台 SPI 只发送TESTS_WITH_CXXC 侧 AGC 外环test_agc_outer_loopTESTS_GPSUM982 GPS 驱动白盒测试。Makefile 的关键机制是shim 头文件优先INCLUDES : -Ishims -I. -I../9_1_1_C_Cpp_Libraries用 tests/shims 下的轻量替身覆盖 STM32 HAL 头从而在宿主机上编译真实固件源文件。以 test_bug1_timed_sync_init_ordering.c 为例该测试验证ADF4382A_Manager_Init()必须先置initializedtrue再调用SetupTimedSync此前顺序颠倒导致同步配置被NOT_INIT静默吞掉并通过 spy 计数断言定时同步对 TX、RX 各写入一次寄存器。运行make test_bug1可单独执行该用例make test跑全部。4. 跨层契约测试uv run pytest 9_Firmware/tests/cross_layer/test_cross_layer_contract.py -v这是本仓库最具特色的测试层。test_cross_layer_contract.py 是一个用 pytest 编排的三层验证体系目标是在各层自证正确之外寻找未知 bugTier 1 — 静态契约解析在解析期直接比较 Python、Verilog、C 三种源码捕获操作码不一致、位宽错误、包常量漂移和布局 bug如status_words[0]的 37 位截断问题。文件中保留了手工转录自radar_system_top.v的GROUND_TRUTH_OPCODES如0x01→host_radar_mode2 位、0x22→host_cfar_train5 位与GROUND_TRUTH_RESET_DEFAULTS如host_detect_threshold10000、host_agc_target200任何一层与真值表不一致即判失败Tier 2 — Verilog 协同仿真用 iverilog 编译运行tb_cross_layer_ft2232h.v解析其输出的cmd_results.txt、data_packet.txt、status_packet.txt再用 Python 的RadarProtocol解析器做命令往返sent vs got 逐字节比对与 11 字节数据包、26 字节状态包的回环验证Tier 3 — C 桩执行编译stm32_settings_stub.cpp与真实RadarSettings.cpp由 Python 构造二进制设置包SET10 个字段END共 82 字节运行桩并验证逐字段解析一致同时覆盖截断包拒绝、错误起始/结束标记拒绝与边界值如system_frequency1.0e9、prf1100场景。Tier 2 还内置了对抗性自检人为翻转固件VM_I[42]的一个比特验证比较逻辑确实能捕获该错误防止未来重构绕过检测。合并前 CI 清单CONTRIBUTING.md 给出的四个 CI 任务及判据如下Job检查内容python-testsruff 干净 pytest 全绿mcu-testsmake all 退出码为 0fpga-regressionrun_regression.sh 退出码为 0cross-layer-testspytest 退出码为 0项目特有的工程要点踩坑指南CONTRIBUTING.md 明确列出几条历史踩坑总结贡献 FPGA 代码时务必遵守NO LEGACY COMPATIBILITY除非维护者明确要求不做遗留兼容——宁可破坏旧接口也不保留死分支FPGA RTL 是唯一事实来源radar_system_top.v定义的操作码、位宽、复位默认值、合法范围所有其它层必须向它对齐对抗性测试是强制项每个测试都必须主动尝试破坏代码而非只验证 happy path测试台时序纪律在(posedge clk)之后、用阻塞赋值驱动 DUT 输入之前必须加#1延迟避免仿真器时钟竞争race condition预取 FIFO 语义牢记wr_full是在DEPTH1次写入后才拉高而不是 DEPTH 次——这是 latency_buffer.v 类模块最容易写错的地方。推送前检查清单Checklist Before Push贡献者在推送前应逐项确认uv run ruff check .— 无 lint 错误uv run pytest test_GUI_V65_Tk.py test_v7.py -v— 全部通过cd 9_Firmware/9_2_FPGA bash run_regression.sh— 全部 5 阶段通过cd 9_Firmware/9_1_Microcontroller/tests make clean make— 通过uv run pytest 9_Firmware/tests/cross_layer/test_cross_layer_contract.py— 通过git diff --check— 无空白字符问题PR 指向develop分支补充验证途径形式化验证除四套 CI 外仓库在 9_Firmware/9_2_FPGA/formal 提供了基于 SymbiYosys 的形式化验证formal verification用例可作为对抗性测试的进阶补充。以 fv_radar_mode_controller.sby 为例它用 z3 引擎对radar_mode_controller.v执行 BMC深度 200与 cover深度 600两类任务从数学上穷举证明/搜索状态空间——这与 CONTRIBUTING.md 强调的对抗性验证是强制项一脉相承。总结PLFM_RADAR 的贡献流程是一条规范约束 多层验证的完整链路sfw前缀守住供应链底线三语种工具链守住代码质量四套 CI 守住回归安全radar_system_top.v单一事实来源守住跨层一致性而人类对 AI 代码全责 对抗性测试则守住了软件工程中最难量化的责任与边界意识。对于希望在 10.5 GHz 相控阵雷达方向参与开源硬件的开发者而言本文给出的命令、清单与源码级解释足以支撑你从零完成第一次合规提交。【免费下载链接】PLFM_RADAROpen-source, low-cost 10.5 GHz PLFM phased array RADAR system项目地址: https://gitcode.com/GitHub_Trending/pl/PLFM_RADAR创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考