Skip to content

S1pdiff Touchstone Sweep Analysis and Baseline Comparison

github-actions[bot] edited this page Nov 15, 2026 · 1 revision

Command-line analysis and comparison of one-port NanoVNA sweep records

Part of the ULTIMATE CYBERSECURITY MASTER GUIDE ยท SDR & RF

NanoVNA Focus


โ† NanoVNA Index

๐ŸŽฏ Purpose

Provide a command-line companion for reviewing archived NanoVNA S11 sweeps.

โš™๏ธ Function

Analyze individual Touchstone files or compare a current sweep with a baseline and export the result.

๐Ÿ† Goal

Report measurement changes with the input data and comparison assumptions available for review.

๐Ÿ“‹ When To Use

  • Analyzing an exported .s1p file.
  • Comparing repeat measurements and producing a report or machine-readable output.

๐Ÿ“‹ Table Of Contents


A standalone command-line tool for NanoVNA .s1p files. Python 3.8+, standard library only โ€” no numpy, no scikit-rf, nothing to install.

Companion to the NanoVNA field guide; see 06 ยง6.10 for the workflow it's built around.


What It's For

You sweep an antenna system, export .s1p, and archive it. Months later you sweep the same system and want an objective answer to "has anything changed?"

s1pdiff gives you that answer, the numbers behind it, and an exit code you can act on in a script.


Install

chmod +x tools/s1pdiff.py

That's it. Optionally put it on your PATH:

sudo ln -s "$(pwd)/tools/s1pdiff.py" /usr/local/bin/s1pdiff

Usage

Analyse One Sweep

s1pdiff.py analyze antenna.s1p
s1pdiff.py analyze antenna.s1p --band 144 148 --at 146

Reports resonance (parabolically interpolated, so it beats your point spacing), the reactance zero-crossing separately, SWR bandwidth, worst-case SWR, and โ€” with --at โ€” the impedance at an exact frequency plus whether the element reads electrically long or short.

Resonance     : 146.0000 MHz  (VSWR 1.042:1, RL 33.80 dB)
X = 0 crossing: 146.0000 MHz (-0.0000 MHz from SWR minimum)
2:1 bandwidth: 140.0000 - 152.0000 MHz  (12.0000 MHz)  [CLIPPED by sweep edge]

At 146.0000 MHz:
  VSWR        : 1.042:1
  Impedance   : 48.00 + j0.00 ohm
  Character   : resonant (X ~ 0)

Compare Against A Baseline

s1pdiff.py diff baseline.s1p current.s1p
s1pdiff.py diff baseline.s1p current.s1p --band 902 928 --warn-db 1.5 --fail-db 3

Machine-readable Output

s1pdiff.py diff base.s1p curr.s1p --format json
s1pdiff.py diff base.s1p curr.s1p --format csv  --out sweep.csv
s1pdiff.py analyze ant.s1p        --format markdown --out report.md

The markdown output is meant to paste straight into a customer report.


Exit Codes

Code Meaning
0 OK โ€” within tolerance
1 WARN โ€” past --warn-db, resonance shift past --res-warn-pct, or SWR limit newly exceeded
2 FAIL โ€” past --fail-db
3 ERROR โ€” bad input, no frequency overlap, unreadable file

So it drops into a site-visit script or a cron job:

s1pdiff.py diff baselines/site7_2m.s1p today.s1p --format json \
    --out reports/site7_$(date +%F).json \
  || mail -s "Antenna drift: site 7" jon@pnwcomputers.com < reports/site7_$(date +%F).json

Options

Option Default Does
--band LO HI full file Restrict analysis to a frequency window (MHz)
--at MHZ โ€” Report VSWR and impedance at one exact frequency
--swr-limit S 2.0 VSWR threshold used for bandwidth figures
--format text text ยท json ยท markdown ยท csv
--out FILE stdout Write output to a file
--quiet off Suppress output, rely on exit code
--tol-db DB 1.0 Per-point deviation counted in the segment report
--warn-db DB 2.0 Deviation that triggers WARN
--fail-db DB 4.0 Deviation that triggers FAIL
--res-warn-pct PCT 0.5 Resonance shift that triggers WARN
--rl-ceiling-db DB 20.0 Return loss better than this counts as "well matched" โ€” see below

Why --rl-ceiling-db Exists

Inside a deep null, dB figures swing wildly for physically trivial differences. A 1.03:1 match reads 36 dB return loss; a 1.04:1 match reads 34 dB. Differencing those raw would flag 2 dB of "drift" on an antenna that did not meaningfully change, and every well-matched antenna in your library would throw spurious warnings.

So both sweeps have their return loss clamped at the ceiling before differencing. Anything better than 20 dB (VSWR 1.22) is simply "well matched" and contributes zero deviation. Real degradation โ€” 25 dB collapsing to 12 dB โ€” still registers at full size.

Raise it if you genuinely care about distinctions above 20 dB return loss; lower it to make the tool less twitchy on marginal installations.


File Format Support

Touchstone 1.0 one-port files:

  • Formats: RI (real/imaginary), MA (magnitude/angle), DB (dB/angle)
  • Units: Hz, kHz, MHz, GHz
  • Reference impedance read from the option line (R 50, R 75, โ€ฆ)
  • Comments (!), blank lines, and Touchstone 2.0 [Keyword] lines ignored
  • Out-of-order frequency points sorted automatically

Handles NanoVNA-Saver's # Hz S RI R 50 convention and the H4's on-device SD card exports.

75 ฮฉ systems: the tool honours the R value in the file's option line, so a correctly-written 75 ฮฉ .s1p is analysed against 75 ฮฉ. If your software exports 75 ฮฉ data with a R 50 header, the SWR figures will be wrong โ€” see 10 ยง10.5.


Interpretation Caveats

The tool sees only the S11 data it was given. It has no way to know:

  • Where the calibration plane was. A sweep taken at the shack end of a lossy feedline has that loss baked in, and the tool will happily report a flattering match.
  • Whether the two sweeps are comparable. A comparison is only meaningful if the calibration plane, cables, adapters, and antenna geometry match the baseline run. Record them โ€” that's what the worksheet in 11 is for.
  • Anything about gain, efficiency, pattern, or power handling. See 12 ยง12.4.

Resonance is reported two ways โ€” minimum-VSWR frequency and reactance zero-crossing โ€” because they are not always the same frequency, and the gap between them is itself diagnostic.


Tests

bash testdata/run_tests.sh

14 checks covering both Touchstone formats, both unit conventions, all four output formats, the three verdict levels, and the error paths. The fixtures in testdata/ are synthetic sweeps generated by testdata/gen.py from a series-RLC antenna model โ€” regenerate or extend them freely.


Naming Convention For Archived Sweeps

2026-09-18_sitename_2m-base_system-shackend.s1p
2026-09-18_sitename_2m-base_antenna-feedpoint.s1p
2026-09-18_sitename_2m-base_feedline-tdr.png

Date first sorts chronologically. Site, antenna, and measurement plane in the name means you never have to guess later which sweep is comparable to which.


Invalid Input & JSON Results

Nonfinite measurements, duplicate frequencies, invalid reference impedance, and malformed data rows are rejected with exit code 3. Unordered unique frequencies are sorted before interpolation. JSON uses null for unbounded derived RF quantities (such as open-circuit VSWR), never Infinity or NaN.


๐Ÿ“„ Source: SDR/nanovna/tools/README.md | โœ๏ธ Suggest an edit | โฌ…๏ธ Back to Software-Defined Radio

Clone this wiki locally