289 lines
6.8 KiB
Markdown
289 lines
6.8 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
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:
|
||
|
||
```markdown
|
||
## 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:
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```markdown
|
||
# 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
|
||
|
||
```bash
|
||
# Quick search and replace
|
||
sed -i 's/yourusername/your-actual-username/g' ESP32-C5_GDB_Debugging_Guide_Updated.html
|
||
```
|
||
|
||
## Verification
|
||
|
||
Before publishing, verify:
|
||
|
||
```bash
|
||
# 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:
|
||
|
||
```bash
|
||
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:
|
||
|
||
```markdown
|
||
## 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! 🎯
|