Development Guide

This guide covers all aspects of developing with the ESP32 Template, from setting up your environment to debugging and testing.

Development Topics:

• Development Container Setup
  • Development Options
  • Using the Dev Container
  • Container Features
  • Build Commands in Container
  • Hardware Flashing
  • Benefits
  • Container Configuration
  • Troubleshooting
• GUI and Graphics Development
  • Overview
  • Architecture
  • Accessing the Desktop
  • VNC Setup Details
  • Running GUI Applications
  • Developing Custom GUI Applications
  • Troubleshooting
  • Best Practices
  • Use Cases
  • Integration with VS Code
  • Advanced Configuration
  • References
  • See Also
• QEMU Emulator Guide
  • Quick Start
  • Architecture Overview
  • Network Configuration
  • How It Works
  • Testing Network Connectivity
  • Troubleshooting
  • Advanced Usage
  • Technical Deep Dive
  • Known Limitations
  • Next Steps
• Web-Based Firmware Flashing
  • Overview
  • Quick Start
  • Features
  • Browser Requirements
  • Usage Guide
  • Architecture
  • Troubleshooting
  • References
  • See Also
• Debugging Guide
  • Quick Start: Debugging in QEMU
  • Debugging Features
  • Hardware Debugging
  • Debug Configuration
  • Advanced Debugging
  • Common Debugging Scenarios
  • Troubleshooting
  • Tips and Best Practices
  • Resources
  • Next Steps
• QEMU Network Internals
  • Architecture Overview
  • Frame Format
  • Initialization Sequence
  • Packet Flow
  • Critical Implementation Details
  • Performance Characteristics
  • Debugging Network Issues
  • Known Issues and Limitations
  • Source Code Reference
  • Further Reading
• Known Issues and Limitations
  • HTTPS Support
  • DNS Captive Portal
  • Contributing

Getting Started

Recommended: GitHub Codespaces

The fastest way to start developing:

1. Click “Use this template” to create your repository

2. Open in GitHub Codespaces (Code → Codespaces → Create)

3. Wait for container to build (first time only, ~2 minutes)

4. Start coding in main/main.c

Testing Without Hardware

Use QEMU emulation:

# Build the project
idf.py build

# Run in QEMU with network support
./tools/run-qemu-network.sh

# Debug in QEMU
# Press F5 in VS Code or use Debug panel

Flashing Real Hardware

When you have physical ESP32:

# Build the project
idf.py build

# Flash and monitor (replace /dev/ttyUSB0 with your port)
idf.py -p /dev/ttyUSB0 flash monitor

# Exit monitor: Press Ctrl+]

Development Workflow

Typical development cycle:

# 1. Customize application
vim main/main.c

# 2. Build
idf.py build

# 3. Test in QEMU (optional)
./tools/run-qemu-network.sh

# 4. Flash to hardware
idf.py -p /dev/ttyUSB0 flash monitor

Template Benefits

• Consistent Environment: Same toolchain everywhere (Codespaces, Docker, CI/CD)

• ESP-IDF v5.4.1: Latest stable version pre-configured

• QEMU Support: Test without hardware using full network emulation

• GDB Debugging: Full breakpoint debugging in emulator

• Web Interface: Access emulated web server via browser

• Documentation: Professional requirements engineering with Sphinx-Needs

Next Steps

• New to dev containers? Start with Development Container Setup

• Want to debug? Check out Debugging Guide

• Curious about QEMU networking? See QEMU Emulator Guide

• Need technical details? Read QEMU Network Internals

Known Issues

Note

ESP-IDF-WEB extension doesn’t automatically install in Codespaces. Please search for “ESP-IDF Web” in the VS Code marketplace and install it manually.