Skip to content
momenticsPublic

About

PyVNA: Multi-protocol Python library for NanoVNA V1/V2/LiteVNA, derived from GoVNA for high performance & secure server-side applications. Supports auto-detection, robust device pooling, and comprehensive data handling.

Topics

Resources

Stars

10 stars

Watchers

0 watching

Forks

Latest commit

 

History

16 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

PyVNA

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)

Requirements

  • 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

Install

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 toolchain

Editable development checkout:

pip install -e ".[server,test,dev]"

Quickstart

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()

NanoVNA-X ADC Dumps

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.

Calibration (SOL)

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 model

The 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.

HTTP server

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 -> Touchstone
  • GET /metrics -> Prometheus text format

The server binds to loopback by default; put it behind an authenticated reverse proxy for network use.

Project layout

  • pyvna/__init__.py — public API exports and package version
  • pyvna/errors.py — exception hierarchy rooted at PyVNAError
  • pyvna/models.py — SweepConfig, VNAData; Touchstone RI export, VSWR
  • pyvna/driver_base.py — shared driver behaviour: bounded I/O discipline
  • pyvna/driver.py — Driver protocol, probe factory, VNAPool
  • pyvna/driver_v1.py — NanoVNA V1 line-based text protocol
  • pyvna/driver_v2.py — NanoVNA V2 / LiteVNA binary register protocol
  • pyvna/driver_x.py — NanoVNA-X ChibiOS shell protocol (USB CDC serial)
  • pyvna/calibration.py — SOL calibration: standards, plans, profiles, error terms
  • pyvna/vna.py — high-level VNA facade: sweep, scan, calibration
  • pyvna/util/serial_port.py — serial port abstraction and path validation
  • pyvna/server/main.py — example FastAPI server: Touchstone scans + Prometheus metrics
  • tests/ — unit test suite with mock ports and fake devices

License

MIT (see LICENSE)

About

PyVNA: Multi-protocol Python library for NanoVNA V1/V2/LiteVNA, derived from GoVNA for high performance & secure server-side applications. Supports auto-detection, robust device pooling, and comprehensive data handling.

Topics

Resources

Stars

10 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages