# Run Config Reference

`run_config.json` is the stable runtime configuration consumed by the GUI,
Python helpers, and C++ pipeline binaries. The active file is normally
`run_config.json`; root-level `*.example.json` files are templates.

JSON does not support comments. Keep notes in docs, not inside config files.

## Top-Level Sections

```json
{
  "radar": {},
  "switches": {},
  "run": {},
  "preprocess": {},
  "gpr": {},
  "rings": {}
}
```

## `radar`

Selects the radar model and sweep settings.

```json
"radar": {
  "model": "compact_m_k209",
  "serial": "",
  "remote_host": "127.0.0.1",
  "remote_port": 50209,
  "driver_mode": "native",
  "mock_signal_hz": 5000000.0,
  "multi_device": {},
  "sweep": {}
}
```

Fields:

| Field | Meaning |
| --- | --- |
| `model` | `librevna`, `librevna_multi`, or `compact_m_k209`. |
| `serial` | LibreVNA serial. Empty means first device for single LibreVNA. For `librevna_multi`, this is the master serial. |
| `remote_host` | K209 remote server host. Used by `compact_m_k209`; ignored by LibreVNA modes. |
| `remote_port` | K209 remote server TCP port. Default is `50209`. |
| `driver_mode` | `native` for hardware, `mock` for supported synthetic LibreVNA modes. K209 requires `native`. |
| `mock_signal_hz` | Existing LibreVNA mock signal parameter used by C++ mock acquisition. |
| `multi_device` | Extra settings for `librevna_multi`. |
| `sweep` | Frequency, point count, IFBW, and power settings. |

### `radar.sweep`

```json
"sweep": {
  "start_hz": 1000000.0,
  "stop_hz": 6000000000.0,
  "points": 201,
  "if_bandwidth_hz": 50000.0,
  "stimulus_power_dbm": -10.0
}
```

Fields:

| Field | Meaning |
| --- | --- |
| `start_hz` | Sweep start frequency in Hz. |
| `stop_hz` | Sweep stop frequency in Hz. Must be `>= start_hz`. |
| `points` | Number of frequency points. |
| `if_bandwidth_hz` | IF bandwidth in Hz. |
| `stimulus_power_dbm` | Output power in dBm. |

K209 limits reported by the tested device:

```text
frequency_hz: 9000 .. 9000000000
ifbw_hz:      1 .. 300000
power_dbm:    -55 .. +5
points:       2 .. 500001
```

### `radar.multi_device`

Used only when `radar.model == "librevna_multi"`.

```json
"multi_device": {
  "slave_serials": [
    "SLAVE_SERIAL_1",
    "SLAVE_SERIAL_2"
  ],
  "force_external_reference": true,
  "recovery_attempts": 3
}
```

Fields:

| Field | Meaning |
| --- | --- |
| `slave_serials` | Exactly two slave LibreVNA serials. |
| `force_external_reference` | Configure the synchronized external reference path. |
| `recovery_attempts` | Reopen/retry attempts after native multi-device acquisition errors. |

## `switches`

Two RF switch sections are used:

```json
"switches": {
  "port1": {},
  "port2": {}
}
```

By convention in the C++ pipeline:

```text
port1 -> output switch
port2 -> input switch
```

Switch fields:

| Field | Meaning |
| --- | --- |
| `name` | Human-readable switch name. |
| `driver_mode` | `native` for GPIO, `mock` to avoid GPIO access. |
| `driver` | `h7992` or `hmc349a`. |
| `radar_port` | Physical radar port mapping, must be unique and either `1` or `2`. |
| `positions` | Number of switch positions. |
| `default_position` | Position selected on open. Zero-based. |
| `gpio_chip` | Linux GPIO chip path, usually `/dev/gpiochip0`. |
| `pin_a` | First GPIO control pin. |
| `pin_b` | Second GPIO control pin for `h7992`. |
| `invert_logic` | Logic inversion for supported switch drivers. |

Use mock switches on a laptop without GPIO:

```json
"driver_mode": "mock"
```

## `run`

Runtime behavior and combo selection.

```json
"run": {
  "settling_ms": 0,
  "idle_sleep_ms": 2,
  "continuous": true,
  "processing_live_config_path": "python_app/runtime/processing_live.json",
  "locator_server": {},
  "combos": [
    {"input": 0, "output": 0}
  ]
}
```

