Microcontroller Project Template using MicroZig and Devenv

This repository serves as a GitHub template to simplify starting microcontroller projects using MicroZig, a framework for developing firmware in Zig. The template is designed to work with various MicroZig-supported boards, with the Raspberry Pi Pico 2 provided as the default example. It leverages Devenv to manage the development environment using Nix, ensuring a consistent and reproducible setup.

Prerequisites

To use this template, ensure you have the following installed:

• Zig version 0.14 or later
• Nix package manager
• Git for cloning the repository
• Board-specific tools (e.g., picotool for Raspberry Pi Pico 2, included in the Devenv environment)

The template is configured for the Raspberry Pi Pico 2 by default but can be adapted for other MicroZig-supported boards. Refer to the MicroZig documentation for a list of supported boards.

Getting Started

Follow these steps to set up and run the example firmware for the Raspberry Pi Pico 2:

1. Clone the repository:

git clone https://github.com/clement-poiret/nix-microzig-devenv.git
cd nix-microzig-devenv

1. Enter the development environment:

devenv shell

Note that if you have direnv, direnv allow will make you automatically enter the development environment when entering it.

This command sets up a shell with all required tools and dependencies, managed by Nix and Devenv.

1. Build the example firmware:

zig build

This compiles the firmware, producing a template.uf2 file in the zig-out/firmware directory.

1. Flash the firmware to the Pico 2:

Put your Raspberry Pi Pico 2 into bootloader mode by holding the BOOTSEL button while plugging it into your computer via USB. Then run:

picotool load -f zig-out/firmware/template.uf2

This flashes the compiled firmware onto the microcontroller. You should see the LED connected to GPIO15 blinking if everything is set up correctly.

Note: If you are using a different board, refer to the Adapting for Other Boards section for guidance on modifying the template.

Project Structure

The template includes the following files, each serving a specific purpose:

• build.zig: The Zig build script that configures the firmware compilation process using MicroZig.
• build.zig.zon: Specifies dependencies (e.g., MicroZig) and metadata for the Zig project.
• devenv.lock, devenv.nix, devenv.yaml: Configuration files for Devenv, defining the Nix-based development environment, including tools like picotool and Zig.
• src/main.zig: The entry point for your firmware code. This file contains a simple example that blinks an LED on GPIO15 for the Pico 2.
• src/root.zig: A supporting Zig module, potentially for root-level configurations or imports (currently minimal in this template).

Adapting for Other Boards

To use this template with a different MicroZig-supported board, follow these steps:

1. Update the target in build.zig: Modify the target field in the mb.add_firmware call to match your board. For example, to use the Raspberry Pi Pico:

.target = mb.ports.rp2xxx.boards.raspberrypi.pico,

Refer to the MicroZig documentation for the list of supported boards under ports.

1. Adjust dependencies in build.zig.zon: Ensure that the MicroZig version and any additional dependencies are compatible with your target hardware. You may need to update the MicroZig commit or add specific dependencies for your board.

2. Modify Devenv configurations: Update devenv.nix to include any board-specific tools or utilities required for flashing or debugging. For example, if your board uses a different flashing tool, replace picotool with the appropriate package.

3. Update firmware code in src/main.zig: Change the pin configurations and any board-specific code to match your board's hardware. Consult your board's documentation for details on GPIO pins, peripherals, and other features.

4. Update flashing instructions: Modify the flashing commands in the Building and Flashing section to match your board's requirements. You may need to use different tools or procedures.

License

This template is released under the MIT License (LICENSE). Feel free to use, modify, and distribute it as needed.