Wi-Fi CSI tools and datasets: GitHub scripts, Python analysis and OpenWrt capture

By Wu Jun · Updated 2026-11-02 · 7 min read

Everything this project actually uses and produces. Every script has been run on real hardware, together with the 10-minute capture.

0. Decide whether the toolkit fits

1. Capture and analysis scripts

Start with the browser-local CSI capture quality checker. It validates the outer frame layout, chain_info closed groups, chain and subcarrier consistency, timestamp gaps and non-empty I/Q without uploading the capture. Results can be exported as JSON or Markdown.

• scripts/csi_capture_session.sh <seconds>: timed capture plus analysis of rate and gaps; runs on macOS/Linux.
• scripts/analyze_csi_capture.py: amplitude heatmap and a one-second rolling motion metric using only NumPy/Matplotlib.
• scripts/csi-watchdog.sh: router-side check of the daemon, interface and CSI state every minute, with tuning replay.
• scripts/wifi-htmode.sh HE80|HE40: switches bandwidth mode and keeps the daemon's bandwidth metadata in sync.
• scripts/mt76-wifi-tune: sets vow_atf to 0 at boot so it cannot block rate recovery.

The scripts and parsers are open source under MIT and run on real hardware ^[1].

Router stability toolkit v0.1.3

• Source and issues on GitHub
• v0.1.3 Release
• Independent source archive at Software Heritage
• Download the toolkit (tar.gz)
• SHA-256 checksum file

The archive contains capture, analysis, watchdog, HE80/HE40 switching, boot-time vow_atf tuning and data-format documentation. It does not contain Wi-Fi firmware, the CSI driver patch or a site-specific first-boot configuration. Run it only on a research device already using OpenWrt plus the mt76 CSI stack, read INSTALL.md, back up the configuration and confirm interface names first.

v0.1.3 moves project links in the public scripts to the canonical okwujun.pw host and adds a standard-library reproducible packager. Archives use stable file ordering, permissions and timestamp metadata while excluding .git, caches, credentials and machine-specific first-boot configuration; two independent builds are byte-identical. Capture and analysis behaviour keeps the v0.1.2 fix that aligns the direct csi_capture.py default with the documented UDP port 8888. Software Heritage completed a full archive visit for the Git repository. Snapshot swh:1:snp:84d1d83e93b8ea9e197fea3b151b3f14113bef4c fixes the main-branch revision, the release branch and the tagged release. This independent archive proves source traceability only; it is not a security audit or a performance endorsement.

# Verify before extracting
shasum -a 256 -c router-csi-toolkit-v0.1.3.tar.gz.sha256
tar -xzf router-csi-toolkit-v0.1.3.tar.gz

# Install analysis dependencies
python3 -m pip install numpy matplotlib

# typical flow: 10-second check
router-csi-toolkit/scripts/csi_capture_session.sh 10

# 10-minute stability run (raw bin + analysis images + summary txt)
router-csi-toolkit/scripts/csi_capture_session.sh 600

Requirements: macOS / Linux, Python 3.8+, numpy and matplotlib; root privileges on the capture host, and a router already running the mt76 CSI daemon (see the reproduction guide).

Outputs:

1.1 Minimum acceptance path

1. confirm UDP visibility with tcpdump -ni any udp port 8888;
2. capture 10 seconds and confirm the bin file is non-empty;
3. run analyze_csi_capture.py and check record count, duration and matrix shape;
4. only then run for 10 minutes;
5. record maximum gaps, file growth, RSSI/SNR and daemon memory;
6. save the command, firmware, channel and bandwidth, not only a heatmap.

If the 10-second file is empty, check the frame-type/MAC filters, interface name and target-client traffic before starting a 10-minute run.

2. Measured data (published here)

The record format is documented in section 6 of the reproduction guide (24-byte header + interleaved int16 I/Q). Download the 10 s sample from the dataset page. Verify the 60-second demo source with SHA256SUMS or inspect its manifest. The full 10-minute dataset is on Zenodo (DOI: https://doi.org/10.5281/zenodo.23434789) with 8 parts, a manifest, a reassembly guide and two analysis figures. The capture-quality audit adds a timing report, JSON summary and script that can be reproduced without training a classifier. The timestamp-gap spectral analysis compares interpolated Welch with an original-timestamp periodogram and publishes the script, frequency-sweep CSV and four-panel figure. The CSI chain-health audit quantifies eight-chain versus four-chain groups, per-chain temporal variability and the shared semantics of RSSI/SNR. It publishes the script, chain CSV, JSON summary and SVG. The CSI subcarrier-redundancy audit uses both captures to compute the 256-bin correlation matrix and PCA: 6 components explain 90% of variance, with per-bin CSV, all 256 eigenvalues, JSON, script and figure published. The result is not a physical sensor count.

Units matter: 95.5 is chain records/s, not a 95.5 Hz independent-snapshot rate. Grouping on chain_info bit 15 gives 7,609 closed measurements over 599.924 s, about 12.68 Hz. Simple chain selection produces an approximately 7,608 x 256 matrix; removing another 25 anomaly groups leaves 7,583 measurements, or about 12.64 Hz.

3. Live visualisation platform (open skeleton)

The platform/ directory is a self-hostable live dashboard:

• docker compose up -d to start;
• full UDP ingest → ring buffer → overview / waterfall / phase-amplitude / motion views;
• REST + WebSocket; any front-end framework can attach;
• recording and replay (M1 skeleton).

Configure the source address, listen port and storage path in platform/README before starting. The containers only require Docker; no host-side database or Python runtime is needed.

This project deployed the platform on an older i5-2430M / 8 GB LAN server, but that is not a capacity promise for every configuration. Benchmark 10 seconds, 10 minutes and 24 hours with your own record rate and retention policy.

3.1 Platform surface and limits

The platform does not currently include an MQTT publisher and has no /api/csi/status. Home Assistant must use a REST integration against /api/stations, or a separate MQTT bridge.

4. Open-source projects you can reuse

5. Hardware (buying references)

These are hardware references; no affiliate links are used. If that changes, promoted links will be clearly labelled.

6. Safety, licences and stop conditions

• capture needs permission for raw UDP, but the web UI and analysis process should not run as root;
• keep UDP 8888, SSH and the management API on a trusted LAN; never expose them directly to the internet;
• toolkit scripts are MIT and documentation is CC BY 4.0; third-party projects retain their own licences;
• record the exact command and interface to avoid analysing another AP or interface by mistake;
• stop when packet loss persists, file growth is anomalous, disk headroom is low or the router becomes unreachable;
• anonymise MAC addresses and recompute SHA-256 before publishing any capture.