5.7 KiB

Raw Blame History

ESP32-C5 GDB Debugging Guide - README

Two versions of the comprehensive GDB debugging guide have been created:

Files

ESP32-C5_GDB_Debugging_Guide.md - Markdown version
- Perfect for GitHub, documentation sites, or conversion to other formats
- Clean, portable, works everywhere
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:

Introduction - ESP32-C5 overview and debugging benefits
Why GDB? - Comparison with printf debugging
Hardware Capabilities - Built-in USB-JTAG features
Prerequisites - Required software and hardware
Building with Debug Symbols - Step-by-step configuration
Starting Debug Session - Three-step process (flash, OpenOCD, GDB)
Essential Commands - Comprehensive GDB command reference
Debugging Strategies - Five proven strategies
Real-World Examples - Five complete debugging scenarios:
- CSI configuration failure (your actual problem!)
- Memory corruption detection
- WiFi connection troubleshooting
- Performance profiling
- Stack overflow debugging
Troubleshooting - Common problems and solutions
Advanced Techniques - Scripting, FreeRTOS, live modification
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

# 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

# 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

# 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:

: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>:

<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>:

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

This guide could be part of a series:

✅ GDB Debugging Guide (this document)
ESP32-C5 WiFi 6 Programming Guide
CSI Data Analysis Tutorial
iperf WiFi Analyzer Usage Guide
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

Review both versions
Customize branding/colors
Test HTML in browser
Publish to your website
Share with ESP32 community
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)

5.7 KiB Raw Blame History