BitWands

[peripheral: SPI1]
base_address = 0x40013000
version = 1.2.0

[SPI1.clock]
source = "HSI"

[[SPI1.register: CR1]]
offset = 0x00

Core notation

The fastest way to get a feel for the spec is to read a few small patterns instead of starting with the whole language document. These are the constructs that show up constantly in real config and manifest files.

1. Use dotted keys or table headers interchangeably when they describe the same structure.
2. Use {...} for homogeneous value arrays and [[...]] for repeated tables.
3. Use header tags when the domain name matters more than the container name.
4. Use version and bitrange literals directly instead of inventing string encodings.

Tables and dotted keys merge

server.host = "localhost"

[server]
port = 8080

Value arrays versus table sequences

ports = {80, 443, 8080}

[[endpoint]]
path = "/health"
method = "GET"

Tags, versions, and bit ranges

firmware = 1.2.3

[[register: CR1]]
bits = 0:7
access = .RW

const fig = @import("fig");

const Config = struct {
    name: []const u8,
    version: fig.Version,
    radio: struct {
        frequency_mhz: u16,
        tx_power_dbm: i8,
    },
};

var result = try fig.parseFile(Config, alloc, "bitwands.fig");
defer result.release(alloc);

Quick start

The easiest way to approach fig-zig is as a typed parser library. Define the Zig shape you actually want, write a matching .fig file, parse it, then keep the Result(T) alive for as long as you need the mapped data.

1. Add fig to build.zig.zon and import it into your root module.
2. Write a .fig file with the values you want to edit outside the binary.
3. Define a Zig struct with matching field names and types.
4. Call fig.parseFile(...) or fig.parseBytes(...), then read result.value.
5. Keep the Result(T) alive for as long as you need any slices or nested allocations owned by the parsed value.
6. Run fig-check when you want syntax and structural validation without writing a consumer first.

Typed config parse

const std = @import("std");
const fig = @import("fig");

const Config = struct {
    name: []const u8,
    version: fig.Version,
    radio: struct {
        frequency_mhz: u16,
        tx_power_dbm: i8,
    },
};

var result = try fig.parseFile(Config, alloc, "bitwands.fig");
defer result.release(alloc);

std.debug.print("{s}: {d} MHz\n", .{
    result.value.name,
    result.value.radio.frequency_mhz,
});

Tagged sequence mapped into a keyed collection

const Register = struct {
    tag: fig.Tag,
    offset: u32,
};

const Device = struct {
    register: fig.Map(Register),
};

var result = try fig.parseBytes(Device, alloc,
    "[[register: CR1]]\n" ++
    "offset = 0x00\n");
defer result.release(alloc);

Validator usage

cd fig/fig-zig
zig build run -- path/to/config.fig

# or
zig build run-check -- path/to/config.fig

const ByteSet = munch.lex.ByteSet;
const Matcher = munch.lex.Matcher;

const alpha = ByteSet.from("abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ");
const digit = ByteSet.from("0123456789");
const alnum = alpha.merge(digit);

const MyLexer = munch.lex.Lexer(.{
    .rules = &.{
        .{ .tag = .identifier, .matcher = Matcher.span(alpha, alnum) },
        .{ .tag = .number, .matcher = Matcher.set(digit) },
        .{ .tag = .equals, .matcher = Matcher.literal("=") },
        .{ .tag = .whitespace, .matcher = Matcher.set(ByteSet.from(" \t")) },
        .{ .tag = .newline, .matcher = Matcher.literal("\n") },
    },
});

Quick start

The easiest way to learn Munch is to parse a tiny line-based language. Start with one token set, one AST node, and one root parser. Once that works, add more tokens and more node types without changing the basic shape. The README's end-to-end flow is the right way to approach it: lexer first, AST second, parser third, diagnostics last.

1. Define the lexer rules with munch.lex.Lexer and the matchers you need.
2. Model the grammar with plain Zig structs and wrapper types such as Token, Skip, and Drain.
3. Configure a parser with munch.parse.Parser and tell it which token tags to skip.
4. Parse a byte buffer, then inspect the typed result and any diagnostics.
5. If you need whole-document recovery, make the root type Drain(T) instead of a single statement node.
6. Add recursive pointers only after the flat version is already working.

Simple parse target

const Token = munch.parse.Token;
const Skip = munch.parse.Skip;
const Drain = munch.parse.Drain;

const Assignment = struct {
    name: Token(.identifier),
    _eq: Skip(.equals),
    value: Token(.number),
};

const Parser = munch.parse.Parser(.{
    .lexer = MyLexer,
    .root = Drain(Assignment),
    .skip = &.{ .whitespace, .newline },
});

