radar_system/docs/k209_setup.md

# Compact-M K209 / S2VNA Setup

This project controls the Compact-M K209 through the S2VNA SCPI server.
The production path is:

```text
K209 --USB-C--> S2VNA --HiSLIP/VISA--> radar_system
```

For complete run-mode instructions, including what runs on the x86_64 S2VNA
computer and what runs on Raspberry Pi, see
[`docs/operation_modes.md`](operation_modes.md). For `run_config.json` fields,
see [`docs/run_config.md`](run_config.md).

There is no direct USB driver for K209 in this project. Do not use mock
transports, socket fallbacks, or `pyvisa-py` for the K209 path. The required
transport dependency is an IVI/Vendor VISA implementation that provides both
`visa.h` and `libvisa.so`.

For maximum throughput the driver uses:

- HiSLIP, not TCP Socket.
- A persistent VISA session.
- Binary `FORM:DATA REAL32`.
- Little-endian `FORM:BORD SWAP`.
- One-time sweep configuration outside the acquisition loop.
- Cached frequency axis after configuration, so repeated acquisition reads only
  the complex traces.
- Point delay forced to `0` and sweep averaging forced `OFF`.
- The acquisition loop sends one synchronized SCPI message:
  `TRIG:SING;*OPC?;:SENS:DATA:CORR? S11;:SENS:DATA:CORR? S21`.
  This keeps the trigger state valid while avoiding separate round trips for
  `*OPC?`, `S11`, and `S21`.

Do not remove the inline `*OPC?` from the hot path. On the tested K209/S2VNA
setup, `TRIG:SING` followed immediately by data queries can return data but
queues SCPI error `-211,"Trigger system is not in the trigger wait state"`.

## Required Components

Install these on the machine that runs the K209 smoke tests or acquisition
process:

1. S2VNA from Planar.
   - On Linux the S2VNA manual describes the AppImage package
     `S2VNA_X.X.X_x86_64.AppImage`.
   - The K209 is connected to this S2VNA instance over USB-C.

2. IVI VISA runtime and development files.
   - Must provide `visa.h`.
   - Must provide `libvisa.so`.
   - Must support TCPIP HiSLIP resources.
   - Suitable implementations include NI-VISA or Keysight IO Libraries Suite.

3. Project Python environment.
   - Use the repository virtual environment, not system Python.
   - Install `requirements.txt` into `.venv`.

4. Native build dependencies.
   - C++20 compiler.
   - `make`.
   - `libusb-1.0` development files for the existing LibreVNA build.

## Ubuntu x86_64

Install base packages:

```bash
sudo apt update
sudo apt install build-essential make pkg-config python3-venv python3-pip libusb-1.0-0-dev
```

Create or update the project virtual environment:

```bash
cd /home/europa/Documents/radar_system
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
```

Install an IVI VISA implementation. For NI-VISA, install the NI Linux package
repository from NI, then install the `ni-visa` package with the system package
manager. For Keysight, install Keysight IO Libraries Suite for Linux with VISA
support enabled.

Do not use Ubuntu's `libvisa-dev` / `libvisa0` packages for the K209 production
path. Those packages come from `librevisa` and are not the vendor IVI VISA stack
used for high-speed HiSLIP operation.

After installation, verify that the system exposes the required C and runtime
files:

```bash
ldconfig -p | grep libvisa
find /usr /opt -name visa.h -o -name libvisa.so 2>/dev/null
.venv/bin/pyvisa-info
```

`pyvisa-info` must show the `ivi` backend with a found binary library.

If `visa.h` or `libvisa.so` is installed outside the default compiler/linker
paths, pass the paths explicitly:

```bash
make build/bin/k209_smoke_test \
  VISA_CXXFLAGS='-I/path/to/visa/include' \
  VISA_LDFLAGS='-pthread -lrt -L/path/to/visa/lib -lvisa'
```

## S2VNA HiSLIP Server

Start S2VNA with the K209 connected over USB-C. Enable HiSLIP server on port
`4880`. This can be done from the S2VNA UI:

```text
System -> Settings -> Remote control network settings -> HiSLIP server -> On
System -> Settings -> Remote control network settings -> HiSLIP port -> 4880
```

The S2VNA command line can also enable the server:

```bash
./S2VNA_X.X.X_x86_64.AppImage /HislipServer:on /HislipPort:4880
```

For unattended runs, S2VNA also supports hiding the UI:

```bash
./S2VNA_X.X.X_x86_64.AppImage /HislipServer:on /HislipPort:4880 /visible:off
```

Verify that the server is listening:

```bash
ss -ltnp | grep 4880
```

The local VISA resource is:

```text
TCPIP0::127.0.0.1::hislip0,4880::INSTR
```

If S2VNA runs on another machine, replace `127.0.0.1` with that machine's IP
address.

