# GDB Runtime Threshold Tuning Guide

Adjust WiFi monitor thresholds **on-the-fly** using GDB - no rebuild required!

## Best of Both Worlds

✅ **C code performance** - 10,000+ frames/sec  
✅ **GDB tunability** - Adjust thresholds in real-time  
✅ **No rebuild needed** - Change settings instantly  

## Installation

```bash
cd ~/Code/esp32/esp32-iperf

# Update components
cp wifi_monitor.c components/wifi_monitor/
cp .gdbinit .

# Rebuild once
idf.py build
idf.py -p /dev/ttyACM0 flash

# Enable GDB auto-load
mkdir -p ~/.config/gdb
echo "set auto-load safe-path /" >> ~/.config/gdb/gdbinit
```

## Start GDB Session

```bash
# Terminal 1: OpenOCD
idf.py openocd

# Terminal 2: GDB
idf.py gdb
```

## Quick Start

### View Current Thresholds

```gdb
(gdb) show_thresholds
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WiFi Monitor Thresholds (GDB-tunable)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
High NAV threshold:         5000 us
Duration mismatch log:      10000 us
PHY rate fallback:          100 Mbps
Duration multiplier:        2x expected

Collapse Detection:
  Retry rate threshold:     20.0%
  Avg NAV collapse:         10000 us
  Collision percentage:     10.0%
  Mismatch percentage:      5.0%

Logging Control:
  Log every N mismatches:   1 (1=all, 10=every 10th)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

### Use Preset Profiles

```gdb
# Sensitive - catch more issues (stricter thresholds)
(gdb) tune_sensitive
Thresholds set to SENSITIVE (catch more issues)
  High NAV: 3000 us
  Rate fallback: 150 Mbps
  Retry rate: 15.0%

# Normal - balanced (default)
(gdb) tune_normal
Thresholds set to NORMAL (default)

# Relaxed - fewer false positives (lenient)
(gdb) tune_relaxed
Thresholds set to RELAXED (fewer false positives)
  High NAV: 10000 us
  Rate fallback: 50 Mbps
  Retry rate: 30.0%
```

### Adjust Individual Thresholds

```gdb
# Set high NAV threshold to 8000 us (8ms)
(gdb) set_high_nav 8000
High NAV threshold set to 8000 us

# Set mismatch logging threshold to 15000 us
(gdb) set_mismatch_log 15000
Duration mismatch logging threshold set to 15000 us

# Set rate fallback to 50 Mbps
(gdb) set_rate_fallback 50
PHY rate fallback threshold set to 50 Mbps

# Set duration multiplier (NAV > 3x expected = mismatch)
(gdb) set_multiplier 3
Duration multiplier set to 3x expected

# Log every 10th mismatch (reduce verbosity)
(gdb) set_log_rate 10
Logging every 10 mismatch(es)
```

## Available Thresholds

### Detection Thresholds

| Threshold | Default | What It Does |
|-----------|---------|--------------|
| `threshold_high_nav_us` | 5000 | NAV above this = "high" |
| `threshold_duration_mismatch_us` | 10000 | Log mismatches when NAV exceeds this |
| `threshold_phy_rate_fallback_mbps` | 100 | PHY rate below this = fallback |
| `threshold_duration_multiplier` | 2 | NAV > expected × this = mismatch |

### Collapse Detection Thresholds

| Threshold | Default | What It Does |
|-----------|---------|--------------|
| `threshold_retry_rate_percent` | 20.0 | Retry rate for collapse |
| `threshold_avg_nav_collapse_us` | 10000 | Avg NAV for collapse |
| `threshold_collision_percent` | 10.0 | Collision % for collapse |
| `threshold_mismatch_percent` | 5.0 | Duration mismatch % for collapse |

### Logging Control

| Threshold | Default | What It Does |
|-----------|---------|--------------|
| `log_every_n_mismatches` | 1 | Log every Nth mismatch (1=all) |

## Tuning Examples

### Example 1: Noisy 2.4GHz Environment

Problem: Too many false positives on 2.4GHz

```gdb
# Use relaxed profile
(gdb) tune_relaxed

