added remote k209 setup

docs/operation_modes.md

@@ -0,0 +1,213 @@
+# Operation Modes
+
+The active radar backend is selected manually in JSON by `radar.model`.
+The GUI does not expose a model selector.
+
+Available models:
+
+```text
+librevna
+librevna_multi
+compact_m_k209
+```
+
+Example configs in the repository root:
+
+```text
+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
+```
+
+## Common Commands
+
+Build native binaries:
+
+```bash
+cd /path/to/radar_system
+make
+```
+
+Run the GUI:
+
+```bash
+.venv/bin/python -m python_app.gui.main
+```
+
+Run a single acquisition producer manually:
+
+```bash
+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`
+
+## Single LibreVNA
+
+Use this mode when one LibreVNA is connected directly over USB to the machine
+running the project.
+
+Config:
+
+```json
+"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:
+
+```bash
+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:
+
+```text
+inputs:  0..3
+outputs: 0..1
+combos:  8
+```
+
+Config:
+
+```json
+"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:
+
+```bash
+.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:
+
+```bash
+.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:
+
+```bash
+.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:
+
+```bash
+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:
+
+```text
+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:
+
+```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 `radar.remote_host` to the Ethernet IP address of the
+x86_64 computer:
+
+```json
+"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:
+
+```bash
+.venv/bin/python -m python_app.gui.main
+```
+
+For a command-line connection check from the Raspberry Pi:
+
+```bash
+.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.
+