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

6.8 KiB
Raw Blame History

Publishing the Updated GDB Debugging Guide

Files Created

  1. ESP32-C5_GDB_Debugging_Guide_Updated.html - Complete updated guide with WiFi monitor mode
  2. GDB_GUIDE_UPDATE_SUMMARY.md - Summary of what changed

Quick Publish

cd ~/Code/esp32/esp32-iperf

# Option 1: Add to docs directory
mkdir -p docs
cp ESP32-C5_GDB_Debugging_Guide_Updated.html docs/ESP32-C5_GDB_Debugging_Guide.html

# Option 2: Replace in project root
cp ESP32-C5_GDB_Debugging_Guide_Updated.html ESP32-C5_GDB_Debugging_Guide.html

# Commit to git
git add ESP32-C5_GDB_Debugging_Guide.html
git add docs/ 
git commit -m "Update GDB guide with WiFi monitor mode debugging features

- Added WiFi monitor mode debugging section
- Added runtime threshold tuning documentation
- Added 802.11 frame analysis examples
- Added duration analysis guide
- Updated with git branch info (feature/wifi-monitor-mode)
- Added GDB command reference tables
- Enhanced troubleshooting section
"

git push origin feature/wifi-monitor-mode

Update README.md

Add to your project's README.md:

## GDB Debugging Guide

Comprehensive guide for debugging ESP32-C5 WiFi applications using GDB:

📖 **[ESP32-C5 GDB Debugging Guide](./ESP32-C5_GDB_Debugging_Guide.html)** - Open in browser

### Features
- WiFi Monitor Mode debugging
- Runtime threshold tuning (no rebuild needed!)
- 802.11 frame analysis
- Duration analysis and collapse detection
- Step-by-step examples

### Quick Start
\`\`\`bash
# Checkout WiFi monitor branch
git checkout feature/wifi-monitor-mode

# Start debugging
idf.py openocd          # Terminal 1
idf.py gdb              # Terminal 2

# In GDB
(gdb) show_thresholds   # View settings
(gdb) tune_sensitive    # Adjust thresholds
(gdb) continue          # Start monitoring
\`\`\`

GitHub Pages Publishing (Optional)

If you want to publish as a website:

# Create gh-pages branch
git checkout --orphan gh-pages
git rm -rf .
git checkout feature/wifi-monitor-mode -- ESP32-C5_GDB_Debugging_Guide.html
mv ESP32-C5_GDB_Debugging_Guide.html index.html

# Commit and push
git add index.html
git commit -m "Publish GDB debugging guide"
git push origin gh-pages

# Enable in GitHub repo settings:
# Settings → Pages → Source: gh-pages branch

# Your guide will be at:
# https://yourusername.github.io/esp32-iperf/

Share With Team

Internal Wiki/Confluence

  1. Open ESP32-C5_GDB_Debugging_Guide_Updated.html in browser
  2. Save as PDF (Ctrl+P → Save as PDF)
  3. Upload to your wiki

Email

Subject: New GDB Debugging Guide - WiFi Monitor Mode

Team,

I've created a comprehensive GDB debugging guide for our ESP32-C5 WiFi development:

📖 ESP32-C5 GDB Debugging Guide - WiFi Monitor Mode Edition

Key Features:
✅ Real-time 802.11 frame capture and analysis
✅ Runtime threshold tuning (no rebuild!)  
✅ Duration analysis and WiFi collapse detection
✅ Step-by-step debugging workflows

Location: feature/wifi-monitor-mode branch
File: ESP32-C5_GDB_Debugging_Guide.html

The guide includes:
- Complete WiFi monitor mode documentation
- GDB command reference (show_thresholds, tune_sensitive, etc.)
- Real-world debugging examples
- Troubleshooting section

Try it out and let me know what you think!

-Bob

Social Media/Blog

Twitter/X Post

🎯 New: ESP32-C5 GDB Debugging Guide

Debug WiFi at the packet level with GDB!

✅ 802.11 frame analysis
✅ Runtime threshold tuning
✅ WiFi collapse detection
✅ No rebuild needed!

10,000+ frames/sec with full GDB control

#ESP32 #RISCV #WiFi6 #EmbeddedSystems

[Link to guide]

Blog Post Template

# Debugging ESP32-C5 WiFi with GDB: A Complete Guide

I've just released a comprehensive guide for debugging ESP32-C5 WiFi applications using GDB. This isn't your typical "printf debugging" – we're talking real-time 802.11 frame analysis and runtime parameter tuning.

## What Makes This Different?

- **WiFi Monitor Mode**: Capture and analyze every 802.11 frame
- **Runtime Tuning**: Adjust detection thresholds via GDB without rebuilding
- **Best of Both Worlds**: C code performance (10,000+ frames/sec) + GDB flexibility

## Key Features

### 802.11 Frame Analysis
Inspect WiFi frames in GDB with full MAC header details:
- NAV (Network Allocation Vector)
- Retry bits
- PHY rates
- MAC addresses
- Frame types

### Duration Analysis
Compare expected vs actual frame duration to detect WiFi problems:

DATA: 1500 bytes @ 433.5 Mbps → Expected 71 us, NAV 68 us (-3) ✅ Healthy DATA: 1200 bytes @ 54.0 Mbps → Expected 222 us, NAV 32000 us (+31778) 🚨 Collapse!


### Runtime Threshold Tuning
Change detection parameters live:
```gdb
(gdb) show_thresholds     # View current settings
(gdb) tune_sensitive      # Catch more issues
(gdb) set_log_rate 10     # Reduce verbosity
(gdb) continue            # Changes take effect immediately!

