### USB Device Example (Chip Agnostic)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

A basic example for a raw USB device. It can be tested using the provided Python script. This example is chip-agnostic.

```zig
src/usb_cdc.zig
```

--------------------------------

### USB HID Device Example (RP2040 Only)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

A basic example demonstrating the implementation of a USB Human Interface Device (HID). It can be tested using the provided Python script. This example is specific to the RP2040.

```zig
src/rp2040_only/usb_hid.zig
```

--------------------------------

### SPI Host Controller Example (RP2040 Only)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Demonstrates how to use the Serial Peripheral Interface (SPI) host controller. This example is specific to the RP2040.

```zig
src/rp2040_only/spi_host.zig
```

--------------------------------

### Blinky Core1 Example (RP2040 Only)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Blinks the onboard LED using the second CPU core. This example is specific to the RP2040.

```zig
src/rp2040_only/blinky_core1.zig
```

--------------------------------

### Flash Program Example (RP2040 Only)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Demonstrates writing and reading data into the microcontroller's flash memory. This example is specific to the RP2040.

```zig
src/rp2040_only/flash_program.zig
```

--------------------------------

### Zig Test Configuration Example

Source: https://github.com/zigembeddedgroup/microzig/blob/main/sim/aviron/README.md

An example of a Zig source file used within the AViRon test suite, demonstrating how to embed JSON configuration for test output and control program execution.

```zig
//! {
//!   "stdout": "hello",
//!   "stderr": "world"
//! }
const testsuite = @import("testsuite");

export fn _start() callconv(.C) noreturn {
    testsuite.write(.stdout, "hello");
    testsuite.write(.stderr, "world");
    testsuite.exit(0);
}

```

--------------------------------

### Custom Clock Configuration Example (Chip Agnostic)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Shows a fully custom clock configuration for the microcontroller. This example is chip-agnostic.

```zig
src/rp2040_only/custom_clock_config.zig
```

--------------------------------

### LED Matrix Control Example (RP2040-Matrix Board)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Showcases how to control the LED matrix on the RP2040-Matrix development board to perform a simple color flipper effect. This example is specific to the RP2040-Matrix board.

```zig
src/rp2040_only/tiles.zig
```

--------------------------------

### WS2812 LED Control Example (RP2040 Only)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Showcases how to control a WS2812 addressable LED attached to GPIO23. This example is specific to the RP2040.

```zig
src/ws2812.zig
```

--------------------------------

### GPIO Clock Output Example (Chip Agnostic)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Routes the system clock, divided by 1000, out to GPIO25. This example is chip-agnostic.

```zig
src/gpio_clock_output.zig
```

--------------------------------

### Square Wave Generation Example (Chip Agnostic)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Showcases how to use the Programmable I/O (PIO) to emit a basic square wave. This example is chip-agnostic.

```zig
src/squarewave.zig
```

--------------------------------

### UART Communication Example (RP2040 Only)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Showcases how to use the Universal Asynchronous Receiver/Transmitter (UART) peripheral, integrated with `std.log`. This example is specific to the RP2040.

```zig
src/rp2040_only/uart.zig
```

--------------------------------

### Flash Firmware with Picotool

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

This snippet demonstrates how to flash a `.uf2` firmware file to a Raspberry Pi RP2040 device using the `picotool load` command. It shows the command execution and expected output, indicating successful loading and device reboot.

```sh-session
[user@host] raspberrypi-rp2040/ $ picotool load -x zig-out/firmware/${file}.uf2
Loading into Flash: [==============================]  100%

The device was rebooted to start the application.
[user@host] raspberrypi-rp2040/ $ 
```

--------------------------------

### Minimal Root File Initialization

Source: https://github.com/zigembeddedgroup/microzig/blob/main/core/thoughts.md

Demonstrates the minimal setup for a root file in microzig. Declaring `panic` in the root file ensures proper instantiation of microzig and its dependencies, including the MCU package.

```zig
const microzig = @import("microzig");

pub const panic = microzig.panic; // this will instantiate microzig

comptime { _ = microzig };  // this should not be necessary

pub fn main() void {

}
```

--------------------------------

### Build Firmware with Zig

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/wch/ch32v/README.md

Builds the firmware for the project using the Zig build system. The first command builds with small release optimization, while the second builds with the default release mode, which may not fit into flash memory.

