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:

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. For run_config.json fields, see docs/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:

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:

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:

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:

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:

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:

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

For unattended runs, S2VNA also supports hiding the UI:

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

Verify that the server is listening:

ss -ltnp | grep 4880

The local VISA resource is:

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:

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:

"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:

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:

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:

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

Run it against the local S2VNA HiSLIP server:

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:

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

The reported points_per_s is:

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:

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:

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