Development Environment
This section covers all aspects of developing the ESP32 Distance Sensor project, from setting up your environment to debugging and testing.
Quick Links
- Dev Container Setup - GitHub Codespaces and local Docker development
- QEMU Emulator - Running the project in QEMU with network support
- Debugging - GDB debugging with QEMU and VS Code
- Network Internals - Deep dive into QEMU IP tunnel implementation
- Pre-commit Hooks - Automated quality checks and documentation validation
Getting Started
Recommended: GitHub Codespaces (Cloud)
The fastest way to start developing:
- Open the repository in GitHub Codespaces
- Wait for container to build (first time only)
- Run QEMU:
./tools/run-qemu-network.sh - Start debugging with F5 or access the web interface
Alternative: Local Dev Container
For offline development or custom hardware:
- Install Docker Desktop
- Open project in VS Code
- "Reopen in Container" when prompted
- Connect hardware via USB (see Dev Container Setup)
Development Workflow
# Build the project
idf.py build
# Flash to hardware (hardware mode)
idf.py -p /dev/ttyUSB0 flash monitor
# Run in emulator (emulator mode)
./tools/run-qemu-network.sh
# Debug in emulator
# Press F5 in VS Code or use Debug panel
Key Features
- 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
- Quality Gates: Pre-commit hooks validate documentation and code before commits
Next Steps
- New to dev containers? Start with Dev Container Setup
- Want to debug? Check out Debugging Guide
- Curious about QEMU networking? See QEMU Emulator
- Need technical details? Read Network Internals
- Setting up quality checks? See Pre-commit Hooks
Known Issues
Unfortunately ESP-IDF-WEB doesn't automatically install. please search the extension in the marketplace and install it.