A small collection of build tooling, example firmware projects, and supporting files for AVR microcontroller development.
- Provide a copyable template application for new AVR projects.
- Provide reproducible CMake and Make-based build tooling.
- Include a devcontainer so the same AVR toolchain is available in a consistent environment.
- Keep editor integrations simple by generating compile artifacts in a predictable location.
This repository is organized around a reusable AVR development setup:
development/applications/contains example or project-specific firmware applications.development/applications/template/is the starting point for a new application.development/scripts/contains the shared Make variables and the compile script used by app Makefiles.development/cmake/toolchain-avr.cmakeconfigures the AVR GCC toolchain..devcontainer/contains the Dockerfile and VS Code devcontainer configuration.
The repository is designed around an AVR development toolchain and a serial programmer connection.
- VS Code
- Docker Desktop or Docker Engine
- VS Code Dev Containers extension
- A USB serial adapter or Arduino-compatible device connected to the host for flashing
The devcontainer build installs the required packages and downloads the AVR GNU toolchain automatically via the Dockerfile in .devcontainer/.
For flashing, a device such as an Arduino Uno, Nano, or USB-to-TTL serial adapter must be available at a port such as:
- Linux:
/dev/ttyACM0,/dev/ttyUSB0 - WSL:
/dev/ttyS*,/dev/ttyUSB*, or/dev/ttyACM* - macOS:
/dev/cu.*or/dev/tty.*
The repo defaults to:
- MCU:
atmega328p - programmer:
arduino - baud:
115200 - port:
/dev/ttyACM0
You may need to add your user to the dialout group on Linux or create a udev rule for serial access.
-
Open the repository in VS Code.
-
In your terminal, outside of the container, run:
bash tools/setup.sh
-
Reopen the workspace in the container via Reopen in Container command from the Command Palette (Ctrl+Shift+P)
-
Change to a project directory. For example, in your terminal run:
cd /workspace/development/applications/template -
Build the project:
make build -
Compile and generate the binaries:
make compile -
Flash to the target MCU:
make flash
The project uses the common build script in development/scripts/ to configure the AVR toolchain and output the firmware hex file.
- Copy the contents of
development/applications/template/into a new project folder. - Update the project-local
MakefileandCMakeLists.txtto match the new application name or target. - Add or remove source files in the app-specific project as needed.
- Adjust the build or flash settings in the local project files when your hardware or MCU differs from the defaults.
Tip: Keep project-specific edits inside the application directory so the shared template remains reusable.
The build system is lightweight:
development/scripts/common.mksets the default AVR toolchain, device, port, programmer, and flash arguments.development/scripts/compile.shruns CMake and copies the resulting compile database todevelopment/artifacts/.development/cmake/toolchain-avr.cmakesets the AVR compiler and target flags.development/applications/template/CMakeLists.txtbuilds anfirmwareexecutable and emits a.hexfile from the compiled ELF output.
The default flash step uses avrdude with the Arduino profile and the target MCU set in the shared Makefile.
Example:
make flash
To override defaults for a different board or port:
make flash AVR_DEVICE=atmega328p PORT=/dev/ttyUSB0 BAUD=57600
If you are flashing from inside the devcontainer, make sure the serial device is visible inside the container. The repo mounts /dev into the container to support this pattern.
On Windows/WSL, USB serial adapters may need to be attached to WSL first.
-
Open Powershell / Terminal
-
Install usbipd with:
winget install usbipd -
Search for AVR device and. Note the busid.
usbipd wsl list -
Attach the port to WSL. Run the command below. Be sure to replace
<busid>with the bus ID reported byusbipd wsl list.
usbipd attach --wsl --busid <busid> --auto-attach
- macOS devices are often under
/dev/cu.*or/dev/tty.*. - On macOS, this command
make flashmust be run OUTSIDE of the container (but still within the correct application directory).
-
To close the container, open the command palette (Cmd+Shift+P) and search
Dev Containers: Reopen Folder Locally -
Change to a project directory, ie.:
cd /workspace/development/applications/template -
Then flash to device:
make flash
- Ensure the user has appropriate permissions for the serial device.
- Linux devices are often under
/dev/ttyUSB*or/dev/ttyACM*.
- Confirm that
development/artifacts/compile_commands.jsonexists, if not, try running:
make compile
- Otherwise try reloading the window with Ctrl + R.
I am getting this error: avrdude ser_open() OS error: cannot open port <...>: No such file or directory!
-
Attempt to plug the adapter in before reopening the container or temporarily remove the device mount from the devcontainer configuration.
-
Additionally, you can check the actual port name in the container using
ls /dev/tty*orls /dev/serial/by-id.