AVR DevContainer Project

Professional containerized AVR development environment with comprehensive build system and testing framework.

Features

• 🐳 DevContainer: Fully containerized development environment
• 🏗️ Dual Build System: CMake for firmware + Ceedling for testing
• 🧪 Unit Testing: CMock/Unity framework with hardware abstraction mocking
• 📊 Code Coverage: LLVM-based coverage analysis with detailed reporting
• 💡 IntelliSense: Advanced code navigation with clangd configuration
• 🔌 USB Programming: Direct AVR device programming from container
• 📁 Professional Structure: Clean separation of firmware and test code

Prerequisites

• Docker Desktop with WSL2 backend
• Cursor or VS Code with Dev Containers extension
• usbipd-win for USB forwarding

Setup

1. USB Device Setup (One-time)

# Install usbipd-win
winget install usbipd

# Share your AVR programmer (as Administrator)
usbipd list
usbipd bind --busid <BUSID>

2. Before Each Session

# Attach USB device to WSL
usbipd attach --wsl --busid <BUSID>

3. Open Project

1. Open project in Cursor
2. Click "Reopen in Container" when prompted
3. Container builds automatically

Project Structure

avr-dev-container/
├── firmware/                   # Firmware source code
│   ├── src/
│   │   ├── main.c             # Application entry point
│   │   ├── led.c              # LED control module
│   │   └── hardware_interface.c # Hardware abstraction layer
│   └── include/
│       ├── led.h              # LED module interface
│       └── hardware_interface.h # Hardware abstraction interface
├── test/                       # Unit testing
│   ├── unit/
│   │   └── test_led.c         # LED module unit tests
│   └── support/
│       └── avr_io.h           # AVR header mocks
├── toolchain/                  # CMake toolchain configurations
│   ├── avr.cmake              # AVR-GCC toolchain setup
│   └── test.cmake             # Host compiler toolchain for testing
├── .devcontainer/              # DevContainer setup
│   ├── devcontainer.json      # Container configuration
│   ├── Dockerfile             # Container image definition
│   └── setup-git.sh           # Git configuration script
├── .github/                    # GitHub Actions CI/CD
│   └── workflows/
│       └── ci.yml             # Continuous integration pipeline
├── build/                      # AVR firmware build artifacts (generated)
├── build-test/                 # Test build artifacts (generated)
│   └── mocks/                 # Auto-generated CMock files
├── CMakeLists.txt             # Main build configuration
├── CMakePresets.json          # Build presets for AVR and testing
├── project.yml                # Ceedling test configuration
├── LICENSE                    # Project license
└── README.md                  # Project documentation

Usage

Build Firmware

cmake --preset avr
cmake --build build

Program Device

cmake --build build --target firmware-upload

Unit Tests

# Run all tests
ceedling test:all

# Run specific test
ceedling test:test_led

# Clean test artifacts
ceedling clean

Code Coverage Analysis

# Generate coverage report
ceedling gcov:all

# Display coverage summary (custom script)
./scripts/coverage_summary.sh

# Clean coverage files
./scripts/clean_coverage.sh

# View detailed coverage data
find build-test/gcov/out/test_led -name "*.gcov" -exec cat {} \;

Coverage File Organization:

• Coverage Data: build-test/gcov/out/test_led/
• Generated Reports: build-test/artifacts/gcov/
• Cleanup Script: scripts/clean_coverage.sh
• Summary Script: scripts/coverage_summary.sh

Current Coverage Results:

• Source Code: 100% line coverage (15/15 lines)
• Test Code: 100% line coverage (34/34 lines)

Clean Build

# Clean AVR build artifacts
cmake --build build --target clean

# Clean everything (custom target)
cmake --build build --target clean-all

Build System Features

AVR Firmware Build

• Toolchain: AVR-GCC with optimized settings for ATmega328p
• Output Formats: ELF, Intel HEX, and binary files
• Memory Analysis: Automatic flash/RAM usage reporting

Unit Testing

• Framework: Unity + CMock for comprehensive testing
• Mocking: Hardware abstraction layer automatically mocked
• Mock Prefix: mock_ functions (e.g., mock_hardware_interface_Init())
• Test Structure: Clean separation of test code and fixtures
• Build Integration: Seamless CMake and Ceedling integration

Configuration

MCU and Frequency Settings

Override default settings with environment variables:

export AVR_MCU=atmega328p
export F_CPU=16000000UL
cmake --preset avr

Build Presets

• avr: Release build for AVR firmware (optimized)
• test: Debug build for unit testing with Ceedling

Test Configuration

• Mock Generation: Automatic in build-test/mocks/
• Test Support: AVR headers stubbed for host compilation
• CMock Settings: Hardware interface mocked with mock_ prefix

Architecture

Hardware Abstraction

The project uses a clean hardware abstraction layer:

• hardware_interface.h/c: GPIO operations abstracted
• led.h/c: High-level LED control using hardware interface
• Testability: Hardware layer mocked for unit testing

Build System Design

• Dual Toolchains: AVR-GCC for firmware, Clang for tests
• Separate Build Directories: build/ for firmware, build-test/ for tests
• IntelliSense Support: .clangd configuration for code navigation

Troubleshooting

USB device not found:

1. Check: usbipd list (device should show "Attached - WSL")
2. Re-attach: usbipd attach --wsl --busid <BUSID>
3. Verify in container: lsusb

Build issues:

cmake --build build --target clean-all
cmake --preset avr && cmake --build build

Container issues: Ctrl+Shift+P → Dev Containers: Rebuild Container