ADALM-PLUTO 2.4 GHz Wi-Fi Spectrum Monitor

Project Overview

This is Part 1 of a university software-defined radio (SDR) project. The system performs online, energy-based monitoring of the complete 2400–2500 MHz (2.4 GHz ISM) band with an ADALM-PLUTO SDR:

• live monitoring of 2400–2500 MHz
• full-band spectrum sensing
• Wi-Fi channel energy analysis (channels 1–13)
• channel-center candidate detection
• temporal candidate stabilization
• time-frequency heatmap

Main Features

System Architecture

ADALM-PLUTO (USB, receive-only)          src/pluto_receiver.py
     ↓
IQ Samples
     ↓
FFT / Relative Power                     src/spectrum.py
     ↓
Overlapping Frequency Sweep              src/sweep.py
     ↓
2400–2500 MHz Spectrum                   (stitched, linear power + dB)
     ↓
 ┌───────────────┬──────────────────┐
 ↓               ↓                  ↓
Channel       Temporal           Heatmap
Analysis      Candidates         History
(src/channel_detector.py)        (src/heatmap.py)

Project Structure

WiFi_Channel_Sensing/
│
├── main.py                       Entry point (menu and --mode)
├── README.md                     Primary documentation (GitHub)
├── README.html                   This standalone documentation page
├── requirements.txt              pyadi-iio, numpy, matplotlib
├── .gitignore
│
├── src/
│   ├── __init__.py
│   ├── config.py                 All settings (including PLUTO_URI)
│   ├── pluto_receiver.py         Hardware access (receive-only)
│   ├── spectrum.py               FFT / power / average / max hold / masks
│   ├── sweep.py                  LO sweep and stitching
│   ├── channel_detector.py       Energy occupancy, center and stable candidates
│   ├── heatmap.py                Spectrum and occupancy history
│   └── utils.py                  Figure helpers
│
├── scripts/
│   ├── __init__.py               Makes `python -m scripts.<name>` reliable
│   ├── test_pluto.py
│   ├── test_spectrum.py
│   ├── test_full_sweep.py
│   ├── test_channel_detection.py
│   └── live_monitor.py
│
├── data/
│   ├── raw/
│   └── processed/                NPZ and CSV results (generated)
│
└── results/
    ├── figures/                  PNG figures (generated)
    └── logs/

Requirements

libiio is a C library installed with apt; pip cannot install it. pyadi-iio loads it through its pylibiio bindings, so both are needed.

Setup on a New Computer

Follow steps A–H once per computer. Nothing is assumed to be installed. PowerShell (Administrator) commands run on Windows; Ubuntu commands run inside the WSL Ubuntu terminal.

wsl --install

wsl --update

winget install --interactive --exact dorssel.usbipd-win

sudo apt update

sudo apt install -y \
    python3 \
    python3-pip \
    python3-venv \
    libiio-utils \
    usbutils

sudo apt install -y git          # only if `git --version` fails (needed in step E)
sudo apt install -y python3-tk   # plot windows through WSLg; PNG files are saved either way

lsusb
iio_info -S usb

Available contexts:
	0: 0456:b673 (Analog Devices Inc. PlutoSDR (ADALM-PLUTO)), serial=... [usb:1.2.5]

cd ~
git clone <REPOSITORY_URL>
cd WiFi_Channel_Sensing

python3 -m venv .venv

source .venv/bin/activate

python -m pip install --upgrade pip

python -m pip install -r requirements.txt

python -c "import iio; print('iio OK')"

python -c "import adi; print('pyadi-iio OK')"

python -m scripts.test_pluto

Connecting to ADALM-PLUTO...
URI: usb:...
Connected successfully.
Configured: LO 2437.000 MHz, 20.0 MS/s, buffer 16384
Samples received: 16384
First 5 IQ samples:
[...]

Pluto URI

Run the following command and use the URI shown in square brackets on your machine:

iio_info -S usb

The program connects to the URI configured in src/config.py:

PLUTO_URI = "usb:..."

Set it to the discovered URI, e.g. PLUTO_URI = "usb:1.2.5". (PLUTO_URI = "usb:" selects the only connected USB Pluto automatically and does not need updating after reconnects.)

Running the Project

Always run from the project root with the virtual environment active.

Main program

============================================
 ADALM-PLUTO 2.4 GHz Wi-Fi Spectrum Monitor
============================================

1. Test Pluto connection
2. Single full-band sweep
3. Analyze saved spectrum
4. Start live monitoring
5. Exit

