11 KiB

Raw Permalink Blame History

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

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

# Terminal 1: OpenOCD
idf.py openocd

# Terminal 2: GDB
idf.py gdb

Quick Start

View Current Thresholds

(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

# 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

# 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

# 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

# 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

# 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

# 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

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

# 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

# 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

# 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

# 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

# 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

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

# 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) 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

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

# Check spelling
(gdb) show_thresholds

Too Much Logging

# 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

# Make more sensitive
(gdb) tune_sensitive

# Or lower specific threshold
(gdb) set_high_nav 3000

Example Session

Complete workflow:

# 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

11 KiB Raw Permalink Blame History Unescape Escape