175 lines
5.5 KiB
Markdown
175 lines
5.5 KiB
Markdown
# 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! 🎯
|