var result = try Parser.parse(alloc, "score = 42\n");
defer result.release(alloc);

Diagnostics and recovery

if (result.hasErrors()) {
    for (result.diag) |d| {
        std.debug.print("{}:{}: expected {s}, found {s}\n",
            .{ d.loc.line, d.loc.col, d.expected, d.found });
    }
}

name = "demo_hal"
build_path = "src/jig"

[target.rp2040]
path = "hardware/rp2040.fig"

Quick start

Jig is easiest to understand as a manifest-to-code pipeline. You describe the chip tree in Fig, run the generator once, and then treat the generated files as a normal Zig module. The first pass does not need a full chip definition. One target and one block is enough to see the shape. It helps to read the generated Zig immediately so the mapping between manifest and API is obvious.

1. Write a project.fig that names the generated HAL and points at one or more targets.
2. Write a target manifest that points at one or more block manifests.
3. Describe registers, groups, and fields in the block manifest.
4. Run zig build run -- path/to/project.fig, then import the generated hal.zig from application code.
5. Read the emitted target and block files before layering more blocks on top.
6. Rely on the generator’s validation instead of treating invalid manifests as input you can fix later in firmware.

1. Root project manifest

name = "demo_hal"
build_path = "src/jig"

target.rp2040.path = "hardware/rp2040.fig"

2. Target manifest

name         = "rp2040"
manufacturer = "Raspberry Pi Ltd"
revision     = "B2"

block.resets.path   = "resets.fig"
block.io_bank0.path = "io_bank0.fig"

3. Block manifest with tagged register fields

name        = "resets"
address     = 0x4000_C000
width       = 32
description = "Peripheral Reset Controller."

[[register: reset]]
offset      = 0x00
description = "Peripheral reset control."

[[reset.field: uart0]]
bits   = 22:22
access = .RW
reset  = 1

[[reset.field: usbctrl]]
bits   = 24:24
access = .RW
reset  = 1

Generated consumer code

const hal = @import("jig/hal.zig");

const before = hal.rp2040.resets.reset.read();
_ = before.uart0;

hal.rp2040.resets.reset.write(.{
    .uart0 = 0,
    .usbctrl = 0,
});

Arrayed register-group example

name        = "io_bank0"
address     = 0x4001_4000
width       = 32
description = "IO bank 0."

[[register_group: gpio]]
offset      = 0x00
count       = 30
stride      = 8
description = "GPIO status and control."

[[gpio.register: ctrl]]
offset      = 0x04
description = "GPIO control."

[[gpio.register.ctrl.field: funcsel]]
bits   = 0:4
access = .RW
reset  = 31

Generated arrayed use

const ctrl0 = hal.rp2040.io_bank0.gpio(0).ctrl().read();
_ = ctrl0.funcsel;

hal.rp2040.io_bank0.gpio(0).ctrl().write(.{
    .funcsel = 5,
});

const fw = jig_rp2040.addFirmware(b, dep, .{
    .app_module = app,
});

b.installFile(fw.uf2, "firmware.uf2");

Quick start

This package turns a normal Zig module into a flashable RP2040 image. The shortest path is: define an app module, hand it to addFirmware(...), then export a main function from src/main.zig. Once that works, add interrupt handlers and supporting modules. The tool stays deliberately minimal at startup so board policy still lives in your application code.

1. Add jig-rp2040 as a dependency and create an app module rooted at src/main.zig.
2. Import the generated rp2040 and optional registry modules in build.zig.
3. Export pub fn main() noreturn from the app module.
4. Run zig build and flash the generated UF2 from zig-out/.
5. Add handlers only for the IRQ slots you truly own.
6. If you change the RP2040 hardware definitions, regenerate the HAL with zig build jig and commit the output.

Small app module

const registry = @import("registry");

pub const handlers: registry.Registry = .{
    .isr_irq5 = handleUsb,
};

fn handleUsb() callconv(.{ .arm_aapcs = .{} }) void {}

pub fn main() noreturn {
    while (true) {}
}

Build-side integration

const dep = b.dependency("jig_rp2040", .{});

const app = b.createModule(.{
    .root_source_file = b.path("src/main.zig"),
});
app.addImport("rp2040", dep.module("rp2040"));
app.addImport("registry", dep.module("registry"));

const fw = jig_rp2040.addFirmware(b, dep, .{
    .app_module = app,
});

hal.gpio.init();
defer hal.gpio.deinit();

hal.time.init(.{ .watchdog_tick_cycles = 12 });
defer hal.time.deinit();

hal.gpio.toggle(25);
hal.time.sleep(125_000);

Quick start

