pyespargos is the Python library for working with the ESPARGOS WiFi channel sounder. ESPARGOS is a real-time-capable, phase-synchronous 2 × 4 WiFi antenna array built from Espressif ESP32 chips that facilitates the development and deployment of WiFi sensing applications.

The library supports combining multiple ESPARGOS arrays into larger antenna arrays, various CSI preamble formats (L-LTF, HT20, HT40), and provides a flexible calibration system for multi-board setups.

Your ESPARGOS looks like this:	Your ESPARGOS looks like this:
→ You have the current ESPARGOS, please use the main branch of this repository.	→ You have the older prototype generation of ESPARGOS, please use the legacy-prototype branch of this repository. This hardware revision is no longer supported.

MUSIC Spatial Spectrum	Receive Signal Phase by Antenna
Instantaneous CSI: Frequency Domain	Instantaneous CSI: Time Domain
Phases over Time	Combined 8 × 4 ESPARGOS Array

pyespargos comes with a selection of demo applications for testing ESPARGOS. All demos are built on a common application framework (demos/common) that provides:

• A consistent command-line interface and YAML configuration support
• A graphical pool management drawer for connecting to ESPARGOS devices
• Selectable preamble formats (L-LTF, HT20, HT40)
• Configurable CSI backlog settings

The following demos are provided in the demos folder of this repository:

Most demos support both single ESPARGOS arrays and combined multi-board setups via command-line arguments or YAML configuration files.

pyespargos requires Python 3.11 or newer. Follow the instructions for your operating system below.

python3 --version

# Debian / Ubuntu
sudo apt update && sudo apt install python3 python3-venv python3-pip

# Fedora
sudo dnf install python3 python3-pip

# Arch Linux
sudo pacman -S python python-pip

python3 -m venv ~/pyespargos-venv
source ~/pyespargos-venv/bin/activate

cd pyespargos
pip install .

pip install -e .

pip install pyqt6 pyqt6-charts pyyaml matplotlib

(not recommended)

python --version

python -m venv %USERPROFILE%\pyespargos-venv
%USERPROFILE%\pyespargos-venv\Scripts\activate

cd pyespargos
pip install .

pip install -e .

pip install pyqt6 pyqt6-charts pyyaml matplotlib

(not recommended)

# Install Homebrew (if not already installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Python
brew install python

python3 --version

python3 -m venv ~/pyespargos-venv
source ~/pyespargos-venv/bin/activate

cd pyespargos
pip install .

pip install -e .

pip install pyqt6 pyqt6-charts pyyaml matplotlib

After installing pyespargos and the demo dependencies (steps above), you can run a demo. Make sure the virtual environment is activated, then run the following from the pyespargos directory.

For example, to run the Instantaneous CSI demo with an ESPARGOS controller at 192.168.1.2:

Linux / macOS:

./demos/instantaneous-csi/instantaneous-csi.py 192.168.1.2

Windows (Command Prompt):

python demos\instantaneous-csi\instantaneous-csi.py 192.168.1.2

If you have multiple ESPARGOS boards, pass their addresses separated by commas:

python demos/instantaneous-csi/instantaneous-csi.py 192.168.1.2,192.168.1.3

Other demos may ask for different command line arguments. Run any demo with --help to see the available options.

To create your own ESPARGOS-based application, you have two options:

• Use the Python + PyQt6 + QML framework used by the other demos. This is the fastest way to get up and running, just start by modifying an existing demo.
• Write your application from scratch using only the pyespargos library

After installation, import the espargos package in your Python application. Use this minimal sample code to get started:

#!/usr/bin/env python

import espargos
import time

pool = espargos.Pool([espargos.Board("192.168.1.2")])
pool.start()
pool.calibrate(duration = 2)
backlog = espargos.CSIBacklog(pool, size = 20)
backlog.start()

# Wait for a while to collect some WiFi packets to the backlog...
time.sleep(4)

# Get CSI data from the backlog (L-LTF format)
csi_lltf = backlog.get_lltf()
print("Received CSI (L-LTF): ", csi_lltf)