python main.py --mode test
python main.py --mode sweep
python main.py --mode analyze
python main.py --mode live

During live monitoring each sweep prints a short block:

Sweep 5/30   (1.09 s, spectrum + heatmap updated)
  Noise floor:       -38.3 dB
  Energy windows:    [4, 5, 6, 7, 8, 9]
  Instant candidate: [7]
  Stable candidate:  [6]   (last 5)

The number of sweeps and all other settings are in src/config.py.

Developer commands

Stand-alone scripts (the menu uses the same code):

python -m scripts.test_pluto               # connection and IQ samples
python -m scripts.test_spectrum            # channel 6: FFT, average, max hold, masks
python -m scripts.test_full_sweep          # full-band sweep with detailed log
python -m scripts.test_channel_detection   # channel analysis of the saved sweep
python -m scripts.live_monitor             # live monitoring

Generated Output

The programs create these files at runtime. They are ignored by Git (.gitignore), so a freshly cloned repository contains only empty folders.

Figures — results/figures/

Processed data — data/processed/

Without a plot window (normal under WSL without python3-tk), open the PNGs from Windows, e.g. explorer.exe results/figures. The live PNG and CSV files are rewritten after every sweep and can be viewed while monitoring runs.

Technical Method

IQ capture → Hann window → FFT → Power → averaging
  → overlapping LO sweep → invalid-edge / DC masking → linear-power stitching
  → channel analysis → temporal smoothing → heatmap

• Capture and FFT: 20 MS/s, FFT size 16384; per buffer the DC offset is removed, a Hann window applied and the power computed. 20 captures per LO center (after 2 discarded buffers) are averaged in linear power; max hold keeps the per-bin maximum.
• Sweep: LO centers 2408.5, 2416.5, 2433.5, 2441.5, 2458.5, 2466.5, 2483.5 and 2491.5 MHz with fixed manual RX gain.
• Masking: ±0.2 MHz around each LO and 1 MHz at each capture edge are excluded; the paired centers fill each other's excluded regions.
• Stitching: valid bins are averaged in linear power into 5 kHz cells over 2400–2500 MHz; overlapping segments are averaged (max hold: maximum).
• Noise floor: 20th percentile of the stitched spectrum.
• Energy occupancy: a channel window (center ±10 MHz) is energy-occupied if its median is ≥ 5 dB above the noise floor or ≥ 20 % of its bins are ≥ 6 dB above it.
• Center candidate: score = max(core median − floor, 0) × core active fraction over center ±8 MHz; local maximum, score ≥ 2.5, 15 MHz separation.
• Stable candidate (temporal smoothing): scores averaged over the last 5 sweeps, same rules, supported (score ≥ 2.5) in at least 3 of them.
• Heatmap: each completed sweep becomes one row of the time-frequency history.

All thresholds are in src/config.py.

Important Scientific Limitations

Troubleshooting

Work through the checks in order: lsusb → iio_info -S usb → Python imports → python -m scripts.test_pluto. The first failing check shows where the problem is.

echo 'SUBSYSTEM=="usb", ATTRS{idVendor}=="0456", ATTRS{idProduct}=="b673", MODE="0666"' \
    | sudo tee /etc/udev/rules/53-adi-plutosdr-usb.rules
sudo udevadm control --reload-rules

usbipd detach --busid <BUSID>
usbipd attach --wsl --busid <BUSID>

Starting the Project Again Later

After rebooting Windows, restarting WSL (wsl --shutdown) or unplugging the ADALM-PLUTO, the device must be attached to WSL again.

1. Start Ubuntu.
2. PowerShell (Administrator)

   usbipd list
   usbipd attach --wsl --busid <BUSID>

   If the device is listed as Not shared (e.g. after using a different USB port), bind it first:

   usbipd bind --busid <BUSID>

3. Ubuntu

   lsusb
   iio_info -S usb

   If the URI in square brackets changed, update PLUTO_URI in src/config.py.
4. Start the program:

   cd ~/WiFi_Channel_Sensing
   source .venv/bin/activate
   python main.py

Quick Start

For a computer where Setup on a New Computer has already been completed.

usbipd list
usbipd bind --busid <BUSID>          # only if the Pluto is not shared yet
usbipd attach --wsl --busid <BUSID>

lsusb
iio_info -S usb                      # update PLUTO_URI in src/config.py if the URI changed

cd ~/WiFi_Channel_Sensing
source .venv/bin/activate

python -m scripts.test_pluto
python main.py

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt