ESP32/doc/BANDWIDTH_BAND_SELECTION_GUIDE.md

# Bandwidth and Band Selection Guide

## 🎯 New Features

### Monitor Mode: Channel + Bandwidth Selection
Control both the channel AND bandwidth when monitoring:
```bash
mode_monitor 6/20      # 2.4GHz channel 6, 20MHz
mode_monitor 36/80     # 5GHz channel 36, 80MHz
```

### STA Mode: Band Preference
Force connection to specific band:
```bash
mode_sta 2.4           # Connect on 2.4GHz only
mode_sta 5             # Connect on 5GHz only
mode_sta auto          # Auto select (default)
```

---

## 📡 Monitor Mode Bandwidth Control

### Syntax
```
mode_monitor <channel>/<bandwidth>
```

### 2.4GHz Band Bandwidth Options

**20MHz (HT20)** - Single channel
```bash
mode_monitor 1/20
mode_monitor 6/20
mode_monitor 11/20
```
- ✅ Maximum compatibility
- ✅ Less interference from adjacent channels
- ❌ Lower throughput (~72 Mbps max)

**40MHz (HT40)** - Channel bonding
```bash
mode_monitor 1/40
mode_monitor 6/40
mode_monitor 11/40
```
- ✅ Higher throughput (~150 Mbps max)
- ⚠️ Uses 2 adjacent channels (more interference)
- ⚠️ Not recommended in dense environments

**Default:** If bandwidth not specified, defaults to 20MHz
```bash
mode_monitor 6         # Same as 6/20
```

### 5GHz Band Bandwidth Options

**20MHz (HT20)** - Single channel
```bash
mode_monitor 36/20
mode_monitor 149/20
```
- ✅ Maximum compatibility
- ✅ Best for long range
- ❌ Lower throughput

**40MHz (HT40)** - Channel bonding
```bash
mode_monitor 36/40     # Channels 36+40
mode_monitor 149/40    # Channels 149+153
```
- ✅ Good balance of speed and compatibility
- ✅ WiFi 5 (802.11ac) standard
- ⚠️ Uses 2 channels

**80MHz (HT80)** - Wide channel bonding (WiFi 6)
```bash
mode_monitor 36/80     # Channels 36+40+44+48
mode_monitor 149/80    # Channels 149+153+157+161
```
- ✅ Maximum throughput (~866 Mbps+ with WiFi 6)
- ✅ WiFi 6 (802.11ax) optimized
- ⚠️ Uses 4 channels
- ⚠️ Shorter range than 20/40MHz

**Default:** If bandwidth not specified, defaults to 40MHz on 5GHz
```bash
mode_monitor 149       # Same as 149/40
```

---

## 🌐 STA Mode Band Selection

### Syntax
```
mode_sta [band]
```

### Band Options

**Auto (Default)** - Let ESP32 choose best band
```bash
mode_sta
mode_sta auto
```
- ✅ Connects to strongest signal
- ✅ Falls back if preferred band unavailable
- Use when: AP supports both bands

**2.4GHz Only**
```bash
mode_sta 2.4
mode_sta 2
```
- ✅ Forces connection on 2.4GHz
- ✅ Better range, wall penetration
- ❌ Lower speed, more interference
- Use when: Need maximum range

**5GHz Only**
```bash
mode_sta 5
mode_sta 5.0
```
- ✅ Forces connection on 5GHz
- ✅ Higher speed, less interference
- ❌ Shorter range
- Use when: AP is close, need best performance

---

## 📊 Usage Examples

### Example 1: 2.4GHz Narrow Band Monitoring
For maximum interference rejection in dense environment:
```bash
esp32> mode_monitor 6/20

I (+1733424645.234) MAIN: Switching to MONITOR MODE
I (+1733424645.235) MAIN:   Channel: 6 (2.4GHz)
I (+1733424645.236) MAIN:   Bandwidth: 20MHz
I (+1733424647.567) MAIN: ✓ Monitor mode active
```

