# ESP32-C5 GDB Debugging Guide - Update Summary

## What's New

The GDB Debugging Guide has been updated to include comprehensive WiFi Monitor Mode debugging features from the `feature/wifi-monitor-mode` branch.

## Major Additions

### 1. WiFi Monitor Mode Section
- **802.11 Frame Capture**: Debug WiFi at the packet level
- **Component Architecture**: Explanation of wifi_monitor component structure
- **Branch Setup**: Instructions for checking out feature/wifi-monitor-mode
- **Starting Debug Sessions**: WiFi-specific debugging workflow

### 2. Frame Analysis Section
- **Frame Callback Breakpoints**: How to inspect captured frames
- **show_frame_full Command**: Detailed frame information display
- **Frame Structure Breakdown**: Complete table of accessible fields
- **Conditional Breakpoints**: Examples for WiFi-specific debugging
  - High NAV detection
  - Retry frame detection  
  - Collision detection

### 3. Runtime Threshold Tuning Section
- **Tunable Thresholds Table**: All 9 configurable parameters
- **GDB Commands**: 
  - `show_thresholds` - Display current settings
  - `tune_sensitive` / `tune_normal` / `tune_relaxed` - Preset profiles
  - `set_high_nav`, `set_rate_fallback`, etc. - Individual adjustments
- **Real-World Tuning Examples**:
  - Noisy 2.4GHz environment
  - Clean 5GHz network
  - Production monitoring
- **No Rebuild Required**: Emphasizes live tuning capability

### 4. Duration Analysis Section
- **Duration Calculation**: Formula breakdown
- **GDB Commands**:
  - `show_duration` - Quick comparison
  - `watch_data` - Monitor DATA frames
  - `find_mismatch` - Auto-break on anomalies
- **Interpretation Table**: What different NAV mismatches mean
- **WiFi Collapse Examples**: Normal vs collapsed network

### 5. Enhanced Strategies Section
- **WiFi Collapse Investigation Workflow**: Step-by-step process
- **Best Practices**:
  - Threshold tuning guidelines
  - Frame analysis tips
  - Performance monitoring advice

### 6. Updated Examples Section
- **Example 1**: Debugging Rate Fallback
- **Example 2**: Finding Collision Hotspots
- **Example 3**: Tuning for 2.4GHz vs 5GHz

### 7. Enhanced Troubleshooting
- GDB commands not found (auto-load .gdbinit)
- Compilation errors (ESP-IDF v6.0 compatibility)
- No frames captured
- Too much logging

### 8. Advanced Techniques
- Creating custom .gdbinit profiles
- Logging frame data to file
- Combining multiple conditions
- Performance comparison: C code vs GDB

### 9. Updated Resources Section
- Git repository with branch info
- Key files in the project
- Documentation files list
- Quick reference command table

## Header Updates

- Added **WiFi Monitor Mode Edition** subtitle
- Added **Git Branch** information: `feature/wifi-monitor-mode`
- Updated tools versions:
  - GDB 16.3_20250913 (September 2024)
  - OpenOCD v0.12.0-esp32-20250707 (July 2025)
- Added dual-band WiFi 6 specification

## Table of Contents Updates

New entries added:
- WiFi Monitor Mode Debugging
- 802.11 Frame Analysis
- Runtime Threshold Tuning
- Duration Analysis

## Visual Enhancements

- Added `.git-branch` style for repository information display
- Added `.feature-box` style for highlighted feature sections
- Maintained teal color scheme throughout

## Command Tables

### New Quick Reference Table

| Command | Purpose |
|---------|---------|
| `show_thresholds` | Display current thresholds |
| `tune_sensitive` | Strict thresholds (catch more) |
| `tune_normal` | Default balanced settings |
| `tune_relaxed` | Lenient thresholds (fewer alerts) |
| `set_high_nav <us>` | Set high NAV threshold |
| `set_rate_fallback <mbps>` | Set rate fallback threshold |
| `set_log_rate <n>` | Log every Nth mismatch |
| `show_frame_full` | Complete frame analysis |
| `show_duration` | Quick duration comparison |
| `watch_data` | Monitor DATA frames |
| `find_mismatch` | Auto-break on NAV mismatches |

### Threshold Variables Table

Complete documentation of all 9 tunable thresholds with defaults and purposes.

### Duration Interpretation Table

Guidance on what different NAV mismatch values mean (normal, warning, critical).

### Performance Comparison Table

C code vs GDB breakpoints vs GDB threshold tuning speeds and use cases.

## File Location

**Updated Guide**: `ESP32-C5_GDB_Debugging_Guide_Updated.html`

## Installation

Replace your existing guide:

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

# Copy to project root or docs directory
cp ESP32-C5_GDB_Debugging_Guide_Updated.html docs/

# Or rename to replace original
mv ESP32-C5_GDB_Debugging_Guide_Updated.html ESP32-C5_GDB_Debugging_Guide.html
```

## Key Messages

1. **WiFi Monitor Mode**: Real-time 802.11 frame capture and analysis
2. **Runtime Tuning**: Adjust detection thresholds without rebuilding
3. **Best of Both Worlds**: C code performance + GDB flexibility
4. **Production Ready**: 10,000+ frames/sec with live tuning capability
5. **Git Branch**: All code in `feature/wifi-monitor-mode` branch

## Content Size

- **Original Guide**: ~950 lines
- **Updated Guide**: ~1,400 lines  
- **New Content**: ~450 lines of WiFi monitor documentation

## Completeness

The updated guide now includes:
- ✅ All original GDB debugging content
- ✅ WiFi monitor mode implementation details
- ✅ Complete threshold tuning documentation
- ✅ Duration analysis examples
- ✅ Real-world WiFi debugging workflows
- ✅ Git branch and repository information
- ✅ Tool version specifications
- ✅ Troubleshooting for ESP-IDF v6.0
- ✅ Performance comparisons
- ✅ Quick reference tables

Perfect for both GDB beginners and advanced WiFi debugging! 🎯