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 snapshotq: 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+
pingcommand- One of:
iw,iwconfig, or NetworkManager (nmcli) - Optional:
iperf3for throughput testing - Optional:
curlorwgetfor HTTP download tests
macOS
- Python 3.10+
pingcommand- Built-in
airportutility - Optional:
iperf3for 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
Metadata
Release files for wifi-profiler 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wifi_profiler-0.1.0.tar.gz | 34.9 kB | Without provenance | Details for wifi_profiler-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wifi_profiler-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for wifi_profiler-0.1.0-py3-none-any.whl |
Total release size: 69.3 kB
Release files / wifi_profiler-0.1.0.tar.gz
| Download URL | wifi_profiler-0.1.0.tar.gz |
|---|---|
| Size | 34.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a32be4c957687013e7f8c0da8ffb68aec48a4c6154574edbffd031c1b24fb516
|
|
BLAKE2b-256 checksum How to use checksums |
67c3a5559b1e9bb196d25309e6442c3ad1528bd6473af36c348196ced9889c43
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.3
|
Release files / wifi_profiler-0.1.0-py3-none-any.whl
| Download URL | wifi_profiler-0.1.0-py3-none-any.whl |
|---|---|
| Size | 34.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fd8da8070bd8c0d64d7c6f333731110be357b50584303eb0e98bd63ef0a3d8b7
|
|
BLAKE2b-256 checksum How to use checksums |
fd7cb3ab52c1b5c6a1a1bacbd56f9cdc1286187a8e5edcb6319df5e3f4278410
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.12.3
|
Security for wifi-profiler 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.