## Remote Raspberry Pi Mode

For Raspberry Pi runs, keep S2VNA and NI-VISA on the x86_64 computer connected
to the K209, and run only the project pipeline/GPIO on the Raspberry Pi.

On the x86_64 computer with S2VNA running:

```bash
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 the K209 config to the server address:

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

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

## Python Smoke Test

Use the project virtual environment:

```bash
cd /home/europa/Documents/radar_system
.venv/bin/python -m python_app.scripts.k209_smoke_test \
  --resource 'TCPIP0::127.0.0.1::hislip0,4880::INSTR' \
  --visa-library '@ivi' \
  --start-hz 10000000 \
  --stop-hz 100000000 \
  --points 11 \
  --ifbw-hz 10000 \
  --power-dbm -20 \
  --no-preset
```

Expected result:

```text
K209 IDN: Planar, K209, ...
K209 sweep OK: points=11, first_hz=10000000.000, last_hz=100000000.000, ...
```

Use `--no-preset` for the first smoke test to avoid resetting the current S2VNA
session. Remove it when testing the full driver setup path.

## C++ Smoke Test

Build the C++ K209 smoke binary:

```bash
cd /home/europa/Documents/radar_system
make build/bin/k209_smoke_test
```

Run it against the local S2VNA HiSLIP server:

```bash
build/bin/k209_smoke_test \
  --resource 'TCPIP0::127.0.0.1::hislip0,4880::INSTR' \
  --start-hz 10000000 \
  --stop-hz 100000000 \
  --points 11 \
  --ifbw-hz 10000 \
  --power-dbm -20 \
  --no-preset
```

If the build fails with `fatal error: visa.h: No such file or directory`, the
IVI VISA development headers are not installed or are not visible to the
compiler. If linking fails with `cannot find -lvisa`, the IVI VISA runtime or
linker path is not installed correctly.

## Python Sweep Benchmark

Use this script to measure hot-loop sweep throughput for a selected sweep
configuration. It keeps one VISA session open, configures the sweep once, caches
the frequency axis once, then times repeated synchronized trigger/read cycles
for binary `S11` and `S21` arrays.

Edit the configuration constants at the top of
`python_app/scripts/k209_sweep_benchmark.py`, then run:

```bash
cd /home/europa/Documents/radar_system
.venv/bin/python -m python_app.scripts.k209_sweep_benchmark
```

The reported `points_per_s` is:

```text
timed_sweeps * points / total_timed_seconds
```

Set `INCLUDE_RESULT_CONVERSION = True` only when you want to include Python
`SweepResult` construction overhead. Keep it `False` when measuring the
device/transport hot path.

## K209 Limits

The connected K209 reports these limits through SCPI service/capability
queries:

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

The S2VNA manual specifies the IFBW range with 1/3-decade spacing.
`SENS:BAND` accepts values in the 1, 1.5, 2, 3, 5, 7 sequence across decades
and clamps out-of-range values to the nearest limit.

The manual describes metrology/dynamic-range frequency subranges such as
`9 kHz..300 kHz`, `300 kHz..2 MHz`, and `2 MHz..9 GHz`, but it does not expose a
SCPI command for manually selecting an internal RF band. S2VNA handles internal
range switching. Benchmark the exact frequency window used by the application
when sweep speed matters.

The S2VNA manual also describes a SCPI FIFO buffer mode for very high-rate
external-trigger sequences. It is not the right default for this driver stage:
the manual limits it to specific analyzer families, external/repeated trigger
workflows, one open channel, disabled display updates, and at most 3000 points
per sweep. The current K209 path therefore uses synchronized HiSLIP binary
sweeps instead of FIFO.

## Raspberry Pi OS

Raspberry Pi 5 uses ARM64/AArch64 when running 64-bit Raspberry Pi OS. The S2VNA
Linux package described in the S2VNA manual is `x86_64`, and common vendor VISA
packages are also primarily published for x86_64 Linux.

Do not assume local K209 acquisition on Raspberry Pi works until both of these
are available for ARM64:

1. S2VNA build that can run on Raspberry Pi OS ARM64 and control the K209 over
   USB-C.
2. IVI VISA implementation for ARM64 that provides `visa.h`, `libvisa.so`, and
   TCPIP HiSLIP support.

If those ARM64 dependencies are not available, run S2VNA and the acquisition
server on an Ubuntu x86_64 machine and use the remote K209 mode documented
above. In that mode, Raspberry Pi runs the project pipeline and GPIO switch
drivers, while the x86_64 machine runs S2VNA and the K209 remote server.

## Expected Hardware Test Result

With S2VNA listening on `4880` and IVI/Vendor VISA installed correctly, the
Python and C++ smoke tests should report:

```text
K209 IDN: Planar, K209, ...
K209 sweep OK: points=11, first_hz=10000000.000, last_hz=100000000.000
```