223 lines
5.7 KiB
Markdown
223 lines
5.7 KiB
Markdown
# ESP32-C5 GDB Debugging Guide - README
|
|
|
|
Two versions of the comprehensive GDB debugging guide have been created:
|
|
|
|
## Files
|
|
|
|
1. **ESP32-C5_GDB_Debugging_Guide.md** - Markdown version
|
|
- Perfect for GitHub, documentation sites, or conversion to other formats
|
|
- Clean, portable, works everywhere
|
|
|
|
2. **ESP32-C5_GDB_Debugging_Guide.html** - HTML version
|
|
- Professional web-ready format with styling
|
|
- Responsive design (mobile-friendly)
|
|
- Direct upload to website
|
|
|
|
## Content Overview
|
|
|
|
### Complete Coverage:
|
|
|
|
1. **Introduction** - ESP32-C5 overview and debugging benefits
|
|
2. **Why GDB?** - Comparison with printf debugging
|
|
3. **Hardware Capabilities** - Built-in USB-JTAG features
|
|
4. **Prerequisites** - Required software and hardware
|
|
5. **Building with Debug Symbols** - Step-by-step configuration
|
|
6. **Starting Debug Session** - Three-step process (flash, OpenOCD, GDB)
|
|
7. **Essential Commands** - Comprehensive GDB command reference
|
|
8. **Debugging Strategies** - Five proven strategies
|
|
9. **Real-World Examples** - Five complete debugging scenarios:
|
|
- CSI configuration failure (your actual problem!)
|
|
- Memory corruption detection
|
|
- WiFi connection troubleshooting
|
|
- Performance profiling
|
|
- Stack overflow debugging
|
|
10. **Troubleshooting** - Common problems and solutions
|
|
11. **Advanced Techniques** - Scripting, FreeRTOS, live modification
|
|
12. **Resources** - Links to official docs and community
|
|
|
|
## Key Features
|
|
|
|
- ✅ **Based on your actual ESP32-C5 experience**
|
|
- ✅ **Real debugging examples from CSI issues**
|
|
- ✅ **Complete command reference**
|
|
- ✅ **Troubleshooting guide**
|
|
- ✅ **Professional web design** (HTML version)
|
|
- ✅ **Ready to publish**
|
|
|
|
## Publishing Options
|
|
|
|
### Option 1: GitHub Pages
|
|
```bash
|
|
# Add to your GitHub repo docs/
|
|
git add ESP32-C5_GDB_Debugging_Guide.md
|
|
git commit -m "Add GDB debugging guide"
|
|
git push
|
|
```
|
|
|
|
### Option 2: Direct Website Upload
|
|
```bash
|
|
# Upload the HTML file to your web server
|
|
scp ESP32-C5_GDB_Debugging_Guide.html user@yoursite.com:/var/www/html/
|
|
```
|
|
|
|
### Option 3: Static Site Generator
|
|
```bash
|
|
# The markdown works with Jekyll, Hugo, MkDocs, etc.
|
|
cp ESP32-C5_GDB_Debugging_Guide.md docs/
|
|
# Build your static site
|
|
```
|
|
|
|
## Customization
|
|
|
|
### HTML Styling
|
|
|
|
The HTML version includes CSS in the `<style>` section. To customize:
|
|
|
|
```css
|
|
:root {
|
|
--primary-color: #0e7490; /* Teal accent */
|
|
--secondary-color: #357edd; /* Blue links */
|
|
--bg-color: #f9f9f9; /* Background */
|
|
}
|
|
```
|
|
|
|
Change these colors to match your website theme.
|
|
|
|
### Branding
|
|
|
|
Update footer section with your info:
|
|
- Website URL
|
|
- Contact information
|
|
- Additional projects
|
|
- Social media links
|
|
|
|
### Content
|
|
|
|
Feel free to:
|
|
- Add your specific hardware setup
|
|
- Include project-specific examples
|
|
- Add screenshots/diagrams
|
|
- Link to your iperf2 documentation
|
|
|
|
## SEO Optimization (HTML version)
|
|
|
|
Consider adding to `<head>`:
|
|
|
|
```html
|
|
<meta name="description" content="Complete guide to GDB debugging on ESP32-C5 with real-world WiFi driver examples">
|
|
<meta name="keywords" content="ESP32-C5, GDB, debugging, RISC-V, WiFi, CSI, iperf">
|
|
<meta name="author" content="Bob McMahon">
|
|
|
|
<!-- Open Graph for social sharing -->
|
|
<meta property="og:title" content="ESP32-C5 GDB Debugging Guide">
|
|
<meta property="og:description" content="Professional guide to debugging ESP32-C5 firmware">
|
|
<meta property="og:type" content="article">
|
|
```
|
|
|
|
## Analytics (Optional)
|
|
|
|
Add Google Analytics to HTML version in `<head>`:
|
|
|
|
```html
|
|
<!-- Google Analytics -->
|
|
<script async src="https://www.googletagmanager.com/gtag/js?id=YOUR-GA-ID"></script>
|
|
<script>
|
|
window.dataLayer = window.dataLayer || [];
|
|
function gtag(){dataLayer.push(arguments);}
|
|
gtag('js', new Date());
|
|
gtag('config', 'YOUR-GA-ID');
|
|
</script>
|
|
```
|
|
|
|
## License
|
|
|
|
Consider adding a license. Suggested Creative Commons:
|
|
|
|
```
|
|
This work is licensed under CC BY 4.0
|
|
(Attribution 4.0 International)
|
|
```
|
|
|
|
## Maintenance
|
|
|
|
### Update Checklist:
|
|
- [ ] ESP-IDF version updates
|
|
- [ ] New debugging techniques discovered
|
|
- [ ] Additional real-world examples
|
|
- [ ] Community feedback/corrections
|
|
- [ ] New ESP32-C5 features
|
|
|
|
### Version History:
|
|
- v1.0 (Dec 2025): Initial release
|
|
- Based on ESP32-C5 CSI debugging experience
|
|
- Complete command reference
|
|
- Five real-world examples
|
|
|
|
## Feedback
|
|
|
|
Encourage readers to:
|
|
- Report errors or outdated info
|
|
- Suggest improvements
|
|
- Share their own debugging experiences
|
|
- Contribute examples
|
|
|
|
## Related Content Ideas
|
|
|
|
This guide could be part of a series:
|
|
1. ✅ **GDB Debugging Guide** (this document)
|
|
2. ESP32-C5 WiFi 6 Programming Guide
|
|
3. CSI Data Analysis Tutorial
|
|
4. iperf WiFi Analyzer Usage Guide
|
|
5. ESP32-C5 vs ESP32-S3 Comparison
|
|
|
|
## Technical Details
|
|
|
|
### Markdown Features Used:
|
|
- Tables
|
|
- Code blocks with syntax highlighting
|
|
- Nested lists
|
|
- Emphasis (bold, italic)
|
|
- Links
|
|
- Headers (h1-h3)
|
|
|
|
### HTML Features:
|
|
- Responsive design (mobile-friendly)
|
|
- CSS Grid/Flexbox layout
|
|
- Syntax highlighting styles
|
|
- Alert boxes (info, success, warning)
|
|
- Jump-to-section navigation
|
|
- Accessible markup
|
|
|
|
### Browser Compatibility:
|
|
- Chrome/Edge ✅
|
|
- Firefox ✅
|
|
- Safari ✅
|
|
- Mobile browsers ✅
|
|
|
|
## File Sizes
|
|
|
|
- Markdown: ~50 KB
|
|
- HTML: ~80 KB (includes embedded CSS)
|
|
|
|
Both are lightweight and fast to load.
|
|
|
|
## Next Steps
|
|
|
|
1. **Review** both versions
|
|
2. **Customize** branding/colors
|
|
3. **Test** HTML in browser
|
|
4. **Publish** to your website
|
|
5. **Share** with ESP32 community
|
|
6. **Update** based on feedback
|
|
|
|
## Questions?
|
|
|
|
Both versions are production-ready. The content is comprehensive, accurate, and based on your real debugging experience with the ESP32-C5 CSI issues.
|
|
|
|
---
|
|
|
|
**Files created:**
|
|
- `ESP32-C5_GDB_Debugging_Guide.md` (50 KB)
|
|
- `ESP32-C5_GDB_Debugging_Guide.html` (80 KB)
|
|
- `GDB_GUIDE_README.md` (this file)
|