```bash
zig build -Doptimize=ReleaseSmall

zig build
```

--------------------------------

### Blinky Example (Chip Agnostic)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

A basic example that blinks the onboard LED. This demo is designed to run on both RP2040 and RP2350 chips without modification.

```zig
src/blinky.zig
```

--------------------------------

### Watchdog Timer Example (Chip Agnostic)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Enables a watchdog timer for 1 second and demonstrates the chip resetting when the timer elapses. This example is chip-agnostic.

```zig
src/watchdog_timer.zig
```

--------------------------------

### Flash ESP32-C3 Direct Boot Image

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/espressif/esp/README.md

This command flashes a direct boot image onto the ESP32-C3 device using `esptool.py`. It's a simpler flashing process that bypasses the need for a separate bootloader and partition table for certain configurations.

```shell
esptool.py --chip esp32c3 --baud 460800 --before default_reset --after hard_reset write_flash 0x0 \
    zig-out/firmware/esp32_c3_direct_boot_blinky.bin
```

--------------------------------

### Random Number Generator Example (RP2040 Only)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Showcases how to use the microcontroller's internal random number generator. This example is specific to the RP2040.

```zig
src/rp2040_only/random.zig
```

--------------------------------

### Flash ESP32-C3 with Bootloader and Partition Table

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/espressif/esp/README.md

This command flashes the ESP32-C3 device using `esptool.py`. It requires a bootloader and a partition table file to be present. The command specifies the chip, baud rate, and the addresses for each binary file.

```shell
esptool.py --chip esp32c3 --baud 460800 --before default_reset --after hard_reset write_flash \
        0x0 bootloader.bin 0x8000 partition_table.bin 0x10000 zig-out/firmware/esp32_c3_blinky.bin
```

--------------------------------

### Changing System Clocks Example (Chip Agnostic)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Demonstrates how to change the system (SYS) and reference (REF) clock frequencies. This example is chip-agnostic.

```zig
src/rp2040_only/changing_system_clocks.zig
```

--------------------------------

### Inspecting Generated Test Files with tree

Source: https://github.com/zigembeddedgroup/microzig/blob/main/sim/aviron/README.md

Example output of the 'tree' command showing the structure of files generated by the 'debug-testsuite' build step in the 'zig-out' directory.

```sh
zig-out/
├── bin
│   └── aviron-test-runner
└── testsuite
    ├── instructions
    │   ├── cbi.elf
    │   ├── in-stdio.elf
    │   ├── ...
    │   ├── out-stdout.elf
    │   └── sbi.elf
    ├── lib
    │   └── write-chan.elf
    └── simulator
        ├── scratch-reg0.elf
        ├── scratch-reg1.elf
        ├── ...
        ├── scratch-rege.elf
        └── scratch-regf.elf

```

--------------------------------

### ADC Example (RP2040 Only)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Takes periodic samples of the temperature sensor and prints it to UART using the stdlib logging facility. This example is specific to the RP2040.

```zig
src/rp2040_only/adc.zig
```

--------------------------------

### PWM Example (RP2040 Only)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Slowly blinks the onboard LED with a smooth effect using Pulse Width Modulation (PWM). This example is specific to the RP2040.

```zig
src/rp2040_only/pwm.zig
```

--------------------------------

### Disassembling AVR ELF Files with llvm-objdump

Source: https://github.com/zigembeddedgroup/microzig/blob/main/sim/aviron/README.md

Example of using 'llvm-objdump' to disassemble an AVR ELF executable generated by the AViRon test suite, showing the machine code for the '_start' function.

```sh
[~/projects/aviron]$ llvm-objdump -d zig-out/testsuite/instructions/out-exit-0.elf 

zig-out/testsuite/instructions/out-exit-0.elf:  file format elf32-avr

Disassembly of section .text:

00000000 <_start>:
       0: 00 27           clr     r16
       2: 00 b9           out     0x0, r16
       

```

--------------------------------

### Disassembling AVR ELF Files with avr-objdump

Source: https://github.com/zigembeddedgroup/microzig/blob/main/sim/aviron/README.md

Example of using 'avr-objdump' to disassemble an AVR ELF executable generated by the AViRon test suite, showing the machine code for the '_start' function.

