SHA256
1
1
Fork 0
GTK NanoVNA - An application to drive NanoVNA hardware built using modern GTK.
  • Rust 99.6%
  • Python 0.3%
  • Shell 0.1%
Find a file
2026-11-21 13:13:04 -05:00
crates Compare readings side by side, and analyse existing data with the wizards 2026-11-21 13:13:04 -05:00
data Firmware: install listed builds from the CLI on revision 2 2026-11-21 11:12:03 -05:00
docs Add hardware report runbook for other NanoVNA models 2026-11-19 19:03:33 -05:00
po Compare readings side by side, and analyse existing data with the wizards 2026-11-21 13:13:04 -05:00
tools Open .s1p and .s2p files from the desktop as file traces 2026-11-20 18:08:22 -05:00
.gitignore Scaffold Rust workspace with Relm4/libadwaita app and gettext i18n 2026-11-18 20:10:06 -05:00
Cargo.lock Firmware: open a NanoVNA in update mode, timed writes, USB port identity, and the groundwork for checking and installing firmware 2026-11-20 22:31:16 -05:00
Cargo.toml Firmware: open a NanoVNA in update mode, timed writes, USB port identity, and the groundwork for checking and installing firmware 2026-11-20 22:31:16 -05:00
LICENSE Scaffold Rust workspace with Relm4/libadwaita app and gettext i18n 2026-11-18 20:10:06 -05:00
README.md Firmware: install listed builds from the CLI on revision 2 2026-11-21 11:12:03 -05:00

GTKNanoVNA

A GTK4 desktop app for the NanoVNA V2 / SAA-2N vector network analyser. It is built to characterise filters, antennas, cables, adapters, components and chokes, with guided measurement wizards, readable graphs, TDR and a parts catalogue.

Own a different NanoVNA model or firmware? Help us support it: a 15-minute set of steps to collect what we need.

Build and run

Needs Rust 1.93+, GTK 4.18+, libadwaita 1.7+, libsoup 3 and gettext.

# Debian / Ubuntu
sudo apt install libgtk-4-dev libadwaita-1-dev libsoup-3.0-dev gettext

cargo run -p vna-gtk            # desktop app
cargo run -p vna-cli -- --help  # command line

To see the French UI: LANGUAGE=fr cargo run -p vna-gtk.

GNOME shows the app's name and icon (in the app switcher, dock and search) only when a desktop file matches its app ID. tools/install-dev.sh installs one for your user, along with the icon, AppStream metadata and the .gnvna, .s1p and .s2p file types, pointing at target/debug/gtknanovna (--release for target/release). tools/install-dev.sh --uninstall removes them. Under cargo run the window and About dialog find the icon in data/icons without installing.

Desktop app

Connect from the device button at the left of the header bar, set the sweep in the sidebar, then press Run (Ctrl+R) for continuous sweeps or Single (F5) for one. A Single sweep fits every chart's scale to its data; Run keeps the scales steady. Esc stops. The sidebar also holds the calibration checklist (or use Calibrate… in the main menu for a step-by-step dialog), port extension and the trace list. Click a chart to place a marker, drag it along the trace, scroll to zoom the frequency axis and double-click to reset. Click the y axis for more per division, right-click or Ctrl+click it for less; hold Shift to add or remove a division instead. Right-click or Ctrl+click a marker to delete it. The gear on each chart, or a click on a trace or marker, opens its settings on the right.

Port extension moves the reference planes to the ends of cables added after calibration. Each port has an Auto button that sweeps once and sets its delay and loss from that sweep: for port 1, leave its cable end open (or shorted); for port 2, choose how its cable is connected under Auto with (the tooltip explains both). With Barrel between cables, set port 1 first, then join the two cable ends with a barrel: port 2 gets what is left after port 1 (or the whole path while port 1 is 0, and the result says so). With Adapter on port 1, plug port 2's cable alone into an adapter on port 1 (e.g. N to SMA female); port 1's extension then counts as 0. The barrel's or adapter's own delay (a few tens of ps) ends up in port 2: subtract it if you need absolute phase. If the calibration thru had length but the kit treated it as flush, port 2's result is relative to that thru; set the kit's thru delay for absolute phase. Press a busy Auto again, or Stop, to cancel it. Auto needs a connected device that isn't busy, a sweep inside the calibrated range, a calibration that corrects S11 (port 1) or S21 (port 2), and enough points for the cable: the tooltip shows the longest cable the sweep settings allow.

