wifi-profiler 0.1.0
A cross-platform CLI/TUI tool for measuring and reporting Wi-Fi quality
License: MIT
Requires Python: >=3.10
Keywords: wifi, network, profiling, cli, tui, monitoring, network-diagnostics, wifi-analysis

# WiFi Profiler

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI](https://img.shields.io/badge/PyPI-wifi--profiler-blue.svg)](https://pypi.org/project/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

```bash
# 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

```bash
# 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.

```bash
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.

```bash
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.

```bash
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.

```bash
wifi-profiler devices --verbose
```

### `wifi-profiler import-session`
Import saved session and generate reports.

```bash
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:**
```bash
sudo apt update
sudo apt install wireless-tools network-manager iperf3 curl
```

**CentOS/RHEL/Fedora:**
```bash
sudo dnf install wireless-tools NetworkManager iperf3 curl
# or
sudo yum install wireless-tools NetworkManager iperf3 curl
```

**macOS:**
```bash
# iperf3 via Homebrew
brew install iperf3
```

## Configuration

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

```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:

```json
{
  "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:

```bash
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
```bash
# Quick check of current WiFi quality
wifi-profiler quick --target 8.8.8.8 --json results.json
```

### Long-term Monitoring
```bash
# Monitor for 5 minutes with live updates
wifi-profiler live --duration 300 --interval 2.0
```

### Comprehensive Analysis
```bash
# 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
```bash
# 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
```bash
# 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:
```bash
# 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
```bash
# Check basic connectivity
ping 8.8.8.8

# Verify interface is up
ip link show wlan0
```

## Development

### Setup Development Environment
```bash
git clone https://github.com/wifi-profiler/wifi-profiler.git
cd wifi-profiler
pip install -e ".[dev]"
```

### Running Tests
```bash
pytest
pytest --cov=wifi_profiler
```

### Code Quality
```bash
ruff check .
black .
mypy wifi_profiler/
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Run the test suite
6. Submit a pull request

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [Textual](https://textual.textualize.io/) for the TUI framework
- [Rich](https://rich.readthedocs.io/) for beautiful terminal output
- [Typer](https://typer.tiangolo.com/) for CLI framework
- [Pydantic](https://pydantic-docs.helpmanual.io/) for data validation
- [Plotly](https://plotly.com/) 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](https://github.com/wifi-profiler/wifi-profiler/issues)
- **Discussions**: [GitHub Discussions](https://github.com/wifi-profiler/wifi-profiler/discussions)
- **Documentation**: [GitHub Wiki](https://github.com/wifi-profiler/wifi-profiler/wiki)