```sh
[~/projects/aviron]$ avr-objdump -d zig-out/testsuite/instructions/out-exit-0.elf 

zig-out/testsuite/instructions/out-exit-0.elf:     file format elf32-avr

Disassembly of section .text:

00000000 <_start>:
   0:   00 27           eor     r16, r16
   2:   00 b9           out     0x00, r16       ; 0

[~/projects/aviron]$ 

```

--------------------------------

### I2C Bus Scan Example (RP2040 Only)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/raspberrypi/rp2xxx/README.md

Scans for I2C devices on the bus and prints them to UART0. It uses GPIO4 for SCL and GPIO5 for SDA. This example is specific to the RP2040.

```zig
src/rp2040_only/i2c_bus_scan.zig
```

--------------------------------

### Zig Microcontroller Register Access Example

Source: https://github.com/zigembeddedgroup/microzig/blob/main/tools/regz/README.md

Demonstrates how to use the generated Zig code to interact with microcontroller peripherals. This example shows modifying pin configuration and setting an output pin's state.

```zig
const regs = @import("nrf52.zig").registers;

pub fn main() void {
    regs.P0.PIN_CNF[17].modify(.{
        .DIR = 1,
        .INPUT = 1,
        .PULL = 0,
        .DRIVE = 0,
        .SENSE = 0,
    });
    regs.P0.OUT.modify(.{ .PIN17 = 1 });
}
```

--------------------------------

### Flash Firmware (CH32V103/CH32V203)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/wch/ch32v/README.md

Flashes firmware onto CH32V103 and CH32V203 microcontrollers. It supports both RUST (wchisp) and C (wch-isp) flashing tools. The C tool requires `libusb-1.0-0-dev`.

```bash
#$ wchisp flash BIN_FILE
$ wch-isp -pr flash BIN_FILE
```

--------------------------------

### Flash ESP32-C3 Flashless Image

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/espressif/esp/README.md

This command loads a flashless image directly into RAM on the ESP32-C3 device using `esptool.py`. This method is useful for debugging or when the firmware does not need to be persistently stored in flash memory.

```shell
esptool.py --chip esp32c3 --baud 460800 --no-stub load_ram zig-out/firmware/esp32_c3_flashless_blinky.bin
```

--------------------------------

### Flash Firmware (CH32V003)

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/wch/ch32v/README.md

Flashes firmware onto CH32V003 microcontrollers using the `wlink` tool. This process may involve switching modes using `wchlinke-mode-switch` and requires `libusb-1.0-0-dev`.

```bash
$ wlink flash --address 0x08000000 BIN_FILE
```

--------------------------------

### Disassemble ELF File

Source: https://github.com/zigembeddedgroup/microzig/blob/main/examples/wch/ch32v/README.md

Disassembles an ELF firmware file to view its machine code. This command requires the `riscv64-unknown-elf-objdump` tool and outputs the disassembled code to a specified file.

```bash
riscv64-unknown-elf-objdump --disassemble-all ELF_FILE > DISASSEMBLED_FILE
```

--------------------------------

### Generate UF2 from ELF using uf2 package in Zig

Source: https://github.com/zigembeddedgroup/microzig/blob/main/tools/uf2/README.md

Demonstrates how to integrate the 'uf2' Zig package into a build.zig file to convert an ELF binary into a UF2 file. This method specifies the microcontroller family ID, such as RP2040, and adds the generated UF2 file to the build artifacts for installation.

```zig
const uf2 = @import("uf2");

pub fn build(b: *Build) void {
    // ...
    const uf2_dep = b.dependency("uf2", .{});

    const uf2_file = uf2.from_elf(uf2_dep, exe, .{ .family_id = .RP2040 });
    _ = b.addInstallFile(uf2_file, "bin/test.uf2");
}

```

--------------------------------

### Zig: Create ESP Image from ELF using esp_image

Source: https://github.com/zigembeddedgroup/microzig/blob/main/tools/esp-image/README.md

This Zig code snippet demonstrates how to create an ESP image file from an ELF executable. It utilizes the `esp_image` build dependency to convert an ELF file, specifying the target chip ID (e.g., `esp32_c3`), into a flashable binary. The generated image is then added to the build installation files.

```zig
const esp_image = @import("esp_image");

pub fn build(b: *Build) void {
    // ...

    const esp_image_dep = b.dependency("esp_image", .{});
    const image_file = esp_image.from_elf(esp_image_dep, elf_file, .{
        .chip_id = .esp32_c3,
    });

    b.addInstallFile(image_file, "test.bin");
}
```

