radar_system/docs/operation_modes.md

Operation Modes

The active radar backend is selected manually in JSON by radar.model. The GUI does not expose a model selector.

Available models:

librevna
librevna_multi
compact_m_k209

Example configs in the repository root:

run_config_librevna.example.json
run_config_librevna_multi.example.json
run_config_compact_m_k209.example.json
run_config_compact_m_k209_local_mock_switches.example.json
run_config_simulator.example.json

Common Commands

Build native binaries:

cd /path/to/radar_system
make

Run the GUI:

.venv/bin/python -m python_app.gui.main

Run a single acquisition producer manually:

build/bin/sweep_orchestrator --config run_config.json

The GUI process supervisor starts the correct producer automatically:

• librevna -> build/bin/sweep_orchestrator
• compact_m_k209 -> build/bin/sweep_orchestrator
• librevna_multi -> python_app.scripts.multi_device_raw_producer

Pure Simulator

Use run_config_simulator.example.json to run the full GUI pipeline without radar hardware or GPIO. It uses the single-LibreVNA mock producer, mock switches, and the synthetic smoke_cal / smoke_ref preprocessing sets stored under python_app/data.

Typical local check:

cd /path/to/radar_system
make
.venv/bin/python -m python_app.gui.main

Then load run_config_simulator.example.json in the GUI and press Start.

Single LibreVNA

Use this mode when one LibreVNA is connected directly over USB to the machine running the project.

Config:

"radar": {
  "model": "librevna",
  "serial": "",
  "driver_mode": "native"
}

Notes:

• Empty serial means use the first compatible LibreVNA found.
• Set serial when multiple LibreVNAs are connected.
• driver_mode: "native" uses the direct USB LibreVNA driver.
• driver_mode: "mock" generates synthetic radar data for UI/development.
• Switch GPIO is controlled by the same machine unless switch driver_mode is set to mock.

Typical local check without GPIO:

cp run_config_librevna.example.json /tmp/librevna_mock_switches.json
# edit both switches to driver_mode="mock" if needed
build/bin/sweep_orchestrator --config /tmp/librevna_mock_switches.json

LibreVNA Multi-Device

Use this mode for one master LibreVNA and two slave LibreVNAs. This mode does not use physical RF switch GPIO in the acquisition producer. It exposes a fixed virtual matrix:

inputs:  0..3
outputs: 0..1
combos:  8

Config:

"radar": {
  "model": "librevna_multi",
  "serial": "MASTER_SERIAL",
  "driver_mode": "native",
  "multi_device": {
    "slave_serials": [
      "SLAVE_SERIAL_1",
      "SLAVE_SERIAL_2"
    ],
    "force_external_reference": true,
    "recovery_attempts": 3
  }
}

Notes:

• Exactly two slave serials are required.
• force_external_reference configures the synchronized reference workflow.
• recovery_attempts controls reopen/retry attempts after native acquisition errors.
• The Python producer is selected automatically by the GUI. Manual raw-producer run:

.venv/bin/python -m python_app.scripts.multi_device_raw_producer \
  --config run_config_librevna_multi.example.json

Compact-M K209 On The Same Computer

Use this for local development on the x86_64 computer that runs S2VNA and has the K209 connected over USB-C. GPIO can be disabled with mock switches.

1. Start S2VNA and enable HiSLIP on port 4880.

2. Start the local project K209 server:

.venv/bin/python -m python_app.scripts.k209_remote_server \
  --host 127.0.0.1 \
  --port 50209

3. In another terminal, smoke-test the server:

.venv/bin/python -m python_app.scripts.k209_remote_smoke_test \
  --host 127.0.0.1 \
  --port 50209

4. Run one acquisition with mock switches:

build/bin/sweep_orchestrator \
  --config run_config_compact_m_k209_local_mock_switches.example.json

This mode is useful on a laptop because it avoids GPIO dependencies.

Compact-M K209 With Raspberry Pi GPIO

Use this for the real K209 + Raspberry Pi setup:

K209 --USB-C--> x86_64 computer running S2VNA
x86_64 computer --Ethernet--> Raspberry Pi 5
Raspberry Pi 5 --GPIO--> RF switches

On the x86_64 computer:

cd /path/to/radar_system
.venv/bin/python -m python_app.scripts.k209_remote_server \
  --host 0.0.0.0 \
  --port 50209

On the Raspberry Pi, set radar.remote_host to the Ethernet IP address of the x86_64 computer:

"radar": {
  "model": "compact_m_k209",
  "remote_host": "192.168.1.10",
  "remote_port": 50209,
  "driver_mode": "native"
}

Then run the GUI or producer on the Raspberry Pi:

.venv/bin/python -m python_app.gui.main

For a command-line connection check from the Raspberry Pi:

.venv/bin/python -m python_app.scripts.k209_remote_smoke_test \
  --host 192.168.1.10 \
  --port 50209

The Raspberry Pi does not need S2VNA or NI-VISA in this remote mode.

K209 Remote Performance

The remote K209 path keeps one persistent TCP connection open. Configuration sends sweep settings once and receives the frequency axis once. Each sweep then sends one command byte and receives only binary S11 and S21 float32 arrays.

Use wired Ethernet. Wi-Fi works for tests but adds jitter.