### Example 2: 2.4GHz Wide Band Monitoring
For maximum throughput testing:
```bash
esp32> mode_monitor 6/40

I (+1733424645.234) MAIN: Switching to MONITOR MODE
I (+1733424645.235) MAIN:   Channel: 6 (2.4GHz)
I (+1733424645.236) MAIN:   Bandwidth: 40MHz
```

### Example 3: 5GHz WiFi 6 Monitoring
For WiFi 6 collapse detection with 80MHz:
```bash
esp32> mode_monitor 36/80

I (+1733424645.234) MAIN: Switching to MONITOR MODE
I (+1733424645.235) MAIN:   Channel: 36 (5GHz)
I (+1733424645.236) MAIN:   Bandwidth: 80MHz
I (+1733424647.567) MAIN: ✓ Monitor mode active
```

### Example 4: Force 5GHz Connection
Connect to AP on 5GHz band only:
```bash
esp32> mode_sta 5

I (+1733424645.234) MAIN: Switching to STA MODE
I (+1733424645.235) MAIN:   Band preference: 5GHz only
I (+1733424647.234) MAIN: Got IP: 192.168.1.100
I (+1733424647.567) MAIN: ✓ STA mode active
```

### Example 5: Check Current Configuration
```bash
esp32> mode_status

=== WiFi Mode Status ===
Current mode: MONITOR
LED state: Blue solid (Monitoring)
Monitor channel: 36 (5GHz)
Monitor bandwidth: 80MHz
Monitor enabled: Yes
Frames captured: 15234
GPS synced: Yes (+)
```

### Example 6: Switch Between Bandwidths
Test different bandwidths on same channel:
```bash
# Start with 20MHz
esp32> mode_monitor 149/20
[collect data for 5 minutes...]

# Switch to 40MHz
esp32> mode_monitor 149/40
[collect data for 5 minutes...]

# Switch to 80MHz
esp32> mode_monitor 149/80
[collect data for 5 minutes...]

# Compare collapse rates vs bandwidth
```

---

## 🎯 Bandwidth Selection Strategy

### When to Use 20MHz

**Best for:**
- Dense environments with many APs
- Long-range connections
- Interference-prone areas
- Maximum compatibility

**Monitor mode:**
```bash
mode_monitor 6/20      # 2.4GHz
mode_monitor 149/20    # 5GHz
```

### When to Use 40MHz

**Best for:**
- Medium-density environments
- Balance of speed and range
- Most common configuration
- WiFi 5 (802.11ac)

**Monitor mode:**
```bash
mode_monitor 6/40      # 2.4GHz (not recommended in dense areas)
mode_monitor 149/40    # 5GHz (recommended)
```

### When to Use 80MHz

**Best for:**
- Low-density environments
- Maximum throughput
- WiFi 6 (802.11ax) testing
- Short-range, high-speed links

**Monitor mode (5GHz only):**
```bash
mode_monitor 36/80
mode_monitor 149/80
```

---

## 🔍 Real-World Scenarios

### Scenario 1: Office WiFi Collapse Detection
**Goal:** Monitor office WiFi on 5GHz with WiFi 6

```bash
# 1. Connect to AP and check its configuration
esp32> mode_sta
[wait for connection...]

esp32> mode_status
Connected band: 5GHz (channel 36)
Bandwidth: 80MHz

# 2. Switch to monitor mode with same config
esp32> mode_monitor 36/80

# 3. Monitor for collapse events
[Logs GPS-timestamped collapse events...]
```

### Scenario 2: 2.4GHz Congestion Analysis
**Goal:** Compare 20MHz vs 40MHz collapse rates

```bash
# Test 20MHz (narrow band)
esp32> mode_monitor 6/20
[collect for 30 minutes...]
# Note collapse count

# Test 40MHz (wide band)
esp32> mode_monitor 6/40
[collect for 30 minutes...]
# Compare: 40MHz likely has MORE collapses in dense area
```

### Scenario 3: Force 5GHz for Performance
**Goal:** Ensure device connects on 5GHz only

```bash
# Force 5GHz connection
esp32> mode_sta 5

# Verify connected on 5GHz
esp32> mode_status
Band preference: 5GHz only
Connected band: 5GHz (channel 149)
Bandwidth: 80MHz

# Now switch to monitor on same channel
esp32> mode_monitor 149/80
```