--------------------------------

### AViRon Repository Architecture

Source: https://github.com/zigembeddedgroup/microzig/blob/main/sim/aviron/README.md

Illustrates the directory structure of the AViRon project, showing the organization of source code, documentation, samples, test suites, and tools.

```sh
.
├── doc                 # Documents for Aviron or AVR 
├── samples             # Source of examples that can be run on the simulator
├── src                 # Source code
│   ├── lib             # - Aviron emulator
│   ├── libtestsuite    # - Source code of the testsuite library
│   └── shared          # - Shared code between the tools, generated code and simulator
├── testsuite           # Contains the test suite of Aviron
│   ├── instructions    # - Tests for single instructions
│   ├── lib             # - Tests for the libtestsuie  
│   ├── simulator       # - Tests for the simulator per se 
│   └── testrunner      # - Tests for the test runner (conditions, checks, ...)
├── testsuite.avr-gcc   # Contains code for the test suite that cannot be built with LLVM right now
│   └── instructions
└── tools               # Code for tooling we need during development, but not for deployment

```

--------------------------------

### Running the AViRon Test Suite

Source: https://github.com/zigembeddedgroup/microzig/blob/main/sim/aviron/README.md

Command to execute the AViRon test suite using the Zig build system. The test runner scans specific file types for compilation and execution.

```sh
[~/projects/aviron]$ zig build test

```

--------------------------------

### Configure RTT Instance

Source: https://github.com/zigembeddedgroup/microzig/blob/main/modules/rtt/README.md

Shows how to configure an RTT instance by defining up and down channels with specific modes and buffer sizes. It also illustrates optional thread safety configuration and linker section placement.

```Zig
const rtt_instance = rtt.RTT(.{
    // A slice of rtt.channel.Config for target -> probe communication
    .up_channels = &.{ 
        .{ .name = "Terminal", .mode = .NoBlockSkip, .buffer_size = 128 },
        .{ .name = "Up2", .mode = .NoBlockSkip, .buffer_size = 256 },
    },
    // A slice of rtt.channel.Config for probe -> target communication
    .down_channels = &.{ 
        .{ .name = "Terminal", .mode = .BlockIfFull, .buffer_size = 512 },
        .{ .name = "Down2", .mode = .BlockIfFull, .buffer_size = 1024 },
    },
    // Optional override of lock/unlock functionality for thread safe RTT
    .exclusive_access = your_lock_struct,
    // Optional placement in specific linker section for a fixed address control block
    .linker_section = ".rtt_cb",
});
```

--------------------------------

### microzig System Initialization and Reset

Source: https://github.com/zigembeddedgroup/microzig/blob/main/core/thoughts.md

Details the low-level system initialization and reset procedures within the microzig framework. It shows how the system handles MCU resets, BSS zeroing, data segment copying, and the execution flow from early initialization to the main application entry point.

```zig
extern fn reset() noreturn {
  if(@hasDecl(mcu, "mcu_reset")) {
  	mcu.mcu_reset();
    @unreachable();
  }
	// zeroing bss, copying .data, setting stack address
  
  if(@hasDecl(root, "early_main")) // idk about the name
    root.early_main();
  else {
  	mcu.init();
  
  	if(@hasDecl(root, "main"))
  		root.main();
		else
  		@compileError("main or entry_main missing")
	}
}
```

--------------------------------

### Build regz Project

Source: https://github.com/zigembeddedgroup/microzig/blob/main/tools/regz/README.md

Command to build the regz project using Zig's build system. The compiled binary will be located in the `zig-out/bin` directory.

```shell
zig build
```

--------------------------------

### Update Testsuite Files with Zig Build

Source: https://github.com/zigembeddedgroup/microzig/blob/main/sim/aviron/testsuite.avr-gcc/README.md

Executes the 'update-testsuite' target within the Zig build system. This command is used to update testsuite files that depend on the avr-gcc and avr-binutils toolchain. Ensure the toolchain is installed and available in your system's PATH before running.

```Zig
zig build update-testsuite
```

--------------------------------

### Debugging AViRon Test Suite Output

Source: https://github.com/zigembeddedgroup/microzig/blob/main/sim/aviron/README.md

Command to build and inspect the generated files from the AViRon test suite using the Zig build system, allowing for debugging of compiled test programs.

