Python driver library for low-cost vector network analyzers of the NanoVNA family. Supported protocol families:
- NanoVNA V1 — line-based text protocol
- NanoVNA V2 / LiteVNA — binary register protocol
- NanoVNA-X — ChibiOS shell protocol (USB CDC serial)
- Python 3.12+
- Optional: a VNA connected via USB-serial for hardware use
- VNA devices might use the NanoVNA-X firmware for supported devices; it is preferable
pip install pyvna # core library (drivers + calibration)
pip install "pyvna[server]" # adds the example HTTP server
pip install "pyvna[test,dev]" # adds the test and lint toolchainEditable development checkout:
pip install -e ".[server,test,dev]"from pyvna import SweepConfig, VNAPool
pool = VNAPool()
vna = pool.get("COM5") # or "/dev/ttyACM0"
print(vna.model) # identification string from the probe
vna.set_sweep(SweepConfig(start=1e6, stop=900e6, points=101))
data = vna.get_data()
print(data.to_touchstone("s11")) # standard Touchstone RI export
pool.close_all()The X driver follows the NanoVNA-X 0.9.104 reference protocol. Deferred
commands complete before the shell emits its next prompt. Binary scans use
scan ... 0x87: a little-endian uint16 mask and count followed by 20-byte
records (uint32 frequency, complex float32 S11, complex float32 S21).
Textual firmware errors, including Capture failed, are reported as
ProtocolError rather than interpreted as binary data.
reference_samples = vna.dump() # equivalent to dump(selection=1)
measurement_samples = vna.dump(selection=0)dump() returns a list of signed 16-bit ADC samples, parsed from the shell's
ASCII output. Current builds return 192 or 384 samples, with 12 samples per
line. Selection 1 is the reference ADC lane; 0 is the measurement lane,
not S11 or S21. The operation needs no SweepConfig, does not retune or select
an RF channel, and does not apply PyVNA calibration. The public API accepts
only selectors 0 and 1. V1/V2 drivers raise DeviceError for this operation.
The example server exposes the same operation as
GET /api/v1/dump?port=COM5&selection=1, returning a JSON array of integers.
X scans require 2 to the build-specific maximum number of points (101 or
401); use equal start/stop frequencies for a fixed-frequency scan. Continuous
sweep may clamp small counts to 21, but scan explicitly supplies the requested
count. Scan deadlines allow for the narrowest reference-firmware bandwidth
(10 seconds plus 1 second per point). A missing final prompt, timeout, or
malformed binary header makes the session unsafe to reuse: close and reopen
the device before another command. A complete textual error response retains
shell synchronization.
from pyvna import (
CalibrationPlan,
CalibrationStandard,
CalibrationStep,
SweepConfig,
)
plan = CalibrationPlan(
name="s11-sol",
sweep=SweepConfig(start=1e6, stop=900e6, points=101),
steps=[
CalibrationStep(CalibrationStandard.OPEN),
CalibrationStep(CalibrationStandard.SHORT),
CalibrationStep(CalibrationStandard.LOAD),
],
)
profile = vna.acquire_calibration(plan, prompt=lambda std: print("connect:", std))
data = vna.get_data() # S11 de-embedded with the three-term modelThe profile is installed only after all standards are measured and the error
terms compute and validate; a cancelled run raises CalibrationCancelledError
and installs nothing. S21 passes through as measured — see the API docstrings.
python -m pyvna.server.main [--host 127.0.0.1] [--port 8080]GET /api/v1/scan?port=COM5&start=1e6&stop=900e6&points=101&trace=s11-> TouchstoneGET /metrics-> Prometheus text format
The server binds to loopback by default; put it behind an authenticated reverse proxy for network use.
pyvna/__init__.py— public API exports and package versionpyvna/errors.py— exception hierarchy rooted atPyVNAErrorpyvna/models.py—SweepConfig,VNAData; Touchstone RI export, VSWRpyvna/driver_base.py— shared driver behaviour: bounded I/O disciplinepyvna/driver.py—Driverprotocol, probe factory,VNAPoolpyvna/driver_v1.py— NanoVNA V1 line-based text protocolpyvna/driver_v2.py— NanoVNA V2 / LiteVNA binary register protocolpyvna/driver_x.py— NanoVNA-X ChibiOS shell protocol (USB CDC serial)pyvna/calibration.py— SOL calibration: standards, plans, profiles, error termspyvna/vna.py— high-level VNA facade: sweep, scan, calibrationpyvna/util/serial_port.py— serial port abstraction and path validationpyvna/server/main.py— example FastAPI server: Touchstone scans + Prometheus metricstests/— unit test suite with mock ports and fake devices
MIT (see LICENSE)