wifi-profiler

WiFi Profiler

A cross-platform CLI/TUI tool for measuring and reporting Wi-Fi quality: RSSI, link speed, jitter, packet loss, latency, and throughput.

Features

• Real-time Monitoring: Live TUI dashboard with updating charts and metrics
• Comprehensive Testing: Ping tests, throughput measurements, and WiFi statistics
• Cross-platform: Linux (primary), macOS support
• Multiple Output Formats: Pretty terminal output, JSON, and HTML reports
• System Integration: Uses native tools (iw, nmcli, iwconfig, airport)
• Active & Passive Tests: ICMP ping, iperf3 integration, HTTP download fallback

Quick Start

Installation

# Install from PyPI
pip install wifi-profiler

# Or install from source
git clone https://github.com/wifi-profiler/wifi-profiler.git
cd wifi-profiler
pip install -e .

Basic Usage

# Quick test (10s ping + RSSI)
wifi-profiler quick

# Live monitoring dashboard
wifi-profiler live

# Comprehensive survey
wifi-profiler survey --duration 60

# List wireless interfaces
wifi-profiler devices

# Generate HTML report
wifi-profiler survey --html report.html

Commands

wifi-profiler quick

Quick WiFi quality test with ping and RSSI measurement.

wifi-profiler quick --target 8.8.8.8 1.1.1.1 --duration 10

Options:

• --iface, -i: Wireless interface name
• --target, -t: Ping targets (multiple allowed)
• --duration, -d: Test duration in seconds
• --json: Save results to JSON file
• --html: Generate HTML report
• --export: Save session data

wifi-profiler live

Interactive TUI dashboard with real-time metrics.

wifi-profiler live --iface wlan0 --target 8.8.8.8 --duration 300

Controls:

• s: Save snapshot
• q: Quit

wifi-profiler survey

Comprehensive WiFi survey with detailed analysis.

wifi-profiler survey \
  --iface wlan0 \
  --target 8.8.8.8 1.1.1.1 \
  --duration 30 \
  --ping-count 10 \
  --throughput-duration 15 \
  --html survey_report.html

wifi-profiler devices

List wireless interfaces and their details.

wifi-profiler devices --verbose

wifi-profiler import-session

Import saved session and generate reports.

wifi-profiler import-session session.json --html report.html

System Requirements

Linux

• Python 3.10+
• ping command
• One of: iw, iwconfig, or NetworkManager (nmcli)
• Optional: iperf3 for throughput testing
• Optional: curl or wget for HTTP download tests

macOS

• Python 3.10+
• ping command
• Built-in airport utility
• Optional: iperf3 for throughput testing

Installation of Dependencies

Ubuntu/Debian:

sudo apt update
sudo apt install wireless-tools network-manager iperf3 curl

CentOS/RHEL/Fedora:

sudo dnf install wireless-tools NetworkManager iperf3 curl
# or
sudo yum install wireless-tools NetworkManager iperf3 curl

macOS:

# iperf3 via Homebrew
brew install iperf3

Configuration

Create a configuration file at ~/.config/wifi-profiler/config.toml:

# Default interface (auto-detect if not specified)
default_interface = "wlan0"

# Default ping targets
default_targets = ["8.8.8.8", "1.1.1.1"]

# Test durations
default_duration = 30
ping_count = 10
throughput_test_duration = 10

# iperf3 server (optional)
iperf3_server = "speedtest.tele2.net:5201"

# HTTP download URL for fallback throughput testing
http_download_url = "https://speed.hetzner.de/100MB.bin"

# Output settings
log_level = "INFO"
output_format = "text"
save_sessions = true

Output Formats

Terminal Output

Rich, colored terminal output with tables and progress bars.

JSON Output

Machine-readable JSON format for programmatic analysis:

{
  "session_id": "survey_1234567890",
  "start_time": "2024-01-15T10:30:00",
  "end_time": "2024-01-15T10:30:30",
  "interface": {
    "name": "wlan0",
    "ssid": "MyWiFi",
    "bitrate": 866.7
  },
  "wifi_stats": [...],
  "ping_summaries": [...],
  "throughput_results": [...]
}

HTML Reports

Self-contained HTML reports with interactive charts:

wifi-profiler survey --html report.html

Features:

• Interactive RSSI charts using Plotly
• Detailed ping and throughput tables
• Responsive design
• Quality indicators with color coding

Examples

Basic Network Quality Check

# Quick check of current WiFi quality
wifi-profiler quick --target 8.8.8.8 --json results.json

Long-term Monitoring

# Monitor for 5 minutes with live updates
wifi-profiler live --duration 300 --interval 2.0

Comprehensive Analysis

# Full survey with all tests
wifi-profiler survey \
  --duration 60 \
  --ping-count 20 \
  --throughput-duration 20 \
  --html comprehensive_report.html \
  --json session_data.json

Batch Testing

# Test multiple targets
wifi-profiler survey \
  --target 8.8.8.8 1.1.1.1 208.67.222.222 \
  --duration 30

Troubleshooting

No Wireless Interfaces Found

# Check available interfaces
wifi-profiler devices --verbose

# Ensure wireless tools are installed
sudo apt install wireless-tools  # Ubuntu/Debian

Permission Issues

Some operations may require elevated privileges:

# Run with sudo if needed
sudo wifi-profiler quick

iperf3 Not Available

The tool will automatically fall back to HTTP download testing if iperf3 is not available.

Network Connectivity Issues

# Check basic connectivity
ping 8.8.8.8

# Verify interface is up
ip link show wlan0

Development

Setup Development Environment

git clone https://github.com/wifi-profiler/wifi-profiler.git
cd wifi-profiler
pip install -e ".[dev]"

Running Tests

pytest
pytest --cov=wifi_profiler

Code Quality

ruff check .
black .
mypy wifi_profiler/

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests
• Run the test suite
• Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Textual for the TUI framework
• Rich for beautiful terminal output
• Typer for CLI framework
• Pydantic for data validation
• Plotly for interactive charts

Roadmap

• Windows support
• Prometheus metrics export
• REST API mode
• Advanced packet analysis
• WiFi channel analysis
• Historical data tracking
• Alert system
• Mobile app companion

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: GitHub Wiki