backlog.stop()
pool.stop()

• ESPARGOS uses the L-LTF and/or HT-LTF fields of 802.11g/n/ax frames to extract channel state information (CSI).
• ESPARGOS is totally passive, it only acts as a receiver in promiscuous mode. It provides CSI for any WiFi frames it receives.
• To receive frames, the transmitter and ESPARGOS must use the same WiFi channel.
• 802.11n supports channel bandwidths of 20MHz and 40MHz. The ESPARGOS hardware and firmware support both bandwidth configurations.
• pyespargos currently supports three preamble formats for CSI extraction:
  • L-LTF: Legacy Long Training Field, available in all 802.11g/n frames (52 subcarriers)
  • HT20: High Throughput 20MHz, available in 802.11n frames with 20MHz bandwidth (56 subcarriers)
  • HT40: High Throughput 40MHz, available in 802.11n frames with 40MHz channel bonding (114 subcarriers)

• ESPARGOS provides an HTTP / WebSocket / UDP API.
• Control commands (configuration, calibration, etc.) are issued via HTTP.
• CSI data is streamed in binary format. Two transports are supported:
  • UDP (default): Lower latency and higher throughput. The library automatically sends periodic keepalive packets to maintain firewall pinholes on platforms like Windows.
  • WebSocket: More widely compatible fallback, but slightly higher latency and overhead.
• By default, pyespargos tries UDP first and falls back to WebSocket if UDP fails.

• The L-LTF and HT-LTF fields used for channel estimation are really short compared to the total length of the WiFi frame.
• This results in really noisy CSI estimates.
• Therefore, it is a good idea to average CSI over multiple WiFi packets.
• To this end, pyespargos offers a backlog functionality, where CSI from the last N packets is cached. The backlog is implemented as a ringbuffer.
• The CSIBacklog class supports configurable fields (lltf, ht20, ht40, rssi, timestamp, mac) and optional MAC address filtering.
• In some applications, you may want use the CSI interpolation helpers in espargos/util.py.

• When receiving CSI from multiple antennas (potentially across multiple ESPARGOS boards), data from the same WiFi packet needs to be grouped together.
• The CSICluster class handles this clustering automatically, ensuring that CSI from all antennas is properly aligned.
• Callbacks can be registered with the Pool to receive complete clusters when all (or a subset of) antennas have reported.
• If you are using a backlog, then this aspect is abstracted away for you.

• ESPARGOS is based on phase-synchronized ESP32 SoCs. Phase synchronization is achieved in two steps:

  • All ESP32 chips are clocked from the same 40MHz reference clock, which makes them frequency-synchronous.
  • To correct for PLL phase ambiguity, WiFi PPDUs are distributed to all ESP32 chips over a known channel (microstrip traces of known length on the PCB).

• Now we know the initial phase of the local oscillator (LO) signal on every ESP32.

• With pyespargos, this calibration can be performed with just one command: pool.calibrate()

• In our observations, this initial phase offset between antennas remains relatively static over time, so one calibration of ESPARGOS should be sufficient.

• Additionally, we can obtain very precise packet reception timestamps, which provides time synchronization.

• pyespargos supports combining multiple ESPARGOS boards into a single large antenna array.
• The CSICalibration class handles phase calibration across boards, including compensation for different cable lengths and velocity factors used to distribute the synchronization signal.
• Board-specific parameters (PCB trace lengths, etc.) are automatically handled based on hardware revision detection.
• The combined-array-calibration demo can be used to generate and export calibration data for multi-board setups.

• dataset-recorder: Application to record ESPARGOS datasets for publication on https://espargos.net/datasets/. Please contact me to get access.
• realtime-localization: Real-time Localization Demo: Channel Charting vs. Triangulation vs. Supervised Training. Requires multiple ESPARGOS. Please contact me to get access.

pyespargos is licensed under the GNU Lesser General Public License version 3 (LGPLv3), see LICENSE for details.