pyespargos, driving a phase-synchronous ESP32 WiFi channel sounder from Python

A channel sounder, not a WiFi sniffer

The hardware is the point. ESPARGOS is described as a real-time-capable, phase-synchronous 2 by 4 WiFi antenna array built from Espressif ESP32 chips, built to facilitate the development and deployment of WiFi sensing applications. That is a different instrument class from a WiFi adapter in promiscuous mode. A sounder transmits known preambles and measures the channel response per antenna with a shared phase reference, which is what makes angle of arrival estimation possible at all. The library is the Python side of that instrument, and its stated capabilities follow from the hardware: combining multiple ESPARGOS arrays into larger antenna arrays, support for several CSI preamble formats (L-LTF, HT20, HT40), and a flexible calibration system for multi-board setups. The topics listed for the repository point the same way, with angle of arrival, channel state information and CSI as the headline terms.

The two hardware revisions live on different branches

The first thing a user with hardware in hand needs to know is which revision they own, and the project splits the library along that line. The current ESPARGOS boards are served by the `main` branch, while the older prototype generation is served by the `legacy-prototype` branch and is explicitly described as no longer supported. This is a common pattern in research hardware, where the first boards are still in circulation and the code diverged enough that a single tree no longer works. The practical consequence is that the install instructions on the main branch are not valid for the older units, and there is no upstream path to make them so. The default branch is `main`, so a plain clone gets the current revision, and the project homepage sits at espargos.net.

Installing the library and the demo dependencies

The library requires Python 3.11 or newer, which the packaging metadata enforces with `python_requires=">=3.11"`. The documented Linux and Raspberry Pi route is a clone, a virtual environment, an editable install and then the extra packages the demos need.

git clone https://github.com/ESPARGOS/pyespargos.git
cd pyespargos
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

The demo dependencies are optional and are the graphics stack: PyQt6, pyqt6-charts, PyYAML and matplotlib.

pip install pyqt6 pyqt6-charts pyyaml matplotlib

The runtime dependencies of the library itself are small and are pinned to minimum versions: websockets, numpy, pyserial and aiohttp, which is the combination you would expect for a device that streams data over a WebSocket while also being configurable over a serial link.

The dependency set, and a duplicated numpy line

The `setup.py` file is plain setuptools with no build backend trickery, and the package name on the index is `pyespargos` at version 0.1.1, with Florian Euchner as author. The runtime dependencies are `websockets>=12.0`, `numpy>=1.26.0`, `pyserial>=3.5` and `aiohttp>=3.9.0`, and the classifier list marks the licence as GNU Lesser General Public License v3 or later. The `requirements.txt` file lists the same four packages, but with `numpy>=1.26.0` appearing twice, once at the top and once at the bottom. It is harmless, since a duplicated requirement resolves to the same constraint, but it is the kind of small inconsistency worth knowing about if you are pinning the environment by hand rather than letting pip resolve it. The `pyproject.toml` file contains only a black configuration with a line length of 250, so formatting is enforced through black and nothing else is configured there.

One framework under every demo

The demo set is the most useful part of the repository, because each one isolates a measurement technique rather than a feature of the library. All of them are built on a common application framework in `demos/common` that provides a consistent command-line interface, YAML configuration support, a graphical pool management drawer for connecting to devices, selectable preamble formats, and configurable CSI backlog settings. `music-spectrum` runs the MUSIC algorithm to show an angular spectrum and demonstrate angle of arrival estimation. `phases-over-space` and `phases-over-time` show the average received phase per antenna. `instantaneous-csi` plots the current frequency-domain or time-domain transfer function. `iq-signal-analyzer` displays synchronized raw IQ as power and phase waterfalls, I/Q traces, constellations and spectra, with Interval, Accumulate and Signal capture modes. `tdoas-over-time` visualizes time difference of arrival measurements, and `polarization` shows signal polarization through constellation diagrams and polarization ellipses.

Beamspace, combined arrays and the tools that need two boards

Several demos push into research territory. `azimuth-delay` displays a two-dimensional azimuth-delay diagram using beamspace processing and ships with pre-compiled shaders, with a note in its own readme in case the shaders cause trouble. `camera` overlays the WiFi spatial spectrum on a live camera feed, also with pre-compiled shaders. `radiation-pattern-3d` gives an interactive three-dimensional radiation pattern visualization and needs additional packages listed in its own readme. Two demos require more than one board: `combined-array` combines multiple ESPARGOS arrays into one large antenna array and visualizes the average received phase per antenna, and `combined-array-calibration` is the tool for calibrating those multi-board arrays, which it both visualizes and exports. `speedtest` measures CSI packet throughput from the device. The two multi-board demos are where the calibration system earns its place, since phase coherence between boards is the hard part of building a larger array out of small ones.

Shader compilation is the only step that can need an extra tool

The project has thought about the failure mode where a demo will not start. Demos such as `camera` and `azimuth-delay` use shaders that are shipped in pre-compiled form as `.qsb` files in the repository, so in the normal case there is nothing to build. Only if a demo fails should you recompile the shaders yourself with the `compile_shader.sh` scripts, which needs the Qt Shader Baker, installed as `qt6-shader-baker` on Debian, Ubuntu and Raspberry Pi OS, `qt6-qtshadertools` on Fedora, and `qt6-shadertools` on Arch. The documentation then names the specific trap: the compile scripts expect `qsb` at `/usr/lib/qt6/bin/qsb`, so on a distribution that puts the tool elsewhere you have to account for that path. The one dependency that is not optional in any sense is the hardware itself.

Editorial conclusion

Adopt pyespargos if you own ESPARGOS hardware and need channel state information measurements, angle of arrival estimates or a multi-board phase-synchronous array, and skip it if you are looking for a general purpose WiFi sniffing tool, because this library is bound to one specific instrument and its firmware. Verify three things before you build on it: that your hardware is the current revision, since the older prototype generation is served from a separate legacy branch and is no longer supported; that your Python is 3.11 or newer, which the package metadata enforces; and that you can use a Qt Shader Baker only if the pre-compiled shaders fail, since the shader demos ship ready to run and the recompile step expects `qsb` at a fixed path.

Frequently asked questions

Official sources

1. ESPARGOS/pyespargos on GitHub
2. License: LGPL-3.0
3. Project website
4. README
5. Releases