# Or manually adjust
(gdb) set_high_nav 10000        # 10ms threshold
(gdb) set_rate_fallback 24      # 2.4GHz rates lower
(gdb) set_multiplier 3          # Allow 3x mismatch
(gdb) set_log_rate 10           # Log every 10th
(gdb) continue
```

Now only severe issues trigger alerts.

### Example 2: Clean 5GHz Network

Problem: Want to catch subtle issues

```gdb
# Use sensitive profile
(gdb) tune_sensitive

# Or manually adjust
(gdb) set_high_nav 3000         # 3ms threshold
(gdb) set_rate_fallback 200     # Should stay >200 Mbps
(gdb) set_multiplier 1.5        # Catch 1.5x mismatches
(gdb) set_log_rate 1            # Log everything
(gdb) continue
```

Catches issues early before collapse.

### Example 3: Production Monitoring

Problem: Need to reduce log spam

```gdb
# Keep normal thresholds but reduce logging
(gdb) tune_normal
(gdb) set_log_rate 100          # Log every 100th mismatch
(gdb) set_mismatch_log 20000    # Only log severe (>20ms)
(gdb) continue
```

Statistics still track everything, but logs are cleaner.

### Example 4: Debugging Specific Issue

Problem: Investigating NAV spikes around 7-8ms

```gdb
# Fine-tune for specific range
(gdb) set_high_nav 6000         # Start counting at 6ms
(gdb) set_mismatch_log 7000     # Log anything >7ms
(gdb) set_multiplier 1          # Catch all mismatches
(gdb) set_log_rate 1            # Log everything
(gdb) continue

# Now watch for those specific spikes
```

### Example 5: Live WiFi Load Test

```gdb
# Start with normal
(gdb) tune_normal
(gdb) continue

# Run iperf from another machine
# Watch serial output...

# If too noisy, relax on the fly
(gdb) Ctrl-C
(gdb) set_log_rate 20
(gdb) continue

# If not catching issues, make sensitive
(gdb) Ctrl-C
(gdb) tune_sensitive
(gdb) continue
```

**Tune while testing - no rebuild!**

## Direct Variable Access

You can also set variables directly:

```gdb
# Set variables directly
(gdb) set threshold_high_nav_us = 7500
(gdb) set threshold_phy_rate_fallback_mbps = 75
(gdb) set log_every_n_mismatches = 5

# Or use C-style
(gdb) print threshold_high_nav_us = 7500
$1 = 7500
```

## Monitor Effects in Real-Time

```gdb
# Set thresholds
(gdb) tune_sensitive
(gdb) continue

# Watch serial monitor in other terminal
# See immediate effect on logging

# If too verbose
(gdb) Ctrl-C
(gdb) set_log_rate 10
(gdb) continue

# Logs immediately reduced by 10x!
```

## Preset Profile Comparison

### Sensitive Profile

```
High NAV:         3000 us   (stricter)
Mismatch log:     5000 us
Rate fallback:    150 Mbps  (higher)
Multiplier:       1.5x      (catches more)
Retry rate:       15.0%     (lower)
Avg NAV collapse: 5000 us
Collision %:      5.0%
Mismatch %:       3.0%
```

**Use for**: Clean networks, early issue detection, debugging

### Normal Profile (Default)

```
High NAV:         5000 us   (balanced)
Mismatch log:     10000 us
Rate fallback:    100 Mbps
Multiplier:       2x
Retry rate:       20.0%
Avg NAV collapse: 10000 us
Collision %:      10.0%
Mismatch %:       5.0%
```

**Use for**: General monitoring, production

### Relaxed Profile

```
High NAV:         10000 us  (lenient)
Mismatch log:     20000 us
Rate fallback:    50 Mbps   (lower)
Multiplier:       3x         (allows more)
Retry rate:       30.0%      (higher)
Avg NAV collapse: 15000 us
Collision %:      15.0%
Mismatch %:       10.0%
```

**Use for**: Noisy environments, 2.4GHz, reduce false positives

## Tips & Best Practices

### 1. Start Conservative, Tune Down

```gdb
# Start sensitive to see what's happening
(gdb) tune_sensitive
(gdb) continue

