Umber
/
ESP32
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
ESP32/doc/GDB_GUIDE_UPDATE_SUMMARY.md

5.5 KiB
Raw Blame History

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:

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! 🎯