No rebuild. No reflash. Just instant tuning.

Get Started

  1. Clone the repo: https://github.com/yourusername/esp32-iperf
  2. Checkout: git checkout feature/wifi-monitor-mode
  3. Open the guide: ESP32-C5_GDB_Debugging_Guide.html

Perfect for WiFi developers working with ESP32-C5!

[Read the full guide →]


## Documentation Site

If using Sphinx/MkDocs:

```bash
# Add to docs/source/index.rst
.. toctree::
   :maxdepth: 2
   
   ESP32-C5_GDB_Debugging_Guide

# Build docs
make html

Customization

Replace placeholder in guide before publishing:

  1. GitHub URL: Change https://github.com/yourusername/esp32-iperf to your actual repo
  2. Branch Name: Verify feature/wifi-monitor-mode is correct
  3. Author Info: Update if needed
  4. Tool Versions: Verify GDB/OpenOCD versions match your setup
# Quick search and replace
sed -i 's/yourusername/your-actual-username/g' ESP32-C5_GDB_Debugging_Guide_Updated.html

Verification

Before publishing, verify:

# Open in browser
firefox ESP32-C5_GDB_Debugging_Guide_Updated.html

# Check:
☐ All links work
☐ Code examples are correct
☐ Tables render properly
☐ Git branch name is correct
☐ GitHub URL is correct
☐ Teal color scheme looks good
☐ Mobile-responsive (resize browser)

Version Control

Tag the release:

git tag -a gdb-guide-v2.0 -m "GDB Guide v2.0 - WiFi Monitor Mode Edition"
git push origin gdb-guide-v2.0

Feedback

Encourage users to provide feedback:

## Feedback

Found an issue or have suggestions? 

- Open an issue: https://github.com/yourusername/esp32-iperf/issues
- Email: your.email@example.com
- Discussion: [Link to forum/Discord]

Summary

The updated guide is production-ready and includes:

✅ Complete WiFi monitor mode documentation
✅ Runtime threshold tuning
✅ Duration analysis
✅ Git branch information
✅ Real-world examples
✅ Troubleshooting
✅ Quick reference tables

Ready to help your team debug WiFi like pros! 🎯