PLFM_RADAR/CONTRIBUTING.md

Contributing to PLFM_RADAR (AERIS-10)

Thanks for your interest in the project! This guide covers the basics for getting a change reviewed and merged.

Getting started

1. Fork the repository and create a topic branch from develop.
2. Keep generated outputs (Vivado projects, bitstreams, build logs) out of version control — the .gitignore already covers most of these.

Repository layout

Path	Contents
4_Schematics and Boards Layout/	KiCad schematics, Gerbers, BOM/CPL
9_Firmware/9_2_FPGA/	Verilog RTL, constraints, testbenches, build scripts
9_Firmware/9_2_FPGA/formal/	SymbiYosys formal-verification wrappers
9_Firmware/9_2_FPGA/scripts/	Vivado TCL build & debug scripts
9_Firmware/9_3_GUI/	Python radar dashboard (Tkinter + matplotlib)
docs/	GitHub Pages documentation site

Before submitting a pull request

• Python — verify syntax: python3 -m py_compile <file>
• Verilog — if you have Vivado, run the relevant build*.tcl; if not, note which scripts your change affects
• Whitespace — git diff --check should be clean
• Keep PRs focused: one logical change per PR is easier to review
• Run the regression tests (see below)

Running regression tests

After any change, run the relevant test suites to verify nothing is broken. All commands assume you are at the repository root.

Prerequisites

Tool	Used by	Install
Icarus Verilog (iverilog)	FPGA regression	brew install icarus-verilog / apt install iverilog
Python 3.8+	GUI tests, co-sim	Usually pre-installed
GNU Make	MCU tests	Usually pre-installed
SymbiYosys (sby)	Formal verification	Optional — see SymbiYosys docs

FPGA regression (RTL lint + unit/integration/signal-processing tests)

cd 9_Firmware/9_2_FPGA
bash run_regression.sh

This runs four phases:

Phase	What it checks
0 — Lint	iverilog -Wall on all production RTL + static regex checks
1 — Changed Modules	Unit tests for individual blocks (CIC, Doppler, CFAR, etc.)
2 — Integration	DDC chain, receiver golden-compare, system-top, end-to-end
3 — Signal Processing	FFT engine, NCO, FIR, matched filter chain
4 — Infrastructure	CDC modules, edge detector, USB interface, range-bin decimator, mode controller

All tests must pass (exit code 0). Advisory lint warnings (e.g., case without default) are non-blocking.

MCU unit tests

cd 9_Firmware/9_1_Microcontroller/tests
make clean && make all

Runs 20 C-based unit tests covering safety, bug-fix, and gap-3 tests. Every test binary must exit 0.

GUI / dashboard tests

cd 9_Firmware/9_3_GUI
python3 -m pytest test_GUI_V65_Tk.py -v
# or without pytest:
python3 -m unittest test_GUI_V65_Tk -v

57+ protocol and rendering tests. The test_record_and_stop test requires h5py and will be skipped if it is not installed.

Co-simulation (Python vs RTL golden comparison)

Run from the co-sim directory after a successful FPGA regression (the regression generates the RTL CSV outputs that the co-sim scripts compare against):

cd 9_Firmware/9_2_FPGA/tb/cosim

# Validate all .mem files (twiddles, chirp ROMs, addressing)
python3 validate_mem_files.py

# DDC chain: RTL vs Python model (5 scenarios)
python3 compare.py dc
python3 compare.py single_target
python3 compare.py multi_target
python3 compare.py noise_only
python3 compare.py sine_1mhz

# Doppler processor: RTL vs golden reference
python3 compare_doppler.py stationary

# Matched filter: RTL vs Python model (4 scenarios)
python3 compare_mf.py all

Each script prints PASS/FAIL per scenario and exits non-zero on failure.

Formal verification (optional)

Requires SymbiYosys (sby), Yosys, and a solver (z3 or boolector):

cd 9_Firmware/9_2_FPGA/formal
sby -f fv_doppler_processor.sby
sby -f fv_radar_mode_controller.sby

Quick checklist

Before pushing, confirm:

1. bash run_regression.sh — all phases pass
2. make all (MCU tests) — 20/20 pass
3. python3 -m unittest test_GUI_V65_Tk -v — all pass
4. python3 validate_mem_files.py — all checks pass
5. python3 compare.py dc && python3 compare_doppler.py stationary && python3 compare_mf.py all
6. git diff --check — no whitespace issues

Areas where help is especially welcome

See the list in README.md.

Questions?

Open a GitHub issue — that way the discussion is visible to everyone.