diff --git a/README.md b/README.md index 11eebb6..e427aef 100644 --- a/README.md +++ b/README.md @@ -1,29 +1,121 @@ -# radar_system +# Radar System -Radar acquisition and processing system for single LibreVNA, synchronized -multi-device LibreVNA, Compact-M K209/S2VNA, and Kamil ADC setups. +A real-time radar acquisition and imaging system for vector-network-analyzer (VNA) +and ADC front-ends. It drives the radar through a frequency sweep, calibrates and +preprocesses the measured S-parameters, runs a selectable imaging/detection +processor, and presents the live result in a desktop GUI and an in-process web +interface. The same application runs interactively on a workstation or unattended +as a headless Raspberry Pi appliance. -Start here: +## Overview -- [Operation Modes](docs/operation_modes.md): what to run on each machine for - `librevna`, `librevna_multi`, `compact_m_k209`, and `kamil_adc`. -- [Run Config Reference](docs/run_config.md): `run_config.json` fields and - example files. -- [K209 Setup](docs/k209_setup.md): S2VNA, VISA, K209 limits, smoke tests, and - Raspberry Pi remote mode details. +The system is split into a **C++ real-time pipeline** and a **Python application** +that supervises it and handles visualization and control. -Common local setup: +The pipeline runs as three independent processes connected by lock-free POSIX +shared-memory ring buffers. Each stage advances on its own, and a slow consumer +never blocks a producer — the rings are latest-wins, so a reader that falls behind +simply skips to the freshest frame: + +1. **Acquisition** — `sweep_orchestrator` (or a hardware-specific producer) + configures the radar, performs the frequency sweep, and publishes raw S11/S21 + traces. +2. **Preprocessing** — `data_preprocessor` applies through/OSL calibration, + reference subtraction, and optional frequency-domain notch filtering. +3. **Processing** — `data_processor` runs the selected processing mode and emits + results (pass-through traces, B-scan images, or GPR images with detected + objects). Detected objects are additionally broadcast to subscribers over a TCP + locator server. + +The **Python application** (`python_app`) starts and monitors the C++ binaries, +reads the result rings, renders the live view with pyqtgraph, and exposes the same +controls plus a pixel-identical live plot through an embedded web UI. + +``` + radar hardware + │ + ▼ + Acquisition ──[raw ring]──▶ Preprocessing ──[preprocessed ring]──▶ Processing ──[result ring]──▶ GUI / Web + │ + └──▶ TCP locator (detected objects) +``` + +## Supported hardware + +- **librevna** — single LibreVNA. +- **librevna_multi** — synchronized multi-device LibreVNA. +- **compact_m_k209** — Compact-M K209 / S2VNA (including Raspberry Pi remote mode). +- **sn9000** — SNVNA SN9000 over VISA (pure-Python `@py` backend). +- **kamil_adc** — external Kamil ADC acquisition process, with optional laser control. +- **mock / simulator** — driver-less mode for development without hardware. + +## Processing modes + +- **pass_through** — magnitude and phase of the selected channel for each combo. +- **bscan** — depth-versus-sweep B-scan heatmap. +- **gpr** — coherent back-projection GPR imaging with object detection. +- **legacy_gpr** — ellipse-intersection MIMO localization (point and extended/region modes). + +## Repository layout + +| Path | Contents | +| --- | --- | +| `data_acq_and_processing/` | C++ pipeline: `sweep_orchestrator/`, `preprocessing/`, `processing/` (including `locator/`), shared `common_cpp/` (config, IPC rings), and vendored `third_party/` (Eigen, nlohmann/json). | +| `python_app/` | Python application: `gui/`, `orchestration/` (process supervisor, shared-memory readers, config), `hardware_full/` (device drivers and services), `webui/`, `storage/`, `models/`, `workflows/`, `scripts/` (producers and tools), and `tests/`. | +| `run_config_examples/` | Ready-made configuration profiles, one per hardware setup. | +| `deploy/` | systemd daemon installer for Raspberry Pi appliances. | +| `build/bin/` | Compiled C++ binaries. | +| `device_firmware/`, `docs/` | Device firmware and vendor manuals. | + +## Requirements + +- Linux (POSIX shared memory; GPIO on Raspberry Pi). +- A C++20 compiler and `make` — Eigen and nlohmann/json are vendored, so no extra C++ dependencies are needed. +- Python 3.12 with a virtual environment. + +## Build and run + +From the repository root: ```bash -cd /path/to/radar_system python3 -m venv .venv .venv/bin/python -m pip install --upgrade pip .venv/bin/python -m pip install -r requirements.txt -make +make # build the C++ binaries into build/bin/ ``` -Run the GUI: +Run the desktop GUI: ```bash .venv/bin/python -m python_app.gui.main +# or, with the build step and single-instance handling: +./start.sh +``` + +`start.sh` supports `--headless` (offscreen, auto-start — for unattended Pi use), +`--kamil-adc`, `--profile PATH`, `--producer-only`, `--skip-build`, and +`--clean-shm`; see `./start.sh --help`. + +The web interface is served in-process at `http://:8080`. It mirrors the live +plot and offers Start / Stop / Capture controls and the active processor settings. + +## Configuration + +The active profile is `run_config.json`. It selects the radar model and sweep, the +switch matrix and acquisition combos, the preprocessing calibration/reference +assets, the GPR geometry, and the shared-memory ring sizes. Profiles for each +hardware setup are provided in `run_config_examples/` — copy one to +`run_config.json`, or pass it with `--profile`, to use it. + +## Deployment + +On a Raspberry Pi, `deploy/install-daemon.sh` installs a systemd service that runs +the application headless and restarts it on failure. A single-instance lock ensures +the interactive GUI and the daemon never run at the same time, since they share the +radar, the shared-memory rings, and the locator port. + +## Tests + +```bash +.venv/bin/python -m unittest discover -s python_app/tests ```