### Scenario 4: Multi-Device Deployment
**Goal:** Monitor different bandwidths across 32 devices

```bash
# Devices 1-8: 2.4GHz 20MHz
Device 1-8: mode_monitor 6/20

# Devices 9-16: 2.4GHz 40MHz
Device 9-16: mode_monitor 6/40

# Devices 17-24: 5GHz 40MHz
Device 17-24: mode_monitor 149/40

# Devices 25-32: 5GHz 80MHz
Device 25-32: mode_monitor 149/80

# Compare collapse rates across all configurations!
```

---

## 📈 Performance Expectations

### 2.4GHz Performance

| Bandwidth | Max PHY Rate | Typical Throughput | Range | Interference |
|-----------|-------------|-------------------|-------|--------------|
| 20MHz | ~72 Mbps | 40-50 Mbps | Best | Least |
| 40MHz | ~150 Mbps | 80-100 Mbps | Good | Most |

### 5GHz Performance

| Bandwidth | Max PHY Rate | Typical Throughput | Range | Best Use |
|-----------|-------------|-------------------|-------|----------|
| 20MHz | ~87 Mbps | 50-60 Mbps | Best | Long range |
| 40MHz | ~200 Mbps | 120-150 Mbps | Good | Balanced |
| 80MHz | ~433 Mbps | 300-400 Mbps | Short | Max speed |

*Note: WiFi 6 (802.11ax) can achieve higher rates with OFDMA and 1024-QAM*

---

## ⚙️ Advanced Usage

### Match Your AP's Configuration
Always match bandwidth to your AP for best results:

```bash
# 1. Check AP configuration (via router admin or WiFi analyzer)
# Example: AP is on channel 36 with 80MHz

# 2. Configure STA mode to connect
esp32> mode_sta 5

# 3. Verify connection
esp32> mode_status
Connected band: 5GHz (channel 36)
Bandwidth: 80MHz

# 4. Switch to monitor with SAME configuration
esp32> mode_monitor 36/80
```

### Test Bandwidth Impact on Collapse
```python
# After collecting data at different bandwidths:
import pandas as pd

df_20 = pd.read_csv('collapses_ch36_20mhz.csv')
df_40 = pd.read_csv('collapses_ch36_40mhz.csv')
df_80 = pd.read_csv('collapses_ch36_80mhz.csv')

print("Collapse rate (20MHz):", len(df_20) / 3600, "per hour")
print("Collapse rate (40MHz):", len(df_40) / 3600, "per hour")
print("Collapse rate (80MHz):", len(df_80) / 3600, "per hour")

# Hypothesis: Wider bandwidth = more collapses in dense environments
```

---

## ✅ Quick Reference

### Monitor Mode Bandwidths

| Band | Command | Bandwidth | Use Case |
|------|---------|-----------|----------|
| 2.4GHz | `mode_monitor 6/20` | 20MHz | Dense area, max compatibility |
| 2.4GHz | `mode_monitor 6/40` | 40MHz | Speed test (avoid in dense area) |
| 5GHz | `mode_monitor 149/20` | 20MHz | Long range |
| 5GHz | `mode_monitor 149/40` | 40MHz | Balanced (default) |
| 5GHz | `mode_monitor 149/80` | 80MHz | WiFi 6 max speed |

### STA Mode Bands

| Command | Behavior | Use Case |
|---------|----------|----------|
| `mode_sta` | Auto select | Default, best signal |
| `mode_sta 2.4` | Force 2.4GHz | Max range |
| `mode_sta 5` | Force 5GHz | Max performance |

---

## 🎉 Summary

**New capabilities:**
- ✅ Monitor mode with bandwidth control (20/40/80MHz)
- ✅ STA mode with band preference (2.4/5/auto)
- ✅ Full control over WiFi 6 configurations
- ✅ Test different bandwidths for collapse analysis
- ✅ Force band for optimal performance

**Syntax:**
```bash
mode_monitor <channel>/<bandwidth>   # e.g., 36/80
mode_sta [band]                      # e.g., mode_sta 5
```

Now you can precisely control and test WiFi configurations across all supported bands and bandwidths!