The main HAL pattern is explicit ownership. You initialize the singleton controller modules you need, then build device drivers on top of them. Nothing silently claims clocks, GPIO muxing, or interrupt slots for you, which keeps board policy visible in the application. The README’s bring-up order is the right mental model to follow whenever the package feels verbose.

1. Add rp2040-hal to your firmware build and import it as const hal = @import("rp2040_hal");.
2. Initialize the singleton modules you need, such as GPIO, time, SPI, I2C, or USB.
3. Create device instances like adxl345.Device or rfm69.Device only after their bus controller is ready.
4. Deinitialize modules when you want to return hardware to a known baseline.
5. Keep board-specific pin muxing outside the package, because the repo intentionally leaves that policy with the caller.
6. Reach for zig build test when you change timing math, driver behavior, or ownership rules.

Simple sensor bring-up

hal.gpio.init();
defer hal.gpio.deinit();

_ = try hal.i2c.init(.{
    .controller = .i2c0,
    .clk_sys_hz = 125_000_000,
    .baud_hz = 400_000,
});
defer hal.i2c.deinit(.i2c0);

var accel = try hal.adxl345.Device.init(.{
    .controller = .i2c0,
    .pins = .{ .chip_select = 17 },
    .address = .alt_low,
});
defer accel.deinit();

const sample = try accel.readSampleMg();
_ = sample;

USB CDC serial shape

const Serial = hal.usb.CdcSerial(.{
    .reference_hz = 12_000_000,
});

try Serial.init();
defer Serial.deinit();

while (true) {
    Serial.poll();
}

const usb = @import("loom").usb;

const Device = usb.CdcDriver(HalConfig, .{});

var device = Device{};
device.init();
while (true) device.poll();

Quick start

Loom pays off when you want protocol logic without rewriting the whole driver stack for each MCU. For a first pass, define one USB configuration type, expose the required lifecycle hooks, and let the framework own the USB state machine. Once that is working, the next useful additions are identity strings, CDC callbacks, and better endpoint-complete handling.

1. Define a HalConfig type that satisfies the USB HAL contract.
2. Provide the CDC endpoint configuration and the device identity callbacks.
3. Create a driver such as usb.CdcDriver(HalConfig, .{}).
4. Call init(), then keep polling in the main loop and use the driver methods for I/O.
5. Add callbacks like onRx and onControlLineStateChanged only after the transport basics work.
6. If you need another USB function class later, extend the driver policy layer rather than copying the CDC path.

Small CDC configuration slice

const usb = @import("loom").usb;

const HalConfig = struct {
    pub const cdc_config = usb.Types.CdcConfig{
        .ep_notification = 2,
        .ep_data_out = 3,
        .ep_data_in = 3,
        .max_packet_notification = 8,
        .max_packet_bulk = 64,
        .notification_interval = 16,
    };

    pub fn onRx(data: []const u8) void {
        _ = data;
    }
};

Identity and poll loop

pub fn getDeviceLanguages() usb.Types.DeviceLanguages {
    return .{
        .language_id = 0x0409,
        .strings = &.{
            .{ .kind = .manufacturer, .content = "BitWands" },
            .{ .kind = .product, .content = "Hub Receiver" },
            .{ .kind = .serial, .content = "001" },
        },
    };
}

var device = Device{};
device.init();
while (true) device.poll();

fwtool rp2040 flash zig-out/bin/firmware.uf2

// Finds the RPI-RP2 volume
// Copies the UF2
// Waits for the volume to disconnect

Quick start

fwtool is deliberately small, so the tutorial is mostly about workflow. Build the tool, put the board in BOOTSEL mode, then flash a UF2 directly. There is no hidden board database or monitor layer. It just finds RPI-RP2, copies the file, and waits for the drive to disappear. That waiting step matters because it keeps the command from returning before the board transitions away from the mass-storage path.

1. cd fwtool and run zig build to build the utility.
2. Put the RP2040 board into BOOTSEL mode so it mounts as RPI-RP2.
3. Run zig build run -- rp2040 flash path/to/firmware.uf2 while working locally.
4. Optionally install the binary and use fwtool rp2040 flash ... directly after that.
5. If flashing fails, verify the board is actually in BOOTSEL mode and check the expected mount paths first.

Simple workflow

cd fwtool
zig build
zig build run -- rp2040 flash ../firmware/zig-out/bin/hub_firmware.uf2

# or, after install
fwtool rp2040 flash ../firmware/zig-out/bin/wand_3_firmware.uf2

Mount search paths

/run/media/RPI-RP2
/media/RPI-RP2
/run/media/$USER/RPI-RP2
/media/$USER/RPI-RP2