# If too noisy, relax specific thresholds
(gdb) Ctrl-C
(gdb) set_log_rate 10
(gdb) continue

# Still too noisy? Adjust threshold
(gdb) Ctrl-C
(gdb) set_high_nav 8000
(gdb) continue
```

### 2. Use Logging Rate Control

```gdb
# Keep all detection active but reduce log spam
(gdb) tune_normal
(gdb) set_log_rate 20          # Log every 20th
(gdb) continue

# Statistics still count everything!
# Periodic stats show full picture
```

### 3. Match Band Characteristics

```gdb
# 2.4GHz - lower rates, more interference
(gdb) set_rate_fallback 24
(gdb) set_high_nav 8000

# 5GHz - higher rates, cleaner
(gdb) set_rate_fallback 100
(gdb) set_high_nav 5000
```

### 4. Experiment Live

```gdb
# Change settings while monitoring
(gdb) continue
# ... let it run ...
(gdb) Ctrl-C
(gdb) set_mismatch_log 15000
(gdb) continue
# ... see effect immediately ...
```

### 5. Save Custom Profiles

Create your own `.gdbinit` commands:

```gdb
# Add to .gdbinit
define tune_my_network
  set threshold_high_nav_us = 6500
  set threshold_phy_rate_fallback_mbps = 120
  set log_every_n_mismatches = 5
  printf "Custom profile loaded\n"
end
```

Then use:

```gdb
(gdb) tune_my_network
```

## Performance Impact

**Zero!** Threshold changes have no performance impact:

- ✅ Variables are checked per frame (already happening)
- ✅ No function calls added
- ✅ No memory allocation
- ✅ Still processes 10,000+ frames/sec

## Troubleshooting

### Thresholds Not Taking Effect

```gdb
# Verify threshold was set
(gdb) print threshold_high_nav_us
$1 = 8000

# Check spelling
(gdb) show_thresholds
```

### Too Much Logging

```gdb
# Reduce log rate
(gdb) set_log_rate 50          # Log every 50th

# Or increase mismatch threshold
(gdb) set_mismatch_log 20000   # Only log >20ms
```

### Not Catching Issues

```gdb
# Make more sensitive
(gdb) tune_sensitive

# Or lower specific threshold
(gdb) set_high_nav 3000
```

## Example Session

Complete workflow:

```bash
# Start debugging
$ idf.py gdb

# Check current settings
(gdb) show_thresholds

# Start monitoring
(gdb) continue

# Run iperf from another machine
# Watch serial output...

# Too many logs? Adjust
(gdb) Ctrl-C
(gdb) set_log_rate 10
(gdb) continue

# Not catching subtle issues? Make sensitive
(gdb) Ctrl-C
(gdb) tune_sensitive
(gdb) continue

# Perfect! Check final settings
(gdb) Ctrl-C
(gdb) show_thresholds
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WiFi Monitor Thresholds (GDB-tunable)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
High NAV threshold:         3000 us
Duration mismatch log:      5000 us
PHY rate fallback:          150 Mbps
Duration multiplier:        1.5x expected
...
Log every N mismatches:     10
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Document these settings for your network!
```

## Summary

| Feature | Benefit |
|---------|---------|
| **Runtime tuning** | No rebuild needed |
| **GDB commands** | Easy to use |
| **Preset profiles** | Quick adjustment |
| **Zero overhead** | Full C code speed |
| **Live testing** | Tune while running |
| **Experiment freely** | Try different settings |

**Perfect combination of speed and flexibility!** 🎯

---

**Key Commands**:
- `show_thresholds` - See current settings
- `tune_sensitive` / `tune_normal` / `tune_relaxed` - Preset profiles
- `set_high_nav <us>` - Adjust high NAV threshold
- `set_log_rate <n>` - Control logging verbosity
- `continue` - Resume monitoring with new settings