Getting Started

This chapter walks you from a clean workstation to a fully simulated firmware build while reinforcing the habits we expect from every contributor: explicit setups, predictable builds, and clean logs.

1. Install Dependencies

ToolNotes
Zig 0.15.2Required compiler for native tests and cross builds.
Renode ≥ 1.16Provides the simulation harness; CLI tools must be on PATH.
mise (optional)Convenience task runner used by the project and CI.
mdBookGenerates the documentation portal under book/.

On macOS using Homebrew:

brew install zig mdbook mise
brew install --cask renode

On Linux, download the official Zig tarball, install Renode via the package or tar release, and place mdbook + mise binaries somewhere on your PATH.

Windows note: the upstream vfox dotnet plugin bundled with mise currently fails when a specific SDK build is requested (jdx/mise#4738). Our CI disables the dotnet tool on Windows so that the pre-installed SDK from the GitHub runner is used instead. If you need to build the Renode C# plugin on a Windows workstation, install the .NET 8 SDK (dotnet-install.ps1 --version 8.0.403 or the MSI) manually and run mise with MISE_DISABLE_TOOLS=dotnet until the upstream bug is fixed.

2. Clone the repository

git clone https://github.com/mattneel/zenbedded.git
cd zenbedded

3. Validate the workspace

# Run all host-side unit tests
zig build test

# Build each shipping board artefact (ReleaseSafe by default, but try Debug + ReleaseFast locally)
zig build -Dboard=stm32f4-discovery -Dtarget=thumb-freestanding-none -Dcpu=cortex_m4 -Doptimize=ReleaseSafe
zig build -Dboard=stm32f103-bluepill    -Dtarget=thumb-freestanding-none -Dcpu=cortex_m3 -Doptimize=ReleaseSafe
zig build -Dboard=nrf52840-dk           -Dtarget=thumb-freestanding-none -Dcpu=cortex_m33 -Doptimize=ReleaseSafe

# Boot the firmware inside Renode
mise run sim-stm32f4
cat build/renode/stm32f4_discovery-uart.log

If you prefer not to use mise, inspect .mise.toml for the underlying commands. Whatever path you choose, keep formatting, linting, and simulations exactly aligned with CI.

4. Explore the code

  • src/hal/cortex_m/startup.zig — vector table and reset handler shared by all Cortex-M boards, with assertions and explicit memory stitching.
  • src/board/console/*.zig — per-board console drivers that write banner text to UART using deterministic register programming.
  • renode/platforms/**/* — vendored CPU + board descriptions that Renode loads during simulation; warnings should be zero.
  • book/ — mdBook sources you are currently reading, kept in sync with the implementation.

With the environment ready, the next chapter dives into architecture-specific details.