```sh
[~/projects/aviron]$ zig build debug-testsuite

```

--------------------------------

### Manually execute elf2uf2 tool in Zig build

Source: https://github.com/zigembeddedgroup/microzig/blob/main/tools/uf2/README.md

Shows how to use the 'elf2uf2' build artifact directly within a build.zig file. This approach allows for explicit configuration of arguments like the family ID, the input ELF file path, and the output UF2 file path, providing more control over the conversion process.

```zig
pub fn build(b: *Build) void {
    // ...

    const uf2_dep = b.dependency("uf2", .{});

    const elf2uf2_run = b.addRunArtifact(uf2_dep.artifact("elf2uf2"));

    // family id
    elf2uf2_run.addArgs(&.{"--family-id", "RP2040"});

    // elf file
    elf2uf2_run.addArg("--elf-path");
    elf2uf2_run.addArtifactArg(exe);

    // output file
    const uf2_file = elf2uf2_run.addPrefixedOutputFileArg("--output-path", "test.uf2");
    _ = b.addInstallFile(uf2_file, "bin/test.uf2");
}

```

--------------------------------

### Updating AViRon AVR-GCC Test Suite

Source: https://github.com/zigembeddedgroup/microzig/blob/main/sim/aviron/README.md

Command to update vendored AVR-GCC toolchain binaries for tests that cannot be built with LLVM, ensuring the test suite remains current.

```sh
[~/projects/aviron]$ zig build update-testsuite

```

--------------------------------

### Import RTT Module

Source: https://github.com/zigembeddedgroup/microzig/blob/main/modules/rtt/README.md

Demonstrates how to import the RTT module from the MicroZig package for use in your Zig project. This is the initial step to access RTT functionalities.

```Zig
const microzig = @import("microzig");
const rtt = microzig.cpu.rtt;
```

--------------------------------

### Zig Build Command for ReleaseSmall Optimization

Source: https://github.com/zigembeddedgroup/microzig/blob/main/port/microchip/avr/README.md

This command instructs the Zig build system to compile the project with the 'ReleaseSmall' optimization level. This is recommended to avoid LLVM issues when targeting AVR microcontrollers in debug mode.

```zig
zig build -Doptimize=ReleaseSmall
```

--------------------------------

### Generate Zig Code from SVD via CLI

Source: https://github.com/zigembeddedgroup/microzig/blob/main/tools/regz/README.md

Shows how to use the `regz` command-line tool to generate Zig code from an SVD file by providing the file path as a command-line argument. The output is redirected to a `.zig` file.

```shell
regz <path-to-svd> > my-chip.zig
```

--------------------------------

### RTT API Usage

Source: https://github.com/zigembeddedgroup/microzig/blob/main/modules/rtt/README.md

Details the core API functions for interacting with an RTT instance after initialization. This includes writing to up channels, reading from down channels, and obtaining standard library compatible readers/writers.

```APIDOC
RTT API:

- init(): Initializes the control block memory. Must be called before any other RTT operations.

- write(comptime channel_number: usize, bytes: []const u8) WriteError!usize:
  Writes bytes to a specific up channel (device -> probe).
  - Parameters:
    - channel_number: Compile-time validated index of the up channel.
    - bytes: The byte slice to write.
  - Returns: The number of bytes written. Writing less than requested is not an error.

- writer(comptime channel_number: usize) Writer:
  Returns a standard library `GenericWriter` for a specific up channel.
  Note: The `GenericWriter` discards data if the buffer is full to prevent blocking.

- read(comptime channel_number: usize, bytes: []u8) ReadError!usize:
  Reads bytes from a specific down channel (probe -> device).
  - Parameters:
    - channel_number: Compile-time validated index of the down channel.
    - bytes: The buffer to read into.
  - Returns: The number of bytes read. Reading less than requested is not an error.

- reader(comptime channel_number: usize) Reader:
  Returns a standard library `GenericReader` for a specific down channel.
```

--------------------------------

### Generate Zig Code from SVD via Stdin

Source: https://github.com/zigembeddedgroup/microzig/blob/main/tools/regz/README.md

Demonstrates generating Zig code by piping an SVD file to `regz` via standard input. The `--format` flag is used to specify the schema type.

```shell
cat my-file.svd | regz --format svd > my-chip.zig
```