A session (.gnvna) saves everything: sweep, calibration, charts, markers and traces, including memories. Open one with gtknanovna file.gnvna or from the menu. Traces can also be imported from and exported to Touchstone files. Opening .s1p or .s2p files from the file manager, or with gtknanovna lpf.s2p, imports them as traces into the open session; given with a session, they go into that session once it opens.

At start, a bar over the charts offers to reopen the last session and to load the last calibration (with its kind, device and age). The last calibration is kept automatically in the config folder (last-cal.json) whenever you measure, load or edit one, saved or not (opening a session doesn't replace it); loading it also brings back the sweep settings it was measured with.

Without hardware, GTKNANOVNA_DEMO=1 adds a simulated device to the connect menu, with a filter, an antenna or the calibration standards on its ports. GTKNANOVNA_DEMO=auto connects it and sweeps once at start. cargo run -p vna-session --example demo_session -- demo.gnvna writes a calibrated filter session to look at.

Command line

gtknanovna-cli list                                    # USB serial ports, NanoVNA marked
gtknanovna-cli probe                                   # model and firmware, changes nothing
gtknanovna-cli firmware list [--all]                   # known firmware builds, offline
gtknanovna-cli firmware update <build> --file fw.bin   # install a listed build
gtknanovna-cli sweep --start 1M --stop 30M --points 201 --samples 2 -o dut.s2p
gtknanovna-cli --mock r=100 sweep --start 1M --stop 30M   # no hardware needed

sweep writes .s1p, .s2p, .csv, or .json (a raw recording you can replay with --mock file.json).

Calibration

gtknanovna-cli cal --start 50k --stop 3G --points 201 -o cal.json   # walks you through open, short, load, thru
gtknanovna-cli sweep --start 50k --stop 3G --points 201 --cal cal.json -o filter.s2p

cal --type reflection skips the thru (S11 only). --type response uses only the thru (quick S21 normalisation). --isolation adds a loads-on-both-ports step. Standards are ideal unless you pass --kit kit.json; gtknanovna-cli kit prints a template to edit. Calibrate on the same points you'll measure on. Other grids inside the calibrated range work but are interpolated, and the tool says so.

S21 uses enhanced response: it is corrected for port 1's source match, which plain thru normalisation (as in NanoVNA-QT) isn't. A T/R VNA can't measure S22, so S11 includes the effect of port 2's load match on the DUT, as on any T/R instrument.

Full S-parameters and TDR

gtknanovna-cli flip --start 50k --stop 3G --cal cal.json -o filter.s2p   # measure, turn the DUT around, measure again
gtknanovna-cli tdr --cal cal.json --vf 0.66                              # reflections along a cable, with distances

flip gives all four S-parameters exactly, including S22, which enhanced response has to assume is matched. It needs a full calibration and checks that the result is reciprocal (as any passive DUT is). tdr lists each reflection with its distance and, in low-pass mode (the default), the impedance just past it. Low-pass needs a sweep starting near 0 Hz (the default 50 kHz is fine); --mode band-pass works on any sweep but only shows reflection size. More points reach further; a higher stop frequency resolves closer reflections. -o trace.csv saves the full trace. Ctrl-C cancels cleanly and hands the device back to its own screen. See docs/protocol.md for how the device is driven, and set GTKNANOVNA_TRACE=1 to log every byte.

Charts

gtknanovna-cli plot filter.json --cal cal.json --chart s21-db,s11-db,s11-smith,s21-gd --marker bw3 --marker 1G -o filter.pdf
gtknanovna-cli plot cable.json --cal cal.json --chart tdr --vf 0.84 --marker 1.8m -o cable.png
gtknanovna-cli plot a.s2p b.s2p --chart s21-db --log --band 144M:148M:2m -o compare.svg

plot draws recordings (.json, corrected with --cal) or Touchstone files on one page with a title block, and saves it as PNG, SVG or PDF. Each input gets its own colour. Charts are <param>-<view>, for example s11-swr, s21-phase or s11-smith, plus tdr. Markers take a frequency, a distance on TDR charts, max, min or a bandwidth like bw3. PDF and SVG pages use your locale's paper size (Letter or A4) unless you pass --paper.

Device access

The device shows up as /dev/ttyACM0. Your user needs to be in the dialout group, or you can install this udev rule as /etc/udev/rules.d/70-nanovna.rules:

SUBSYSTEM=="tty", ATTRS{idVendor}=="04b4", ATTRS{idProduct}=="0008", MODE="0660", TAG+="uaccess", ENV{ID_MM_DEVICE_IGNORE}="1"

The last part tells ModemManager to leave the port alone. Without it, ModemManager may send its own bytes to a newly plugged NanoVNA, which can make the port busy and spoil a firmware update. Run sudo udevadm control --reload and plug the NanoVNA in again after adding the rule.

Firmware updates

Firmware… in the connect menu shows what the connected NanoVNA reports, lists every known firmware build for the V2 family (older ones too), and has a built-in Update Guide that works without a device or network. Many builds report the same firmware number, so the app asks you once which one is installed: press Identify… and pick what CONFIG → VERSION shows on the NanoVNA, plus its screen size, and its SD card slot and chip if you know them ("Not sure" clears an earlier answer). The answers are kept per device in devices.json in the config folder.

The list ships with the app. Check Online for Firmware Updates (or Check Now in Preferences) downloads a newer copy of the list from git.lalonde.me once, whenever you press it. Check Automatically in Preferences does the same at most once a day while a NanoVNA is connected, skips metered networks, and is off by default. Only the list's own address over HTTPS is fetched, with a 10 second timeout and a 256 KiB size limit, through your system's proxy settings; nothing about you or your NanoVNA is sent. A downloaded list is used only when it is valid and at least as new as the one in use, and is kept in ~/.cache/gtknanovna/firmware/. The app never re-hosts firmware: download buttons open the publisher's own address in your browser.

The app doesn't install firmware itself yet: the command line does, and the Update Guide shows the steps. gtknanovna-cli firmware list [--all] shows the builds and their names. gtknanovna-cli firmware inspect <file> shows what a firmware file contains and changes nothing. gtknanovna-cli firmware update <build> --file <file> installs a listed build through update mode: it checks the file against the list and your answers from Identify…, tells you how to enter update mode, and asks you to type WRITE before it writes. Builds the list marks untested need --untested. Close the desktop app first so the port is free. If an update stops halfway, it prints the steps and the command that finish it (firmware update --resume --file <file>); firmware restart leaves update mode without installing anything. Only hardware revision 2 (V2_2 and SAA-2N) is updated.

Layout

Path What it holds
crates/vna-device Serial driver, sweep engine, mock device
crates/vna-core Calibration, RF maths, TDR, Touchstone/CSV
crates/vna-plot Cairo plot engine and PNG/SVG/PDF export
crates/vna-catalog Parts catalogue and labels
crates/vna-cli gtknanovna-cli command line
crates/vna-gtk gtknanovna desktop app
po/ Translations and the French RF glossary
tools/ Dev scripts (translations, test fixtures)

Translations

Wrap every user-facing string in gettext("..."). Then refresh the template and language files with:

tools/i18n.sh update

Translators edit po/<lang>.po. Use po/glossary-fr.md for consistent RF terms in French.

Test fixtures

Reference values for the maths tests come from scikit-rf, run on real recordings from an SAA-2N (crates/vna-device/tests/data). You only need Python to regenerate fixtures; cargo test doesn't need it.

python3 -m venv .venv && .venv/bin/pip install -r tools/requirements.txt
.venv/bin/python -I tools/fixtures/cal_skrf.py

Licence

GPL-3.0-or-later. See LICENSE.