Fields:

| Field | Meaning |
| --- | --- |
| `settling_ms` | Delay after switching before measuring. |
| `idle_sleep_ms` | Sleep between continuous collections. |
| `continuous` | `true` loops until stopped; `false` captures one collection and exits. |
| `processing_live_config_path` | Runtime path used by processing live settings. |
| `locator_server` | Embedded TCP server settings for publishing locator results. |
| `combos` | Zero-based switch combinations to acquire. |

`combos` entries use input/output switch positions:

```json
{"input": 2, "output": 1}
```

For `librevna_multi`, the model constraints force the canonical virtual matrix:

```text
input:  0..3
output: 0..1
```

## `run.locator_server`

Settings for the embedded locator result TCP server.

| Field | Meaning |
| --- | --- |
| `device_id` | Device identifier in locator payloads. |
| `protocol_version` | Locator payload protocol version. |
| `host` | Bind host, commonly `0.0.0.0`. |
| `port` | TCP port, commonly `8888`. |
| `max_payload_bytes` | Maximum result payload size. |
| `client_queue_size` | Per-client queue size. |
| `logger_name` | Logger name used by the service. |

## `preprocess`

Names or bundle paths for calibration/reference assets used by preprocessing.

```json
"preprocess": {
  "s21": {
    "calibration": {"set_name": "", "bundle_path": ""},
    "reference": {"set_name": "", "bundle_path": ""}
  },
  "s11": {
    "calibration": {
      "open": {"set_name": "", "bundle_path": ""},
      "short": {"set_name": "", "bundle_path": ""},
      "load": {"set_name": "", "bundle_path": ""}
    },
    "reference": {"set_name": "", "bundle_path": ""}
  },
  "notch": {
    "enabled": true,
    "bands_hz": [],
    "taper_width_hz": 40000000.0,
    "taper_type": "cosine"
  }
}
```

`set_name` selects a stored set for the active radar key. `bundle_path` can
point to an exported bundle. Empty values mean no asset is selected.

`notch.bands_hz` is a list of `[low_hz, high_hz]` ranges. `taper_type` is
`cosine` or `hard`.

## `gpr`

GPR geometry and processing configuration.

```json
"gpr": {
  "relative_permittivity": 1.0,
  "tx_geometry": [
    {"output_pos": 0, "x_m": 0.905}
  ],
  "rx_geometry": [
    {"input_pos": 0, "x_m": -0.18}
  ]
}
```

Fields:

| Field | Meaning |
| --- | --- |
| `relative_permittivity` | Medium relative permittivity used for propagation speed. |
| `tx_geometry` | Transmitter positions keyed by output switch position. |
| `rx_geometry` | Receiver positions keyed by input switch position. |

Geometry positions must match configured switch positions. For example, an
`output_pos` of `1` requires the output switch to have at least 2 positions.

## `rings`

Shared-memory ring endpoints used by native processes.

```json
"rings": {
  "raw": {"name": "/radar_raw", "capacity": 50, "slot_size_bytes": 2097152},
  "raw_tap": {"name": "/radar_raw_tap", "capacity": 50, "slot_size_bytes": 2097152},
  "preprocessed": {"name": "/radar_preprocessed", "capacity": 50, "slot_size_bytes": 2097152},
  "preprocessed_tap": {"name": "/radar_preprocessed_tap", "capacity": 50, "slot_size_bytes": 2097152},
  "results": {"name": "/radar_results", "capacity": 50, "slot_size_bytes": 2097152}
}
```

Fields:

| Field | Meaning |
| --- | --- |
| `name` | POSIX shared-memory object name. |
| `capacity` | Number of slots. |
| `slot_size_bytes` | Maximum serialized payload size per slot. |

Use unique ring names for parallel tests to avoid collisions with a running GUI
session.

## Minimal Model Examples

Single LibreVNA:

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

Multi-device LibreVNA:

```json
"radar": {
  "model": "librevna_multi",
  "serial": "MASTER_SERIAL",
  "driver_mode": "native",
  "multi_device": {
    "slave_serials": ["SLAVE_1", "SLAVE_2"],
    "force_external_reference": true,
    "recovery_attempts": 3
  }
}
```

Compact-M K209 via remote server:

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