k4s.xyz

Lesson 1: Anatomy of an RP2350 Image

kevstewa@protonmail.com (Kevin Stewart) — Sun, 18 Oct 2026 00:00:00 +0000

This is the second lesson of Embedded Rust on the RP2350, a course in embedded Rust on the Raspberry Pi RP2350, built from the reset vector up. It follows Lesson 0, which sets up the toolchain and the rp2350-course workspace this lesson adds to.

Goals

You finish with lessons/l01-image, a crate with zero dependencies that the RP2350's boot ROM accepts and runs. Every byte in it is yours:

A linker script that places your code in flash at 0x1000_0000 and defines the top of the stack.
A vector table built by hand: the initial stack pointer, then your reset handler.
A 20-byte IMAGE_DEF you assemble word by word.
Proof on hardware that the boot ROM launched your code, and proof of what it does when your image is wrong.

rp-hal's blinky from Lesson 0 puts 40 bytes in .start_block: a 20-byte IMAGE_DEF followed by a 20-byte picotool header. This lesson builds only the first part.

Your reset handler stays deliberately small. Copying .data, zeroing .bss and turning on the LED are Lesson 2.

Read first

All section numbers are from the RP2350 datasheet, with the page number printed in its footer.

Section	Pages	Why
§5.1.4 Image definitions	328	What an IMAGE_DEF is for
§5.1.5 Blocks and block loops	328–329	Markers, items, and the link word
§5.1.12 Flash image boot	331–332	The first-4-KB rule, and the 20-byte minimum
§5.9.3.1 IMAGE_DEF item	383–384	The flags field, bit by bit
§5.9.3.3 VECTOR_TABLE item	385	Without this item, the vector table is assumed to be at the start of the image
§5.9.5.1 Minimum Arm IMAGE_DEF	389	The exact five words you'll type
§2.2 Address map	27	Where flash (0x1000_0000) and SRAM (0x2000_0000) live

For comparison after you've built yours: rp235x-hal/src/block.rs in rp-hal, and memory.x in rp235x-hal-examples.

Concepts

What the boot ROM does before your code exists

At power-on the core runs code from its own mask ROM at address 0, not from flash. The boot ROM sets up the QSPI flash in a simple, safe mode, then searches the first 4 KB of flash for a block loop holding a valid IMAGE_DEF (§5.1.12). If it finds one for an Arm executable, it looks for the vector table at the start of the image, because your IMAGE_DEF names no other location (§5.9.3.3). It loads the stack pointer from word 0 and jumps to the address in word 1. If it finds nothing valid, it treats the flash as blank, drops into BOOTSEL mode, and the board appears on your PC as a USB drive.

Lesson 0's diagram showed the vector table at the start of flash. The boot ROM never reads that table until the IMAGE_DEF has vouched for the image.

Blocks, items and loops

A block is a run of 32-bit words (§5.1.5.1):

A start marker, 0xffffded3.
One or more items. The first item's type decides what kind of block it is.
A LAST item recording how many words of items came before it.
A link: the relative offset to the next block in the loop.
An end marker, 0xab123579.

A link of 0 points back at the block itself, a loop of one. Longer loops exist so that tools can append blocks after linking: signing an image, for example, adds a second, larger IMAGE_DEF (§5.1.5.2). The markers were chosen because they're unlikely to appear in real Arm or RISC-V code.

Your IMAGE_DEF, word by word

Word	Value	Meaning
0	`0xffffded3`	Start marker
1	`0x10210142`	`IMAGE_TYPE` item: byte 0 is type `0x42`, byte 1 is the size (1 word), bytes 2–3 are the flags `0x1021`
2	`0x000001ff`	`LAST` item: byte 0 is type `0xff`, bytes 1–2 say the items before it total 1 word
3	`0x00000000`	Link to the next block: offset 0, a loop of one
4	`0xab123579`	End marker

The flags 0x1021 in binary are 0001 0000 0010 0001. Checked against Table 493 (§5.9.3.1):

Bits	Field	Value	Meaning
0–3	Image type	1	Executable
4–5	Security	2	Runs in Secure mode
8–10	CPU	0	Arm
11	Extra security	0	Off (ignored before stepping A4)
12–14	Chip	1	RP2350
15	Try before you buy	0	Off

The image format and the boot ROM's search for it are the same on every RP2350 stepping. Bit 11 is the one difference, and this image leaves it clear anyway (§5.9.3.1, p. 384).

Little-endian storage is why a hex dump of the block shows d3deffff 42012110: the same words, low byte first.

Linker scripts

The linker script is the contract between your code and the chip's address map. Yours has four parts:

MEMORY names the regions and their sizes.
SECTIONS says which input sections go where, in what order.
ENTRY names the symbol debuggers treat as the start. The chip ignores it.
Symbols such as _stack_start are addresses the script defines and your code can read.

Two more pieces protect you. KEEP stops the linker from discarding a section nothing references. ASSERT fails the link with your own message when a rule is broken, which beats debugging a silent board.

Keeping the linker from deleting your work

Nothing in your code calls the vector table or reads the IMAGE_DEF, so the toolchain would happily throw both away. Three layers stop it:

#[used] tells the compiler to emit the static even though nothing uses it.
#[unsafe(link_section = "...")] puts it in a named section. It's unsafe because the wrong section can break the program in ways the compiler can't check.
KEEP(...) in the script tells the linker not to garbage-collect that section.

Exercise 3 has you remove one layer and watch what disappears.

The Thumb bit

Cortex-M only runs Thumb code, and bit 0 of a branch target says "Thumb". When you put a function in the vector table, the toolchain sets that bit for you. That's why blinky's reset vector is 0x10000139 while Reset itself sits at 0x10000138.

Build it

Four files go in a new crate, and one line changes in the workspace.

rp2350-course/
├── Cargo.toml            add the crate to members
└── lessons/l01-image/
    ├── Cargo.toml
    ├── build.rs          hands link.ld to the linker
    ├── link.ld           MEMORY, SECTIONS, ENTRY, _stack_start
    └── src/main.rs       vector table, IMAGE_DEF, Reset

1. Register the crate

In the workspace's root manifest:

# Cargo.toml (workspace root)
[workspace]
resolver = "3"
members = ["lessons/l01-image"]

And the crate's own manifest:

# lessons/l01-image/Cargo.toml
[package]
name = "l01-image"
version = "0.1.0"
edition.workspace = true

[[bin]]
name = "l01-image"
test = false
bench = false

How to read these two files. TOML is key = value lines grouped under [table] headers. A dotted key such as edition.workspace is shorthand for a nested table.

[workspace] makes the root Cargo.toml a virtual manifest. It owns the crates under it, but is not a crate itself. All of them share one target/ directory and one Cargo.lock.
members lists each crate's directory. A crate is part of the workspace because it is listed here.
resolver = "3" picks the dependency-resolution rules. A crate gets this default from its edition, but a virtual manifest has no edition of its own, so it must say it. Version 3 is the one that comes with edition 2024.
[workspace.package] holds values that members can inherit. edition.workspace = true means "take edition from the workspace". That's why the crate's manifest doesn't say 2024 itself.
[package] describes the crate. name is also the default name of the binary it produces.
[[bin]], with double brackets, is TOML's array of tables. Each [[bin]] header adds one more entry to a list of binary targets. Cargo would find src/main.rs on its own anyway. This entry exists only to change two settings on that binary, and since its name matches the package name, it adjusts the binary Cargo already found instead of creating a new one.
test = false and bench = false keep this binary out of cargo test and cargo bench. Those commands compile it with Rust's test harness (the test crate), which needs std, so the build would fail on this target.

2. Hand the script to the linker

// lessons/l01-image/build.rs
use std::{env, path::PathBuf};

fn main() {
    // Let the linker find link.ld in this crate's directory.
    let dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap());
    println!("cargo:rustc-link-search={}", dir.display());

    // Use our script, and skip page-aligning sections
    // (flash isn't paged memory).
    println!("cargo:rustc-link-arg-bins=-Tlink.ld");
    println!("cargo:rustc-link-arg-bins=--nmagic");

    println!("cargo:rerun-if-changed=link.ld");
}

How this file works:

A build script is a separate program. If a crate has a build.rs, Cargo compiles it for your Linux machine, not the Pico, and runs it before compiling the crate. It's ordinary std Rust, which is why std::env is available here.
It talks to Cargo through stdout. Each printed line that starts with cargo: is an instruction. Anything else is ignored. (Recent Cargo also accepts cargo::, with two colons. Both work.)
env::var("CARGO_MANIFEST_DIR") reads an environment variable Cargo sets for the script: the directory holding this crate's Cargo.toml. Cargo always sets it, so the unwrap() can't fail.
cargo:rustc-link-search=DIR adds -L DIR to the linker command. The linker looks for the file named by -T in its working directory first, then in each -L directory. Delete this line and the link fails with rust-lld: error: cannot find linker script link.ld.
cargo:rustc-link-arg-bins=FLAG passes FLAG to the linker, but only when it links this crate's binaries. Tests, examples and the build script itself are left alone. (rustc-link-arg, without -bins, would apply to every target.)
-Tlink.ld tells the linker to use your script instead of its built-in default layout.
--nmagic turns off page alignment of the program's segments. By default the linker assumes an operating system will map the file into memory a page at a time (64 KB pages for this target), so it pads the file to match. Without the flag, the ELF grows from 5,292 to 70,680 bytes, and each LOAD segment in readelf -l reports Align 0x10000 instead of 0x4. The 58 bytes that reach flash are identical either way. So with rust-lld, the flag keeps the ELF honest about a chip that has no pages; it doesn't save flash. Some guides say it saves flash, including the config comments in Shawn Hymel's introduction-to-embedded-rust ("Prevent padding memory between sections"), but with this linker it doesn't, even with a section at a deliberately unaligned address.
cargo:rerun-if-changed=link.ld narrows when Cargo reruns the script. By default it reruns whenever any file in the crate changes. Once the script prints a rerun-if-changed line, Cargo reruns it only when a listed file (or build.rs itself) changes. Editing link.ld still triggers a relink, which is the case that matters.

3. Write the linker script

/* lessons/l01-image/link.ld */
/* Lesson 1: the memory map of a zero-dependency RP2350 image. */

MEMORY
{
    /* The Pico 2's QSPI flash, seen through XIP. */
    FLASH : ORIGIN = 0x10000000, LENGTH = 4M
    /* SRAM0-7; the two 4 KB banks above are left alone. */
    RAM   : ORIGIN = 0x20000000, LENGTH = 512K
}

/* Debuggers treat this as the start. The chip ignores it and uses the
   vector table. */
ENTRY(Reset);

/* The stack starts at the top of RAM and grows down. */
_stack_start = ORIGIN(RAM) + LENGTH(RAM);

SECTIONS
{
    /* Word 0: initial stack pointer. Word 1: reset handler.
       Must be first in flash. */
    .vector_table ORIGIN(FLASH) :
    {
        KEEP(*(.vector_table));
    } > FLASH

    /* The IMAGE_DEF block. The boot ROM only searches the first 4 KB of
       flash for it. */
    .start_block : ALIGN(4)
    {
        KEEP(*(.start_block));
    } > FLASH

    .text : ALIGN(4)
    {
        *(.text .text.*);
    } > FLASH

    .rodata : ALIGN(4)
    {
        *(.rodata .rodata.*);
    } > FLASH

    /* Nothing copies .data or zeroes .bss until Lesson 2, so both must
       stay empty. */
    .data : ALIGN(4)
    {
        *(.data .data.*);
    } > RAM AT > FLASH

    .bss (NOLOAD) : ALIGN(4)
    {
        *(.bss .bss.*);
    } > RAM

    /* Unwind tables are for panics that unwind. This target aborts
       instead. */
    /DISCARD/ :
    {
        *(.ARM.exidx .ARM.exidx.* .ARM.extab.*);
    }
}

ASSERT(SIZEOF(.data) == 0 && SIZEOF(.bss) == 0,
       "Lesson 1 has no runtime init: keep mutable statics out until Lesson 2");
ASSERT(ADDR(.start_block) + SIZEOF(.start_block) <= ORIGIN(FLASH) + 4K,
       "the IMAGE_DEF must end within the first 4 KB of flash");

Reading the script, line by line

Cargo hands this file to rust-lld, LLVM's linker, running in GNU mode (-flavor gnu on its command line). It reads the same script language as GNU ld, so the GNU ld manual's "Linker Scripts" chapter is the reference for everything below. These rules apply throughout the file:

Comments are /* ... */ only. A // line fails the link with unknown directive: //.
An assignment such as _stack_start = ...; needs its semicolon. Elsewhere semicolons are optional, and this script uses them anyway for consistency.
Numbers take C syntax (0x10000000), plus the suffixes K (×1024) and M (×1024×1024). So 4M is 0x40_0000 and 512K is 0x8_0000.

MEMORY { ... } declares regions, and nothing else. Each line is NAME : ORIGIN = start, LENGTH = size. A region is a named address range that output sections can be placed into, plus a running "next free address" that starts at ORIGIN. The linker checks fit: if .text grows past LENGTH(FLASH), the link fails with an overflow error instead of producing an image that wraps. GNU syntax also allows attributes such as FLASH (rx) :. They only steer sections the script doesn't mention, and this script mentions everything, so they're left out.

ENTRY(Reset); writes Reset's address into the ELF header's entry-point field. Tools that load the ELF, such as GDB, read it as "where the program starts", and the linker treats it as a garbage-collection root. The chip never sees it: it starts from the vector table.

_stack_start = ORIGIN(RAM) + LENGTH(RAM); defines a symbol, which is a name for an address with no storage behind it. ORIGIN() and LENGTH() are built-in functions that read a region's numbers back, so this is 0x2000_0000 + 0x8_0000 = 0x2008_0000. In Rust you declare it as extern static _stack_start: u32 and only ever take its address (&raw const _stack_start). Reading its value would load whatever word sits at 0x2008_0000, which is the first word of SRAM8.

SECTIONS { ... } is where the work happens. The compiler's object files arrive full of input sections. Each statement inside SECTIONS builds one output section in the final ELF, in the order written. The general shape is:

NAME [ADDRESS] [(TYPE)] : [ALIGN(n)]
{
    FILE-PATTERN(SECTION-PATTERNS)
    ...
} [> VMA-REGION] [AT > LMA-REGION]

Taking each piece in turn:

Piece	Example	Meaning
`NAME`	`.text`	The output section's name in the ELF. Only `/DISCARD/` is special; any other name is just a label.
`ADDRESS`	`ORIGIN(FLASH)`	An explicit start address. Without it, the section starts at the region's next free address. Only `.vector_table` uses one, because the boot ROM expects the table at the very start of flash.
`(TYPE)`	`(NOLOAD)`	`NOLOAD` reserves addresses but writes no bytes to the file. That's right for `.bss`, which only has to be zero at run time.
`ALIGN(n)`	`ALIGN(4)`	Rounds the start address up to the next multiple of `n` bytes. The linker already aligns each section to its strictest input (a `u32` forces 4), so `ALIGN` sets a floor regardless of contents. `.text` ends at 0x1000_003a. A `.rodata` holding only a `[u8; 3]` lands at 0x1000_003a without `ALIGN(4)` and 0x1000_003c with it. Lesson 2's copy loop moves whole words, which is why it needs that floor.
`> REGION`	`> FLASH`	Place the section in this region, at its next free address, and advance that address past it.
`AT > REGION`	`> RAM AT > FLASH`	Give the section a different load address (LMA). `.data` runs at RAM addresses (VMA) but its starting bytes are stored in flash, right after `.rodata`. That's the VMA/LMA split from Lesson 0: virtual memory address (where it runs) versus load memory address (where it's stored).

Inside the braces: *(.text .text.*). This is an input section description, FILE-PATTERN(SECTION-PATTERNS).

The * outside the parentheses matches every input file: your crate's object file, plus libcore and compiler_builtins. A narrower file pattern is possible, but this course won't need one.
Inside the parentheses is a space-separated list of glob patterns for section names. .text matches a section named exactly .text. .text.* matches any name that starts with .text..
Why the second pattern matters: rustc puts every function in its own section, named .text. plus the symbol name. Your Reset arrives as .text.Reset, and the panic handler as .text._RNv…rust_begin_unwind. That's what lets the linker's --gc-sections (Rust always passes it) delete unused functions one at a time. *(.text) alone would match none of your code.
Order: one pattern list places matches in the order the linker meets them. *(.text) *(.text.*) would instead put all plain .text first, then everything else. Here the result is the same.
.rodata, .data and .bss follow the same convention, so each gets the same two patterns.

Here's what happens if you write *(.text) alone. The link still succeeds, with no warning. .text.Reset becomes an "orphan", a section no rule claims, and the linker places it by its own heuristics as an output section named .text.Reset. It happens to land at 0x1000_001c, so the image even runs. That's the danger: an unmatched section is placed silently, wherever the linker sees fit. Adding -C link-arg=--orphan-handling=warn makes it name every orphan. It also lists the debug sections, which is harmless, because they never reach flash.

KEEP(...) wraps an input section description. Sections inside it are roots for garbage collection, so the linker never removes them. Anything they reference survives too. .text.Reset needs no KEEP because the vector table points at it.

/DISCARD/ : { ... } is the one special output name: anything matched there is thrown away. .ARM.exidx and .ARM.extab are unwind tables that let a panic walk back up the stack. This target aborts on panic, so they're dead weight. rustc still emits a small one for the panic handler.

ASSERT(condition, "message"); at the top level is checked after every address is fixed. If the condition is false, the link fails with your message. ADDR(sec) is a section's start address, and SIZEOF(sec) its size in bytes.

rp-hal's rp235x-hal-examples/memory.x uses one more piece you'll meet in Lesson 2: ., the location counter. Inside a section it means "the current address", so __start_block_addr = .; records where the block begins. Each of its SECTIONS blocks closes with INSERT AFTER, as in } INSERT AFTER .vector_table;, because the file isn't a whole script. The blocks splice .start_block and a few other sections into link.x, the full script the cortex-m-rt crate provides, which defines the vector table and everything else.

4. Write the program

// lessons/l01-image/src/main.rs
//! Lesson 1: an RP2350 image the boot ROM accepts, with zero dependencies.
#![no_std]
#![no_main]

use core::panic::PanicInfo;
use core::ptr;

unsafe extern "C" {
    /// Defined by link.ld at the top of RAM. Only its address means anything.
    static _stack_start: u32;
}

/// The first two words of the Armv8-M vector table. Lesson 8 adds the other 66.
#[repr(C)]
pub struct VectorTable {
    initial_sp: *const u32,
    reset: extern "C" fn() -> !,
}

// Raw pointers aren't `Sync`, so a static holding one needs this promise.
// It holds: nothing ever writes the table, and it lives in flash anyway.
unsafe impl Sync for VectorTable {}

#[used]
#[unsafe(link_section = ".vector_table")]
static VECTOR_TABLE: VectorTable = VectorTable {
    initial_sp: &raw const _stack_start,
    reset: Reset,
};

/// The minimum Arm IMAGE_DEF (RP2350 datasheet §5.9.5.1, p. 389).
#[used]
#[unsafe(link_section = ".start_block")]
static IMAGE_DEF: [u32; 5] = [
    0xffff_ded3, // PICOBIN_BLOCK_MARKER_START
    0x1021_0142, // IMAGE_TYPE item, 1 word: EXE, Secure, Arm, RP2350
    0x0000_01ff, // LAST item: the items before it total 1 word
    0x0000_0000, // link to the next block: 0 means it loops to itself
    0xab12_3579, // PICOBIN_BLOCK_MARKER_END
];

/// A word of RAM you can watch from the probe. A raw address, not a static,
/// because a static here would land in .bss and nothing zeroes .bss yet.
const HEARTBEAT: *mut u32 = 0x2000_0000 as *mut u32;

#[unsafe(no_mangle)]
#[allow(non_snake_case)]
pub extern "C" fn Reset() -> ! {
    let mut count: u32 = 0;
    loop {
        count = count.wrapping_add(1);
        // Volatile, so the compiler can't decide nobody is looking.
        unsafe { ptr::write_volatile(HEARTBEAT, count) };
    }
}

#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
    loop {}
}

Reading the program, line by line

Each variation below was built to check it. Where removing something breaks the build, the error shown is the real one.

Comments and crate attributes

//! is a doc comment for the thing that contains it (here, the whole crate). /// documents the item that follows it. // is a plain comment.
#![...], with the !, is an inner attribute: it applies to whatever encloses it, here the crate. #[...], without the !, applies to the next item.
#![no_std] links only core, never std. core is the part of the standard library that needs no operating system: pointers, integers, Option, slices, formatting. There's no heap, no threads and no files.
#![no_main] tells rustc not to generate the usual program entry point, which sets up std's runtime and then calls your fn main. Without it you get error[E0601]: `main` function not found in crate `l01_image` . Here, the vector table is how the program starts.

Declaring a symbol from the linker script

unsafe extern "C" {
    static _stack_start: u32;
}

An extern block declares things defined somewhere else; here, by link.ld. The compiler trusts the declaration and leaves the linker to supply the address.
"C" names the ABI, meaning the C conventions for symbols and calls. It's the one stable convention Rust shares with linkers and other languages.
Since edition 2024, the block itself must be written unsafe extern, because the compiler can't check that your declaration matches reality. Leave out unsafe and you get error: extern blocks must be unsafe.
Declaring the type as u32 is a convenient fiction. Nothing is stored at that address, and the code never reads it. Taking its address with &raw const needs no unsafe block, but reading the value would.

The vector table type

#[repr(C)] fixes the struct's memory layout to C's rules: fields in the order written, each at its natural alignment. Rust's default layout is unspecified, and the compiler may reorder fields. The hardware reads offset 0 as the stack pointer and offset 4 as the reset address, so the order isn't negotiable.
*const u32 is a raw pointer: an address with no lifetime and no borrow checking. It may be null or dangling, so dereferencing one needs unsafe. Storing one is safe.
extern "C" fn() -> ! is a function pointer type: the address of a function that takes nothing, uses the C calling convention, and never returns. ! is the never type. A reset handler has nothing to return to.
unsafe impl Sync for VectorTable {}: every static must be Sync, meaning it's safe to share between threads (and, on this chip, between the two cores and interrupt handlers). Raw pointers aren't Sync, so neither is the struct. Delete the line and you get error[E0277]: `*const u32` cannot be shared between threads safely. unsafe impl is you telling the compiler "this holds" for a property it can't prove. It holds here because the table is never written.

The two statics

static, not const. A static is one object at one fixed address, which is exactly what a vector table is. A const has no address; the compiler pastes its value wherever it's used. Change static to const and you get error: `#[used]` attribute cannot be used on constants.
#[used] and #[unsafe(link_section = "...")] are explained under "Keeping the linker from deleting your work". Since edition 2024, attributes that can break a program the compiler can't check must be wrapped in unsafe(...). link_section and no_mangle are two of them.
&raw const _stack_start creates a raw pointer directly. &_stack_start would create a reference, which promises a valid, initialized u32 that the code may read. &raw const makes no such promise. That's the honest description of a symbol that is only an address.
reset: Reset uses the function's name as a value, which turns it into a function pointer. The compiler can't know the final address, so it leaves a relocation, and the linker fills in 0x1000_001d.
[u32; 5] is an array of five u32s. The underscores in 0xffff_ded3 are digit separators with no meaning, like commas in 1,000.

The heartbeat address

const HEARTBEAT: *mut u32 = 0x2000_0000 as *mut u32; casts a plain integer to a raw pointer. A const is right here, because it's just a number. *mut means writing through it is allowed (still only inside unsafe).

The reset handler

#[unsafe(no_mangle)]: by default, rustc mangles symbol names, encoding the crate and path so names from different crates can't collide. Without this attribute your function's symbol is _RNvCs6rdpOkqRjUQ_9l01_image5Reset. The image still builds and even runs, because the vector table refers to the function through a relocation, not by name. But the linker warns cannot find entry symbol Reset; not setting start address, and the ELF's entry point becomes 0x0.
#[allow(non_snake_case)] silences the lint that wants function names in snake_case. Reset is capitalized to match cortex-m-rt's handler of the same name, and the ENTRY(Reset) in your script.
pub extern "C" fn Reset() -> ! uses the C calling convention, because hardware calls it, not Rust code. -> ! means the function can never return, and the compiler enforces that: the body must diverge, as the loop does.
count.wrapping_add(1) wraps from u32::MAX back to 0 in every build profile. Plain + would panic on overflow in debug builds.
unsafe { ptr::write_volatile(HEARTBEAT, count) } stores count at 0x2000_0000 and promises the compiler it really happens. Writing through a raw pointer is unchecked, hence unsafe. Here's why volatile matters. Replace the line with a plain store, unsafe { *HEARTBEAT = count };, and the release build's entire loop compiles to this:

1000001c: b580    push {r7, lr}
1000001e: 466f    mov  r7, sp
10000020: e7fe    b    0x10000020 <Reset+0x4>

That's a branch to itself, with no store anywhere. The compiler proved that nothing in the program ever reads that memory, so it deleted the writes. Volatile tells it that each access is visible outside the program (to the probe here, and to hardware from Lesson 3 on), so every write must happen, in order. That's the version that produced the unrolled loop of four str instructions you'll see in the disassembly below.

The panic handler

#[panic_handler] marks the function that runs when code panics. With std that function comes built in. Under no_std you must provide exactly one, and its signature must be fn(&PanicInfo) -> !. This one just spins. Nothing in Reset can panic, so the linker removes the handler entirely, as the --print-gc-sections output below shows.

Watch the linker work

With main.rs in place, the crate has something to link, so you can watch the step 3 script at work. Two flags show you exactly what it did. Run them from the workspace root:

# A map: every output section, the input sections inside it,
# and their addresses
cargo rustc --release -p l01-image --bin l01-image -- \
    -C link-arg=-Map=$PWD/target/l01.map
grep -E '\.(vector_table|start_block|text)|Reset$' target/l01.map

# Garbage collection: every section the linker removed
# (touch forces a relink)
touch lessons/l01-image/src/main.rs
cargo rustc --release -p l01-image --bin l01-image -- \
    -C link-arg=--print-gc-sections 2>&1 | grep -v debug

The map shows .text.Reset inside your .text output section:

     VMA      LMA     Size Align Out     In      Symbol
10000000 10000000        8     4 .vector_table
10000000 10000000        8     4         l01_image-….rcgu.o:(.vector_table)
10000008 10000008       14     4 .start_block
10000008 10000008       14     4         l01_image-….rcgu.o:(.start_block)
1000001c 1000001c       1e     4 .text
1000001c 1000001c       1e     4         l01_image-….rcgu.o:(.text.Reset)
1000001d 1000001d       1e     1                 Reset

The GC list shows what didn't survive: a stray empty .text, the panic handler .text._RNv…rust_begin_unwind, and its .ARM.exidx entry. Nothing in Reset can panic, so nothing references the handler, and the linker deletes it. You wrote a panic handler and it costs zero bytes of flash.

Look before you flash

From the workspace root:

cargo build --release
cargo size --release --bin l01-image -- -A
cargo objdump --release --bin l01-image -- -h --show-lma
cargo objdump --release --bin l01-image -- -s -j .vector_table -j .start_block
cargo objdump --release --bin l01-image -- -d -j .text

-d disassembles, and -j limits any of these to the named section. With Rust 1.97 the sections come out as below; .text may differ a little with another compiler version:

Section	Address	Size
`.vector_table`	0x1000_0000	8 bytes
`.start_block`	0x1000_0008	20 bytes
`.text`	0x1000_001c	30 bytes

Contents of section .vector_table:
 10000000 00000820 1d000010                    ... ....
Contents of section .start_block:
 10000008 d3deffff 42012110 ff010000 00000000  ....B.!.........
 10000018 793512ab                             y5..

The reset vector is 0x1000001d: Reset at 0x1000_001c, plus the Thumb bit. In the disassembly, the compiler unrolled your loop four times, and every store still goes to 0x2000_0000, because the write is volatile. cargo objcopy --release --bin l01-image -- -O binary l01.bin gives a 58-byte file, against about 8 KB for blinky.

Flash it and prove it runs

probe-rs download writes the ELF's LOAD segments into flash at their physical addresses. Then probe-rs reset restarts the chip, so it boots through the boot ROM as it would at power-on:

probe-rs download --chip RP235x \
    target/thumbv8m.main-none-eabihf/release/l01-image
probe-rs reset --chip RP235x

Now read the heartbeat twice:

probe-rs read --chip RP235x b32 0x20000000 1
probe-rs read --chip RP235x b32 0x20000000 1

Two different values mean the boot ROM accepted your IMAGE_DEF, loaded your stack pointer, and jumped into your Reset. Also read back your tag with probe-rs read --chip RP235x b32 0x10000008 5.

cargo run --release works too, but probe-rs run stays attached waiting for logs that this image never sends, so press Ctrl-C to get the probe back.

Break it on purpose

Change the start marker in IMAGE_DEF from 0xffff_ded3 to 0xffff_ded4, then rebuild, download and reset. The build succeeds, because the linker has no idea what the words mean. The heartbeat stops changing. With the Pico 2's own USB cable connected, run:

lsusb | grep -i 2e8a
lsblk -o NAME,LABEL,SIZE

A Raspberry Pi device (vendor ID 2e8a) appears, along with a small drive labeled RP2350. The boot ROM found no valid block in the first 4 KB and fell back to BOOTSEL. Restore the marker, download, reset, and confirm the heartbeat ticks again. The probe can flash the chip whether or not it's in BOOTSEL, so this is always recoverable.

How rp-hal does it

Your piece	rp-hal's piece
`link.ld`	`memory.x` (regions, plus `.start_block` and `.bi_entries` placement) combined with cortex-m-rt's `link.x` (everything else)
`IMAGE_DEF: [u32; 5]`	`ImageDef::secure_exe()` from `rp235x-hal/src/block.rs`, which builds the same five words
Two-word `VectorTable`	cortex-m-rt's 16 exception entries plus the PAC's 52 interrupt entries: 272 bytes
`Reset` that loops	cortex-m-rt's `Reset`, which initializes RAM, enables the FPU, then calls `main`
`ASSERT`s	cortex-m-rt asserts its own rules too. Find them in `link.x`

Open block.rs and check that secure_exe() produces your exact five words.

Exercises

Past the 4 KB line. Move .start_block with `.start_block ORIGIN(FLASH)
- 4K : ALIGN(4). Your ASSERT` stops the build first. Comment the assert out, predict what the boot ROM does, then flash and check. This is Lesson 0's self-check question 4, answered on hardware.
Trip the other assert. Add static mut SEEN: u32 = 7; and write to it from Reset with ptr::write_volatile(&raw mut SEEN, 1). Read the link error. Which section did SEEN try to land in, and what would go wrong if the linker let it through?
Remove a layer. Delete KEEP from .start_block and rebuild. Then put it back and delete #[used] instead. Check cargo size -A each time. Which change loses the IMAGE_DEF, and why?
Fault with a two-word table. Before the loop in Reset, add unsafe { ptr::read_volatile(0x0100_0000 as *const u32) }, a read from an unmapped address. The bus fault becomes a HardFault, and the core fetches the HardFault handler's address from word 3 of the vector table. Work out what's at 0x1000_000c in your image, then predict whether the heartbeat ever starts.

Self-check

Why does the boot ROM need an IMAGE_DEF, when the vector table already says where the code starts?
What does the LAST item's size field count, and what is it in your block?
Why does the linker accept a wrong start marker without complaint?
Where does the value of _stack_start end up in the final image, and who reads it first?
Your image has no .data and no .bss. What would break if it had them?

Previous: Lesson 0: Toolchain and a Known-Good Baseline.

Part of Embedded Rust on the RP2350.

Lesson 0: Toolchain and a Known-Good Baseline

kevstewa@protonmail.com (Kevin Stewart) — Sat, 17 Oct 2026 00:00:00 +0000

This is the first lesson of Embedded Rust on the RP2350, a course in embedded Rust on the Raspberry Pi RP2350, built from the reset vector up. It assumes you know Rust reasonably well and have done a little microcontroller work. Everything runs on Linux; the setup steps are written for Fedora.

Goals and how this course works

This lesson proves your bench end to end: a stock rp-hal example builds, flashes and blinks, and you can read your firmware's bytes back out of the chip. That matters for Lesson 1. When your hand-built image refuses to boot, you'll know the fault is in the image, not the toolchain or the wiring.

You finish with:

A Rust toolchain that cross-compiles for the RP2350's Cortex-M33 cores (target thumbv8m.main-none-eabihf).
A working flash path: a Raspberry Pi Debug Probe, over SWD.
rp-hal cloned locally. It is the course's answer key.
An inventory of every black-box piece in a typical RP2350 Rust project, each mapped to the lesson that replaces it.
An empty course workspace, ready for Lesson 1.

The crate rule. Part 1 uses zero dependencies. After that, a crate appears only once you've built a small version of what it does.

How every lesson is built. Goals, datasheet sections to read, concepts, a step-by-step build with complete code, a comparison with how rp-hal does it, exercises, and self-check questions. Code accumulates in one Cargo workspace, and each lesson builds on the one before it, so run each one on hardware before moving on.

Keep these open: the RP2350 datasheet, the Pico 2 datasheet, rp-hal, the pico-pico book and Shawn Hymel's course repo.

Course map

PIO has its own lesson (10), and Lesson 11 uses it to build a logic analyzer, so you don't need to buy one. Lesson 7 teaches Rust's concurrency tools on your laptop first; Lesson 9 then puts the second Cortex-M33 to work, well before Embassy.

Lesson 21 comes right before the capstone so the station can sleep between readings. A bench supply that reports current measures the awake states, and a multimeter measures the deep ones. It leans on Lesson 5's clocks, Lesson 8's interrupts and both cores going idle.

After the capstone, a security track (S1 to S4) covers the RP2350's security features. Short security notes appear earlier, wherever those mechanisms first show up. Signed boot burns a key into OTP and can't be undone, so S3 runs on a second Pico 2 kept for that purpose.

The analyzer samples the chip's own pins while your code drives them, so one board both runs the bus and watches it. You'll open captures in PulseView, which is free. Lesson 18 upgrades it with a ring buffer so it can show what happened before the trigger.

#	Lesson	What you build
0	Toolchain and baseline	A proven bench: blinky flashed, ELF inspected, bytes read back
1	Anatomy of an RP2350 image	Linker script and a hand-assembled IMAGE_DEF the boot ROM accepts
2	Reset and the runtime contract	Reset handler in a naked function; LED on with raw writes
3	GPIO from the registers up	Your register layer and type-state pins; blinky plus button
4	PAC and runtime crates	Your own PAC generated with svd2rust, then rp235x-pac and cortex-m-rt; defmt logging
5	Clocks from scratch	XOSC and PLLs to 150 MHz, checked by the frequency counter
6	Time, PWM and first trait impls	Mini-HAL v0.1: DelayNs, OutputPin, SetDutyCycle; the watchdog: enable, feed, reset reason, pause while debugging
7	Rust concurrency, laptop first	Small std programs on move closures, Send and Sync, Rc vs Arc, RefCell vs Mutex, atomics; then what changes without std
8	Interrupts and shared state	Interrupt-driven blinker, debounced button, your critical-section impl; a HardFault handler that reads the fault registers, saves them to watchdog scratch and reboots to report the crash
9	The second core (Arm only)	Core 1 booted by hand over the SIO FIFO; spinlocks, ordered atomics, a heap with Arc, your own safe spawn API
10	PIO from the instruction up	Hand-encoded PIO programs, then pio_asm!; side-set, FIFOs, clock dividers
11	Build a logic analyzer	PIO capture plus your first DMA transfer; captures opened in PulseView
12	UART and embedded-io	PL011 driver, interrupt-driven RX ring buffer, command console
13	I²C from registers	DesignWare I²C driver implementing I2c; bus scanner
14	Driver: SHT31-D	Standalone driver crate with host-side tests
15	SPI and bus sharing	PL022 SpiBus and shared-bus devices
16	Driver: ILI9340C TFT	Display driver, your bitmap font, DrawTarget
17	Driver: SD card	SPI-mode block driver, FAT32 walked by hand, embedded-sdmmc
18	DMA in depth	Chaining, ring buffers, safe buffer ownership; BMP viewer; analyzer pre-trigger
19	rp235x-hal under the hood	HAL swap with your drivers unchanged
20	Async to Embassy	Toy executor, then embassy-rp, async drivers, an executor per core
21	Power: sleep, dormant, power-down	Clock gating while asleep, DORMANT woken by a GPIO edge or the always-on timer, switched-core power-down that keeps SRAM; current logged from a bench supply by a small Rust host tool, with a multimeter for the microamp states
22	Capstone: environment station	SHT31 dashboard on the TFT, CSV logging to SD, work split across both cores, sleeping between samples, a watchdog fed only while both cores are alive
E1	TMC2209 stepper (after 12)	STEP/DIR ramps, single-wire UART driver, PIO step generator
E2	OLED FeatherWing (after 16)	Framebuffer driver plus the wing's buttons
S1	TrustZone-M	SAU setup, a Secure and Non-secure split, calls through `.gnu.sgstubs` veneers
S2	OTP	Reading the OTP rows, what each controls, and which writes are permanent
S3	Hashed and signed images	Hash and signature items in the block loop, signing with picotool, secure boot on the spare board
S4	Hardening	Glitch detector, debug lockdown, and the published attacks on the A2 stepping

Portfolio projects

Eight milestones end in a standalone repo you can publish. Between them, the course workspace stays your lab notebook (a private repo works well) and keeps building on its own copy.

After	Repo	What it shows
3	`rp2350-from-reset`	Boots with zero dependencies: your linker script, IMAGE_DEF, reset handler, GPIO from raw registers
8	`rp2350-minihal`	Your HAL implementing embedded-hal 1.0: clocks, timers, PWM, interrupts. New releases at 13, 15 and 18
9	`rp2350-dual-core`	Core 1 booted by hand, a safe spawn API, cross-core messaging, a measured speedup
11	`pio-logic-analyzer`	A working tool: PIO and DMA capture, opened in PulseView. Version 2 adds pre-trigger at 18
14	`sht31`	A HAL-agnostic driver crate with host-side and mock-bus tests
17	`tft-breakout`	Display and SD card drivers for the Adafruit 2.2" breakout. A DMA image viewer joins at 18
22	`environment-station`	The capstone: both cores, async tasks, live dashboard, SD logging
E1	`tmc2209`	Stepper driver crate: single-wire UART protocol plus PIO step generation

Repo names are suggestions. Driver repos stay HAL-agnostic: their examples run on your mini-HAL, pinned by git tag, and gain rp235x-hal examples after Lesson 19 so anyone can run them.

Exporting a milestone

Copy the crate out of the workspace into a fresh directory. The workspace copy carries on into the next lesson untouched.
Make it build alone. Replace each *.workspace = true field with a real value, and bring .cargo/config.toml, rust-toolchain.toml, memory.x and build.rs along. Path dependencies on your mini-HAL become git dependencies pinned to a tag.
Add a README covering what it demonstrates, the wiring, how to flash it, and what you learned building it. Add a license; MIT OR Apache-2.0 is the Rust norm.
From a fresh clone, run cargo fmt --check, cargo clippy, any host tests, and cargo build --release.
Commit, tag v0.1.0, and push to your git host.
Optional CI: a workflow that builds for the RP2350 target and runs the host tests.

Lesson 3 walks through the first export end to end. A repo that later lessons improve gets a new tagged release from a fresh copy, so every published version stays a coherent snapshot. If you want a crate's commit history in its repo, git subtree split --prefix=lessons/<crate> extracts it; a plain copy starts clean.

What you need

The two essentials are a Pico 2 and a Raspberry Pi Debug Probe. Every lesson flashes and debugs through the probe.

Item	When	Why
Raspberry Pi Pico 2	Now	The course uses its pinout: 12 MHz crystal, LED on GPIO25
Raspberry Pi Debug Probe	Now	Flashes over SWD, halts the core, reads any address; its UART port serves Lesson 12
USB cables that carry data, one per board	Now	A charge-only cable fails silently
3-pin header for the Pico 2's debug pads	Now	Connects the probe's SWD cable
Breadboard, jumpers, LED with 330 Ω resistor, push button	Lesson 3	GPIO output and input
Logic analyzer	Never	You build one in Lesson 11
Bench supply that reports current (optional)	Lesson 21	Powers the Pico 2 through VSYS and logs its current while running and sleeping
Multimeter with a µA range	Lesson 21	Dormant and power-down draw tens to hundreds of µA, below what most bench supplies resolve
A second Pico 2	Before S3	Secure boot burns OTP permanently; keep your main board unlocked

Why the probe matters. cargo run flashes over SWD with no button presses. You can halt the CPU, read memory, and stream logs. In Lesson 2, a broken reset handler leaves the board silent, and the probe is your only window into it.

Software, installed next: Rust stable with the thumbv8m.main-none-eabihf target, cargo-binutils, probe-rs, picotool, git, and an editor with rust-analyzer. The course uses Helix. PulseView arrives with Lesson 11.

Fedora setup

On a fresh Fedora install, do this section first. It adds what the next section takes for granted: rustup, the libraries probe-rs builds against, picotool, and permission to use the probe without sudo. After it, every command in the course runs unchanged. These steps were checked against Fedora 44 on x86_64.

1. Packages from Fedora

# Rust's installer, the editor, and what cargo needs to build probe-rs
sudo dnf install rustup helix helix-parsers helix-themes git gcc cmake \
  pkgconf-pkg-config libusb1-devel systemd-devel

# Rust itself, into ~/.rustup and ~/.cargo; the default choices are fine
rustup-init

Open a new terminal afterwards so ~/.cargo/bin is on your PATH. The editor's command is still hx.

Fedora splits Helix into three packages. helix is the editor; helix-parsers holds the grammars and queries behind syntax highlighting; helix-themes holds the themes. helix only recommends the other two, and a minimal install skips recommended packages, so name them. Without helix-parsers, Helix opens files with no highlighting at all.

On the bare Linux console, with no desktop, only 16 colors exist. Pick a theme built for that in ~/.config/helix/config.toml:

# ~/.config/helix/config.toml
theme = "term16_dark"

Don't also install Fedora's rust and cargo packages. The workspace's rust-toolchain.toml only takes effect through rustup's own cargo, so which cargo should print a path under ~/.cargo/bin.

2. picotool from RPM Fusion

Fedora doesn't package picotool. RPM Fusion's nonfree repository does (version 2.3.1), and the package installs picotool's udev rules too. Enable RPM Fusion the way its documentation shows, which adds the free and nonfree repositories together, then install:

sudo dnf install \
  https://mirrors.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm \
  https://mirrors.rpmfusion.org/nonfree/fedora/rpmfusion-nonfree-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install picotool

If you'd rather not add RPM Fusion, use Raspberry Pi's prebuilt picotool from the releases page linked in the next section. You then copy its udev rules into /etc/udev/rules.d yourself.

3. Probe and serial permissions

The probe-rs and picotool rules both grant access two ways: to whoever is logged in at the machine's own screen and keyboard, and to members of the plugdev group. Over SSH only the group works. Fedora doesn't create plugdev, and probe-rs says to make it a system group on systemd newer than v258; Fedora 44 ships v259.

Lesson 12's serial port, /dev/ttyACM0, belongs to the dialout group, and logging in at the machine doesn't open it.

Create the group and join both groups first. udev looks up a group name when it loads a rules file, and drops the group from the rule if it doesn't exist yet. Rules loaded before plugdev existed wouldn't use it until udev reloaded them.

sudo groupadd --system plugdev
sudo usermod -aG plugdev,dialout $USER

probe-rs publishes its own udev rules. Install them, then reload, which picks up picotool's rules from step 2 as well, now that plugdev exists:

sudo curl -fsSL -o /etc/udev/rules.d/69-probe-rs.rules \
  https://probe.rs/files/69-probe-rs.rules
sudo udevadm control --reload
sudo udevadm trigger

The Debug Probe has no entry of its own in that file. It matches the rule for any adapter whose USB product name contains CMSIS-DAP.

Log out and back in so the new groups apply, then check:

groups            # lists plugdev and dialout
which cargo       # a path under ~/.cargo/bin
probe-rs list     # once probe-rs is installed: the probe, without sudo

For later lessons. PulseView (Lesson 11) and a serial terminal (Lesson 12) are both packaged: sudo dnf install pulseview tio. Fedora's openocd and RPM Fusion's pico-sdk aren't needed; the course uses neither.

Install the toolchain

Four tools cover the whole course: the Cortex-M33 compile target, LLVM's binary inspectors, probe-rs, and picotool.

# 1. Rust stable plus the RP2350 Arm target (Armv8-M Mainline, hard-float ABI)
rustup update stable
rustup target add thumbv8m.main-none-eabihf

# 2. cargo size / objdump / nm, backed by LLVM's tools
rustup component add llvm-tools
cargo install cargo-binutils

# 3. probe-rs: flashing, logs, memory reads
cargo install --locked probe-rs-tools

Install picotool as well. Its info command and UF2 conversion stay useful alongside the probe.

Prebuilt binaries: raspberrypi/pico-sdk-tools releases
Linux distro packages exist, including RPM Fusion's for Fedora; make sure picotool version reports 2.x, which added RP2350 support.

Check everything answers:

rustup target list --installed
cargo size --version
probe-rs --version
picotool version

Linux permissions. udev rules let probe-rs and picotool run without sudo; on Fedora, the setup above installs them. On another distribution, follow the same order: make sure the plugdev group exists and you're in it, then install probe-rs's rules and picotool's (from its repository's udev folder) into /etc/udev/rules.d and reload udev. If either tool ever demands sudo after an OS upgrade, check the rules first.

Editor: Helix. Helix talks to rust-analyzer over LSP, so install the server through rustup and confirm Helix finds it:

rustup component add rust-analyzer
hx --health rust   # the rust-analyzer line should show a path, not "Not found"

Helix's debugger support is still experimental, so Lesson 2 single-steps the reset handler from the command line through the probe instead.

Wire it up

Connect ground first, then the signals. The probe's D port carries SWD and its U port carries UART. Raspberry Pi's docs warn that boards on separate power need a common ground before any signal wire goes on.

Raspberry Pi Debug Probe to Pico 2

Probe port and wire	Pico 2 connection
D, black (GND)	Debug header GND
D, orange (SC)	Debug header SWCLK
D, yellow (SD)	Debug header SWDIO
U, black (GND)	Pin 3, GND
U, orange (probe TX)	Pin 2, GP1 (UART0 RX)
U, yellow (probe RX)	Pin 1, GP0 (UART0 TX)

A plain Pico 2 has no JST debug connector. Solder a 3-pin header onto the SWCLK, GND and SWDIO pads at the end opposite USB, then use the probe's JST-to-female-header cable on the D port. The UART rows matter from Lesson 12, but wiring them now costs nothing. Power each board from its own USB cable; the shared GND wire ties them together.

Source: Raspberry Pi Debug Probe documentation.

Verify the chain

Confirm the host sees the probe, and the probe sees the chip, before you build anything.

probe-rs list   # should list a CMSIS-DAP probe
probe-rs info   # reads the target's debug port; no Rust involved yet

If info reports an SWD or wire-protocol error, recheck the ground wire first, then check SC and SD aren't swapped.

Read your chip marking. The top of the RP2350 carries a line such as RP2350A0A2 or RP2350A0A4; a phone camera's zoom helps. The last two characters are the stepping. Steppings A3 and later fix erratum E9, the GPIO input leakage issue Lesson 3 covers (datasheet Appendix C.2.1, p. 1349). Note yours down.

Flash the baseline

Flash rp-hal's own blinky before writing a line yourself. If the LED blinks, every link in the chain works.

git clone https://github.com/rp-rs/rp-hal.git
cd rp-hal/rp235x-hal-examples

Open .cargo/config.toml and find the [target.thumbv8m.main-none-eabihf] table. Point its runner line at the probe:

# .cargo/config.toml, in [target.thumbv8m.main-none-eabihf]
runner = "probe-rs run --chip RP235x"

Build and flash:

cargo run --release --bin blinky

cargo run builds the ELF, then calls the runner with the ELF's path as the last argument. The first build compiles every dependency, so it is the slow one. With probe-rs, the command stays attached to stream output; Ctrl-C ends the session.

If it fails

probe-rs finds no probe: check the probe's USB cable, the udev rules, and that no other program holds the probe.
SWD or wire-protocol errors: ground first, then SC and SD swapped, then the solder joints on the debug header.
It flashes but nothing blinks: confirm the board is a Pico 2, not a Pico 2 W, and that the example still drives gpio25.

The magic inventory

Seventeen pieces of this baseline run before or around your code without you writing them. By Lesson 8, you will have rebuilt every one. Open .cargo/config.toml, memory.x, build.rs and src/bin/blinky.rs, and find each piece.

Piece (where)	What it does	Rebuilt in
Target `thumbv8m.main-none-eabihf` (`.cargo/config.toml`)	Armv8-M Mainline, Thumb code, hard-float ABI	1
`-Tlink.x` and `--nmagic` (`.cargo/config.toml`)	Hands the linker cortex-m-rt's script; skips page alignment	1, then 4
`memory.x` (crate root)	Flash and RAM regions; slots `.start_block` after the vector table	1
`build.rs` (crate root)	Copies `memory.x` to where the linker searches	1
`#![no_std]`, `#![no_main]` (`blinky.rs`)	No OS, no runtime-provided `main`	1
Vector table (cortex-m-rt)	Initial stack pointer, then handler addresses	1; device IRQs in 8
`IMAGE_DEF` in `.start_block` (`blinky.rs`)	Tells the boot ROM this is a valid Arm executable	1
Reset handler (cortex-m-rt)	Copies `.data`, zeroes `.bss`, enables the FPU, calls `main`	2
`#[hal::entry]` (`blinky.rs`)	rp235x-hal's wrapper around cortex-m-rt's entry attribute	2, compared in 4
The `panic_*` crate import (`blinky.rs`)	Supplies the mandatory panic handler	2
`Peripherals::take()` (`blinky.rs`)	Hands out each peripheral exactly once	3 raw, 4 via PAC
`Pins::new`, `into_push_pull_output` (`blinky.rs`)	Releases IO and pad resets; configures pad and pin function	3
`init_clocks_and_plls` (`blinky.rs`)	Crystal, PLLs, clock muxes	5
Timer and `delay_ms` (`blinky.rs`)	64-bit microsecond timer behind embedded-hal's DelayNs	6
`set_high`, `set_low` (`blinky.rs`)	embedded-hal's OutputPin trait	6
`-Tdefmt.x` (`.cargo/config.toml`)	Linker support for defmt's compact logging	4
`PICOTOOL_ENTRIES` in `.bi_entries` (`blinky.rs`)	Metadata that `picotool info` displays	1, as an exercise

Names drift between rp-hal versions. If a piece isn't where the table says, note what you found instead; that is part of the exercise.

What IMAGE_DEF is. The boot ROM won't run whatever happens to be in flash. Before launching anything, it searches the first 4 KB of flash for a small tag called an image definition, or IMAGE_DEF. The tag says "this is a program, built for an Arm core, for an RP2350". If the ROM can't find one, it treats the flash as blank and drops into BOOTSEL mode. The smallest valid tag is 20 bytes: a start marker, one item describing the image, a closing item, a link to the next block, and an end marker (RP2350 datasheet §5.1.4, p. 328, and §5.9.5.1, p. 389). The ROM then finds the vector table at the start of the image, because no item says otherwise (§5.9.3.3, p. 385). rp-hal writes the tag for you with ImageDef::secure_exe(). In Lesson 1 you type out all five words yourself.

Look inside the ELF

The ELF is a container for your tools, not something the chip ever sees. The boot ROM only meets the raw bytes that land in flash. This section opens the container, then follows its bytes to their final addresses.

The container

ELF, the Executable and Linkable Format, wraps one blob of bytes in three kinds of table. The ELF header says what the file is. Program headers describe segments: which bytes to load, and where. Section headers name the regions the linker built, such as .text and .data.

The blinky ELF file                      Where each part goes
(file offsets increase downward)

+--------------------------------+
| ELF header                     |  52 bytes: class, machine, entry point
+--------------------------------+
| Program headers                |  segments: what to load, and where
+--------------------------------+
| Loadable section bytes         |  flashed    Flash at 0x1000_0000
|   .vector_table, .start_block, | ----------> probe-rs writes these bytes
|   .text, .rodata, and the      |             at the PhysAddr (LMA) of
|   initial values for .data     |             each segment
+--------------------------------+
| Non-allocated sections         |  read by    Stays on your PC
|   .debug_*, .symtab, .strtab,  | ----------> debugger: symbols, source
|   .comment, .ARM.attributes    |  tools      lines, variable types;
+--------------------------------+             defmt strings later
| Section headers                |  name, type and flags of every section
+--------------------------------+

probe-rs reads the program headers to decide which bytes to write at which flash addresses. It reads the symbol table and debug sections to show you variables, backtraces and, from Lesson 4, logs.

Look at all three tables from rp-hal/rp235x-hal-examples:

# ELF header: class, endianness, machine, entry point
cargo readobj --release --bin blinky -- --elf-output-style=GNU --file-headers

# Program headers: the loader's view, segment by segment
cargo readobj --release --bin blinky -- --elf-output-style=GNU --program-headers

# Section headers: the linker's view, with flags
cargo readobj --release --bin blinky -- --elf-output-style=GNU --section-headers

In the ELF header

Class ELF32 with little-endian data: a 32-bit Arm core.
Type EXEC: a fully linked executable, not an object file waiting for more linking.
The entry point is Reset with bit 0 set. The chip never reads it; debuggers do.
The flags read 0x5000400: Arm EABI version 5 with the hard-float ABI, matching the eabihf in your target name.

In the program headers

Each LOAD segment pairs a VirtAddr (VMA, virtual memory address: where code expects the bytes at run time) with a PhysAddr (LMA, load memory address: where the bytes are stored). "Virtual" is a leftover from systems with an MMU; on this chip both are plain physical addresses.
For segments in flash the two match, because the RP2350 executes straight from flash.
When .data isn't empty, its segment has a RAM VirtAddr and a flash PhysAddr. That gap is the copy your reset handler performs. Blinky's .data is empty, so you won't see this segment until the experiment below.
Where MemSiz exceeds FileSiz, the extra bytes exist only at run time and must be zeroed. That is .bss.

In the section headers

Flag A (alloc) means the section occupies target memory. X means executable, W writable.
.bss has type NOBITS: it takes RAM but no bytes in the file.
Sections without the A flag never reach the chip: .debug_*, .symtab, .strtab, .comment, .ARM.attributes. That is why debug = 2 costs no flash.

What the non-allocated sections hold

.debug_info describes every type, variable and function in DWARF, the standard debug format. It is how a debugger shows a struct's fields by name.
.debug_line maps each code address to a source file and line. Stepping through source, and line numbers in backtraces, both come from here.
.debug_frame records how to unwind each function's stack frame. probe-rs uses it to print a backtrace after a panic or fault.
.debug_str, .debug_abbrev, .debug_ranges and .debug_loc are supporting tables: shared strings, encoding templates, address ranges, and where each variable lives as code runs. Exact names vary a little with the DWARF version.
.symtab is the symbol table that cargo nm prints: name, address, size and type for every function and static. .strtab holds those names.
.shstrtab holds the section names themselves.
.comment records the compiler and linker versions that built the file.
.ARM.attributes records the architecture, FPU and calling convention. Tools use it to spot incompatible objects, such as soft-float code in a hard-float build. Add --arch-specific to the readobj command to see it.

Thrown away at link time

.ARM.exidx and .ARM.extab hold unwinding tables for panics that unwind. This target aborts on panic instead, so cortex-m-rt's linker script discards them.
.got, the global offset table, serves position-independent code. cortex-m-rt keeps it only to fail the link if anything needs one, so it should always be empty.

Where the bytes land

rp235x-hal blinky linked by cortex-m-rt; addresses increase downward

Flash (XIP) at 0x1000_0000           RAM at 0x2000_0000
+------------------------------+     +--------------------------------+
| Vector table                 |  +->| .data                          |
|   initial SP, then handler   |  |  |   statics with initial values  |
|   addresses                  |  |  +--------------------------------+
+------------------------------+  |  | .bss                           |
| .start_block                 |  |  |   statics that start at zero;  |
|   IMAGE_DEF, then picotool's |  |  |   zeroed at reset, no flash    |
|   header; must sit in the    |  |  |   copy                         |
|   first 4 KB of flash        |  |  +--------------------------------+
+------------------------------+  |  |                                |
| .text                        |  |  |   free RAM                     |
|   your code plus the runtime |  |  |                ^               |
+------------------------------+  |  +----------------|---------------+
| .bi_entries                  |  |  | Stack                          |
|   picotool metadata          |  |  |   starts at 0x2008_0000 and    |
+------------------------------+  |  |   grows toward lower addresses |
| .rodata                      |  |  +--------------------------------+
|   constants and strings      |  |
+------------------------------+  |
| .data load copy              |--+  copied at reset
|   initial values for RAM     |
|   statics                    |
+------------------------------+

Only .data needs both regions: its initial values ship in flash and are copied to RAM before main. .bss gets no flash bytes at all.

Section by section, in flash

.vector_table sits at 0x1000_0000 and is 272 bytes long. Word 0 is the initial stack pointer and word 1 the reset handler. The next 14 words serve the Cortex-M33's own exceptions (NMI, HardFault, SVCall, PendSV, SysTick and others), then come 52 words, one per RP2350 interrupt line. The boot ROM reads the first two words at launch; the CPU reads the rest each time an exception fires.
.start_block follows at 0x1000_0110. It holds the 20-byte IMAGE_DEF, followed in current rp-hal by a 20-byte picotool binary-info header, 40 bytes in all. Your running code never touches either one. The IMAGE_DEF exists so the boot ROM accepts the image at all; the header tells picotool where .bi_entries lives.
.text is machine code: your functions, the HAL's, core's, and compiler helpers such as 64-bit division. Each function arrives in its own input section, so the linker can drop everything unreachable. That is why unused HAL code costs no flash. The CPU executes it in place from flash, through a cache.
.bi_entries is a table of pointers to picotool metadata such as the program name and version. Only picotool reads it.
.rodata holds constant data: string literals, immutable statics, lookup tables the compiler generates, and formatting strings when something prints. It is never written, so it never needs RAM.
The .data load copy holds the starting values for .data, packed after .rodata. The reset handler reads it exactly once.
.gnu.sgstubs holds TrustZone entry stubs, used only when firmware is split into Secure and Non-secure halves. Blinky's is empty.
.end_block is a reserved spot after everything else, where a signature or hash block can go for secure boot. Blinky leaves it empty.

Section by section, in RAM

.data holds statics that can change and start with nonzero values. It costs twice: flash for the starting values, RAM for the working copy.
.bss holds statics whose starting bytes are all zero. The reset handler zeroes the region, so it costs RAM and no flash. The name comes from a 1950s IBM 704 assembler directive, Block Started by Symbol.
.uninit holds statics you deliberately leave uninitialized. Reset neither copies nor zeroes it, so its contents survive a soft reset. That suits crash logs, and big buffers you fill anyway.
The stack is not a section. It starts at _stack_start (0x2008_0000) and grows down toward .uninit, holding local variables, saved registers, return addresses, and the frame the CPU pushes when an interrupt fires. Nothing stops an overflow by default; it silently overwrites your statics. Armv8-M's stack-limit register, MSPLIM, can turn that into a fault, and Lesson 2 sets it.
There is no heap until you add one. cortex-m-rt marks where one could begin with __sheap, and Lesson 9 adds a heap for Arc.
The two 4 KB banks at 0x2008_0000 and 0x2008_1000 sit outside the RAM region, unused for now. Lesson 9 gives each core its own stack there.

Where your Rust ends up

Rust item	Section	Why
Any `fn`, method, closure or generic instance	`.text`	Code runs in place from flash
`"hello"`, `b"bytes"`, `&[1, 2, 3]`	`.rodata`	Constant data, never written
`static LUT: [u8; 256] = [...]`	`.rodata`	Immutable static, so no RAM needed
`const MAX: u32 = 100`	none	A value, inlined wherever it is used
`static N: AtomicU32 = AtomicU32::new(7)`	`.data`	Can change, starts nonzero
`static N: AtomicU32 = AtomicU32::new(0)`	`.bss`	Can change, starts as zero bytes
`static mut BUF: [u8; 4096] = [0; 4096]`	`.bss`	4 KB of RAM, no flash
`let x = ...` inside a function	registers or stack	Lives only while the function runs
A `MaybeUninit` static with `#[unsafe(link_section = ".uninit.LOG")]`	`.uninit`	Untouched at reset

The rule: a static lands in RAM only if it can change, through static mut or interior mutability (atomics, Cell, UnsafeCell). Its starting bytes then decide between .data and .bss.

Try it: move a static between sections. Add these lines to blinky, rebuild, and compare cargo size --release --bin blinky -- -A before and after.

// Near the top of src/bin/blinky.rs
static mut BIG: [u8; 8192] = [0; 8192];

// Inside main, before the loop, so the linker keeps BIG
unsafe { core::ptr::write_volatile((&raw mut BIG).cast::<u8>(), 1) };

.bss grows by 8192 bytes and flash stays the same. Now change the initializer to [1; 8192]: .bss shrinks back, while .data and the flash image each grow by 8192.

The symbols that connect layout to code. cortex-m-rt's linker script defines symbols at the boundaries it draws. They are addresses with no storage behind them, and the reset handler reads them to know what to copy and what to clear.

Symbol	Marks
`__sidata`	Start of the initial values for `.data` in flash (its LMA)
`__sdata`, `__edata`	Start and end of `.data` in RAM
`__sbss`, `__ebss`	Start and end of `.bss` in RAM
`_stack_start`	Initial stack pointer, at the top of `RAM`

cargo nm --release --bin blinky \
  | grep -E '__s(i)?data|__edata|__[se]bss|_stack_start'

__sidata is where the starting values for .data begin in flash, right after .rodata. In stock blinky .data is empty, so __sidata equals __erodata and the program headers have no .data segment to compare with. Run the experiment above with [1; 8192] and a new LOAD segment appears with VirtAddr 0x2000_0000 and PhysAddr equal to __sidata. In Lesson 2, your own reset handler copies from __sidata into __sdata..__edata, zeroes __sbss..__ebss, then calls main.

Run these from rp-hal/rp235x-hal-examples, so its .cargo/config.toml applies:

# Sections with sizes and addresses: 0x1000_xxxx is flash, 0x2000_xxxx is RAM
cargo size --release --bin blinky -- -A

# Section headers: VMA is where a section runs, LMA is where it is stored
# --show-lma adds the load address column; LLVM's objdump hides it by default
cargo objdump --release --bin blinky -- -h --show-lma

# Raw bytes of the vector table and the boot block
cargo objdump --release --bin blinky -- -s -j .vector_table
cargo objdump --release --bin blinky -- -s -j .start_block

# The 15 biggest symbols, and where key ones landed
cargo nm --release --bin blinky -- --print-size --size-sort | tail -n 15
cargo nm --release --bin blinky | grep -E 'IMAGE_DEF|Reset|main'

What to look for

In the -h --show-lma output, .data is the one section whose VMA (RAM) differs from its LMA (flash). With an empty .data, the difference is still there but covers zero bytes.
The vector table's first word is the initial stack pointer. Expect 0x20080000, the end of the 512 KB RAM region in memory.x. objdump prints bytes in memory order, so it shows as 00000820.
The second word is the reset handler's address, and it is odd. Bit 0 marks Thumb code.
.start_block holds 40 bytes. The first 20 are the IMAGE_DEF, from d3deffff to 793512ab: the block's start and end markers, stored little-endian. Lesson 1 decodes the 12 bytes between them. The next 20, from f2eb8871 to 90a31ae7, are picotool's binary-info header. They hold the addresses of __bi_entries_start, __bi_entries_end and a mapping table.
.text starts right after .start_block, because memory.x sets _stext there.
You may see more than one symbol containing main. Lesson 2 explains why.

From ELF to flash image

Flash holds a plain image, not the ELF. objcopy extracts exactly those bytes, so you can compare the two directly:

cargo objcopy --release --bin blinky -- -O binary blinky.bin
ls -l blinky.bin
find .. -path '*/thumbv8m.main-none-eabihf/release/blinky' -exec ls -l {} \;
xxd blinky.bin | head -n 2      # or: hexdump -C blinky.bin | head -n 2

The .bin is small, around 8 KB. The ELF is many times larger, and almost all of the difference is debug info.
Byte 0 of blinky.bin is address 0x1000_0000. Its first 8 bytes are the stack pointer and reset vector you read back in the next section.
This is everything the boot ROM ever sees: no headers and no names, just bytes at addresses. IMAGE_DEF is how it recognizes them as a program.
UF2, the format behind BOOTSEL drag-and-drop, carries the same bytes in 256-byte chunks, each tagged with its target address.

Try it: add up the FileSiz of every LOAD segment whose PhysAddr is in flash, then compare the total with the size of blinky.bin. Explain any difference.

Coming in Lesson 4: defmt adds a .defmt section without the A flag. Every log message's format string lives there, in the ELF on your PC. The chip sends only a small index, and probe-rs looks the string up.

Read it back from the chip

The bytes objdump showed now sit in flash at 0x1000_0000. Reading them back closes the loop between the file on your disk and the silicon.

# Vector table: initial stack pointer, then the reset vector
probe-rs read --chip RP235x b32 0x10000000 2

# The boot block, at the IMAGE_DEF address cargo nm printed (0x10000110)
probe-rs read --chip RP235x b32 0x10000110 5

probe-rs prints whole 32-bit words, so the stack pointer reads 20080000 here rather than objdump's 00000820. Same bytes, different presentation. The reset vector is an odd address just above the vector table, such as 10000139; the exact value depends on your rp-hal version. The boot block should read ffffded3 first and ab123579 last.

Bonus: watch a peripheral tick. TIMER0 starts at 0x400b0000. Find the offset of its raw low-word register, TIMERAWL, in the datasheet's TIMER register list, and add it to the base address. The offset alone points into the boot ROM, which never changes. Read the full address twice, a few seconds apart, and estimate the tick rate from the difference. That is your first peripheral register read; Lesson 3 starts writing them.

Set up the course workspace

Create the workspace now so Lesson 1 drops straight into it. Keep it separate from your rp-hal clone.

rp2350-course/
├── .cargo/config.toml
├── .helix/languages.toml
├── Cargo.toml
├── rust-toolchain.toml
└── lessons/            (Lesson 1 adds the first crate)

# Cargo.toml
[workspace]
resolver = "3"
members = []

[workspace.package]
edition = "2024"

[profile.release]
debug = 2   # full symbols in the ELF for probe-rs; none of it reaches flash

# .cargo/config.toml
[build]
target = "thumbv8m.main-none-eabihf"

[target.thumbv8m.main-none-eabihf]
rustflags = ["-C", "target-cpu=cortex-m33"]
runner = "probe-rs run --chip RP235x"

# rust-toolchain.toml
[toolchain]
channel = "stable"
targets = ["thumbv8m.main-none-eabihf"]
components = ["llvm-tools"]

# .helix/languages.toml
# Workspace-local Helix config, merged over your global languages.toml
[language-server.rust-analyzer.config]
check.allTargets = false

Three choices worth noticing:

No linker flags at the root. Lesson 1's crate links with a script you write, and Lesson 4 switches to cortex-m-rt's, so each crate's build.rs passes its own.
target-cpu=cortex-m33 lets the compiler use the M33's DSP instructions and tune for its pipeline.
check.allTargets = false stops rust-analyzer checking test targets, which need std and can't build for this target. rust-analyzer already picks up the target from .cargo/config.toml, so Helix needs nothing else. If diagnostics look wrong, run hx --health rust from inside rp2350-course/.

Run git init too. You will want to diff your from-scratch code against rp-hal's later.

Exercises and self-check

Exercises

Change the blink timing in src/bin/blinky.rs, for example 100 ms on and 900 ms off, and reflash. Note how much faster the second build is.
Build blinky in debug and in release, and compare their .text sizes from cargo size -- -A. Explain the gap, and why debug info isn't the cause.
List the five largest functions with cargo nm. Guess what each does from its name.
Run picotool info -a target/thumbv8m.main-none-eabihf/release/blinky -t elf. Match each line of output to the source that produced it.
Run probe-rs read a few times while watching the LED. Does it keep its rhythm, and what does that suggest about how the probe reaches memory?

Self-check

Why does .data take space in both flash and RAM, while .bss takes RAM only?
Why is the initial stack pointer 0x20080000, and which way does the stack grow from there?
Why is the reset vector an odd number?
memory.x puts .start_block right after the vector table. What would happen if it landed after 10 KB of .text instead?
Which pieces in the magic inventory run before main is called?

Next: Lesson 1: Anatomy of an RP2350 Image.

Part of Embedded Rust on the RP2350.

Sunlight to Server

kevstewa@protonmail.com (Kevin Stewart) — Mon, 27 Nov 2023 00:00:00 +0000

Charting my Course for a Low-Impact Web Presence

With the hectic clamor of summer and fall coming to a close, it seems I can once again dream up projects that might actually come to fruition. I've been tossing around an idea for a while now, heavily inspired by Low<-Tech Magazine and their solar-powered website, of self-hosting my website locally on a small Kubernetes cluster.

The major motivation for this project comes from a desire to reduce my impact and explore how we can exceed the value provided by turn-key solutions and profit motivated corporations. As we barrel down the tracks towards climate catastrophe and are ultimately consumed by the Goliath that is capitalism, I can hold my head above water even if for a minute and claim that this is one of my small efforts towards sustainability.

Hardware

Compute

The core of the platform will be a set of four Odroid-MC1 devices. These were originally intended for the purpose of small, personal clusters. I have successfully used K3s on top of Armbian for learning the basics of Kubernetes by running cloudflared for DoH to back my Pi-hole.

Power

I have experience with more complex solar setups but for the sake of keeping things simple and cheap, my eye falls on a Renogy 10A charge controller. This is plenty of allowance for even a relatively large panel. I have an old ~20Ah SLA batter kicking around somewhere in the dungeon I can resurrect as well. Together these should get me going.

Software

OS

The current choice is Armbian as there is excellent support for these boards with relatively recent kernels.

Web Server

I'm leaning towards Nginx since I'm not super familiar and would like to learn. Apache is my comfort zone and I'll come back to that if necessary or I get too lazy. If I remember correctly, these boards are arm32v6 and both webservers have container images for this architecture.

Kubernetes

Here I'll be leaning on the wonderful K3s project for these tiny systems. This is should be obvious.

Cluster Datastore

I'll probably stick with etcd for now but have used a Postgres database previously. This will depend on whether I replace my aging NAS disks.

Text Editor

Vim.

Closing Thoughts

Yes, this is needlessly complex for my website and traffic. What can I say? I like to learn and I've got the devices hanging around collecting dust.

This is by no means an exhaustive exploration of my idea and it will flesh out over time. I'm slow at executing projects so this likely will be a long time in the works with plenty of time for updates and changes.

OpenBSD: Installing WiFi Firmware for a MacBook Pro

kevstewa@protonmail.com (Kevin Stewart) — Sat, 14 Jan 2023 00:00:00 +0000

After coming into a possession of an Early 2015 MacBook Pro, it turned out to be a perfect opportunity to install OpenBSD. This crystallized as a result of having some older, but still perfectly performant hardware, along with my recent run-ins with principles related to permacomputing. The latter deserves a future post all on its own, but in short the ideas center around resilience, sustainability, and our relationships with hardware and software.

This particular device has an Intel i5-5257U CPU, 8GB RAM, a 120GB SSD, and a Retina display. Installing OpenBSD 7.2 was rather uneventful and less involved than my experience with FreeBSD. Due to licensing, not all firmware is able to be shipped with the base install so I took the route of post-install configuration.

Not knowing exactly what I needed, save for the wireless device, I downloaded all files located at firmware.openbsd.org for 7.2. Download firmware specific to your release.

$ wget -r --no-parent https://firmware.openbsd.org/firmware/7.2/

I moved these files to a USB flash drive, mounted the device on the MacBook, and ran the fw_update utility.

# doas mkdir /mnt/usb_drive
# doas mount /dev/sd2i /mnt/usb_drive
# cd /mnt/usb_drive
# doas fw_update -p .

You should see output similar to that listed below:

fw_update: added bwfm,intel,inteldrm,vmm; updated none; kept none

And that's really all there is to it. Be sure to follow up with an appropriately configured /etc/hostname.xxx file for the device, in this case bwfm0, and reboot.

Retrocausation

kevstewa@protonmail.com (Kevin Stewart) — Tue, 13 Dec 2022 00:00:00 +0000

A quick note--I've recently committed to restructuring the sort of content I post here. While technology is at the forefront of my interests, prepare for rambling on the many others.

I'm re-reading Time Loops by Eric Wargo after a recent and particularly reinvigorating syncronicity. I would recommend this book to anyone and I'm excited to explore his relatively new book that I just found out about, Precognitive Dreamwork and the Long Self. He also has an interesting blog at thenightshirt.com.

This had seeded interest in Philip K. Dick on the first go and I'm excited to continue down that path. I'd also like to read Story of Your Life by Ted Chiang. This was inspiration for the film Arrival, one of my top 5 movies.

Anyway, I've had a refocus on precognition with the aforementioned synchronicity and several others. They seem to come in waves; I wonder if it is just awareness instead of any true increase. Regardless, they will certainly increase as I make my way through this book, just as it happened last time. Maybe I should start sharing them here...

Website Revival

kevstewa@protonmail.com (Kevin Stewart) — Sun, 11 Dec 2022 00:00:00 +0000

When I began working on this website about a year and a half ago, it was biased by a job hunt. At the time, I wasn't satisfied with where I was at in my career. To advance, it was ideal to have a place to demonstrate some level of skill. As a result, I treated the content very mechanically and the authenticity I am now hunting for suffered.

While I grew up with the internet in a state more or less functionally similar to what we have today, it was amorphous and I lacked context for what it represented and how it was structured; a story as old as time, not understanding what you have until it's gone. I want reduction in centralization and walled gardens. I want less dependencies and more efficiency. Most of all, I want to cultivate exploration in this intangible landscape.

I'm now reapproaching the content, structure, and mindset that goes in to having my personal corner of the World Wide Web. Already magnetically attracted to minimalism and simplicity in the analog, carrying these practices to my digital life has been a long-standing target. Along with the feel of my personal site never sitting quite right, I've been further driven by recent articles such as this one by Bradley Taut or another by Tania Rascia to focus less on fitting content within an imaginary box.

So here it is--a rebuild from the ground up. I've started from zero. No themes, no pre-built CSS, nada. There is, of course, copy-pasted snippets and inspriation from many sources, but this incantation of symbols is 100% unique. By just pressing buttons in the right order, I've finally got something I can call my own--a place for me to treat mindfully knowing how it works from the bottom up, a place without pretension or bias or rigor. It can just exist as it is. Welcome...

Automount Home Directories on CentOS 8 With FreeIPA

kevstewa@protonmail.com (Kevin Stewart) — Mon, 23 Aug 2021 00:00:00 +0000

FreeIPA is an identity management solution combining LDAP, Kerberos, NTP, and DNS, among others. I have deployed this in production for our small business to manage users across several satellite retail and production locations. Currently I have no shared home directory set up so when a user moves to a different workstation, they must reconfigure their GNOME and Firefox settings. This has minimal impact right now as users are usually using a single workstation to complete computer-related tasks, but in preparation for business growth, as well as catering to the unique users moving across multiple facilities, I will be testing out NFS-based automounting home directories.

This guide expects you can configure your server securely and does not attempt to cover all possible configurations. Shortcuts are taken as this is a lab setup in a VLAN with limited ingress and egress access. I will utilize three VMs, all running CentOS 8 starting with a minimal install and additionally adding the standard and guest tools as via the graphical installer. Our lab environment is as follows:

idm1.example.com as 10.0.51.150
nfs.example.com as 10.0.51.151
client.example.com as 10.0.51.152

idm1.example.com

idm1 will be our identity management (idm) server running FreeIPA. This will be set up as a standalone service (no replicas) with integrated DNS and with an integrated CA as the root CA.

Setup

After logging in as root, update the server and install the necessary packages, first enabling the module containing the idm software:

# dnf module enable idm:DL1
# dnf distro-sync
# dnf module install idm:DL1/dns

I chose idm:DL1/dns as I am installing with integrated DNS. Other options exist and you should familiarize yourself with them here.

Next, I'll open the appropriate firewall ports using firewall-cmd. Service definitions found in /usr/lib/firewalld/services make this easy -- just add freeipa-4 and dns (the freeipa-ldap/s and related service files have been deprecated).

# firewall-cmd --permanent --add-service={freeipa-4,dns}
# firewall-cmd --reload

You should now see these services added:

# firewall-cmd --list-all
public (active)
  target: default
  icmp-block-inversion: no
  interfaces: ens18
  sources: 
  services: cockpit dhcpv6-client dns freeipa-4 ssh
  ports: 
  protocols: 
  masquerade: no
  forward-ports: 
  source-ports: 
  icmp-blocks: 
  rich rules:

Finally, add the hostname and IP information to the /etc/hosts file so our server can reference itself for proper domain setup:

# echo "10.0.51.150 idm1.example.com idm1" >> /etc/hosts

Install

This part is relatively straightforward. I'll run the install command and, for the most part, accept the default values. Pay attention to the prompts as some defaults cause an abort or can uncover configuration mistakes, particularly with the assumed domain. Much of the output of the command below has been cut for brevity's sake:

# ipa-server-install 

The log file for this installation can be found in /var/log/ipaserver-install.log
==============================================================================
This program will set up the IPA Server.
Version 4.9.2

Do you want to configure integrated DNS (BIND)? [no]: yes
Server host name [idm1.example.com]: 
Please confirm the domain name [example.com]: 
Please provide a realm name [EXAMPLE.COM]: 

Directory Manager password: 
Password (confirm): 

IPA admin password: 
Password (confirm): 

Do you want to configure DNS forwarders? [yes]:

Following DNS servers are configured in /etc/resolv.conf: 1.1.1.1, 1.0.0.1
Do you want to configure these servers as DNS forwarders? [yes]: 
Enter an IP address for a DNS forwarder, or press Enter to skip: 

Do you want to search for missing reverse zones? [yes]: 
Do you want to create reverse zone for IP 10.0.51.150 [yes]: 
Please specify the reverse zone name [51.0.10.in-addr.arpa.]: 

Do you want to configure chrony with NTP server or pool address? [no]: 

The IPA Master Server will be configured with:
Hostname:       idm1.example.com
IP address(es): 10.0.51.150
Domain name:    example.com
Realm name:     EXAMPLE.COM

The CA will be configured with:
Subject DN:   CN=Certificate Authority,O=EXAMPLE.COM
Subject base: O=EXAMPLE.COM
Chaining:     self-signed

BIND DNS server will be configured to serve IPA domain with:
Forwarders:       1.1.1.1, 1.0.0.1
Forward policy:   only
Reverse zone(s):  51.0.10.in-addr.arpa.

Continue to configure the system with these values? [no]: yes

...

==============================================================================
Setup complete

Next steps:
	1. You must make sure these network ports are open:
		TCP Ports:
		  * 80, 443: HTTP/HTTPS
		  * 389, 636: LDAP/LDAPS
		  * 88, 464: kerberos
		  * 53: bind
		UDP Ports:
		  * 88, 464: kerberos
		  * 53: bind
		  * 123: ntp

	2. You can now obtain a kerberos ticket using the command: 'kinit admin'
	   This ticket will allow you to use the IPA tools (e.g., ipa user-add)
	   and the web user interface.

Be sure to back up the CA certificates stored in /root/cacert.p12
These files are required to create replicas. The password for these
files is the Directory Manager password
The ipa-server-install command was successful

That's it for the idm server. I'll use the ipa command line utilities for adding users and NFS service in the next part.

nfs.example.com

This server will be enrolled in our idm and provide our NFS server.

Setup

Again, we're starting on a fresh minimal install as root. I'll update the server and make sure the necessary utilities are installed. No need for installing the idm:DL1 stream -- the ipa-client is available in the repositories.

# dnf update
# dnf install nfs-utils ipa-client

I'll go ahead and add additional services allowed via firewalld:

# firewall-cmd --permanent --add-service={nfs,mountd,rpc-bind}
# firewall-cmd --reload

Output should confirm:

# firewall-cmd --list-all
public (active)
  target: default
  icmp-block-inversion: no
  interfaces: ens18
  sources: 
  services: cockpit dhcpv6-client mountd nfs rpc-bind ssh
  ports: 
  protocols: 
  masquerade: no
  forward-ports: 
  source-ports: 
  icmp-blocks: 
  rich rules:

For the last setup task, I'll enroll this host with our previously created idm host. Make sure your nameserver in /etc/resolv.conf points to the idm host and verify your search domain is correct as well. Once again, pay attention to default values.

# cat /etc/resolv.conf
search example.com
nameserver 10.0.51.150

# ipa-client-install -p admin -W
This program will set up IPA client.
Version 4.9.2

Discovery was successful!
Do you want to configure chrony with NTP server or pool address? [no]: 
Client hostname: nfs.example.com
Realm: EXAMPLE.COM
DNS Domain: example.com
IPA Server: idm1.example.com
BaseDN: dc=x,dc=example,dc=net

Continue to configure the system with these values? [no]: yes
Synchronizing time
No SRV records of NTP servers found and no NTP server or pool address was provided.
Using default chrony configuration.
Attempting to sync time with chronyc.
Time synchronization was successful.
Password for admin@EXAMPLE.COM: 
Successfully retrieved CA cert
    Subject:     CN=Certificate Authority,O=EXAMPLE.COM
    Issuer:      CN=Certificate Authority,O=EXAMPLE.COM
    Valid From:  2021-08-23 21:00:55
    Valid Until: 2041-08-23 21:00:55

Enrolled in IPA realm EXAMPLE.COM
Created /etc/ipa/default.conf
Configured sudoers in /etc/authselect/user-nsswitch.conf
Configured /etc/sssd/sssd.conf
Configured /etc/krb5.conf for IPA realm EXAMPLE.COM
Systemwide CA database updated.
Hostname (nfs.example.com) does not have A/AAAA record.
Missing reverse record(s) for address(es): 10.0.51.151.
Adding SSH public key from /etc/ssh/ssh_host_ecdsa_key.pub
Adding SSH public key from /etc/ssh/ssh_host_ed25519_key.pub
Adding SSH public key from /etc/ssh/ssh_host_rsa_key.pub
SSSD enabled
Configured /etc/openldap/ldap.conf
Configured /etc/ssh/ssh_config
Configured /etc/ssh/sshd_config
Configuring example.com as NIS domain.
Client configuration complete.
The ipa-client-install command was successful

Install

To start I will obtain a Kerberos ticket:

# kinit admin

Next I'll create an NFS service entry:

# ipa service-add nfs/nfs.example.com
---------------------------------------------------------------------------
Added service "nfs/nfs.example.com@EXAMPLE.COM"
---------------------------------------------------------------------------
  Principal name: nfs/nfs.example.com@EXAMPLE.COM
  Principal alias: nfs/nfs.example.com@EXAMPLE.COM
  Managed by: nfs.example.com

Follow this with a keytab retrieval:

# ipa-getkeytab -s idm1.example.com -p nfs/nfs.example.com -k /etc/krb5.keytab
Keytab successfully retrieved and stored in: /etc/krb5.keytab

I'll verify that everything looks good using ipa service-show:

# ipa service-show nfs/nfs.example.com
  Principal name: nfs/nfs.example.com@EXAMPLE.COM
  Principal alias: nfs/nfs.example.com@EXAMPLE.COM
  Keytab: True
  Managed by: nfs.example.com

Configure the NFS settings:

# ipa-client-automount
Searching for IPA server...
IPA server: DNS discovery
Location: default
Continue to configure the system with these values? [no]: yes
Configured /etc/idmapd.conf
Restarting sssd, waiting for it to become available.
Started autofs

We're getting close. Next I'll add the exports using the krb5p security setting. I'm just going to export the home directory but you can use a different directory (or multiple directories) if you so desire.

# echo "/home  *(rw,sec=krb5:krb5i:krb5p)" > /etc/exports

Let's enable and start NFS, and verify our directory exports:

# systemctl enable --now nfs-server.service
# export -rav
exporting *:/home
# showmount -e
Export list for nfs.example.com:
/home *

Finally, I am going to create the automount map:

# ipa automountmap-add-indirect default auto.home --mount=/home
-------------------------------
Added automount map "auto.home"
-------------------------------
  Map: auto.home

...and key:

# ipa automountkey-add default auto.home --key "*" --info "nfs.example.com:/home/&"
-----------------------
Added automount key "*"
-----------------------
  Key: *
  Mount information: nfs.example.com:/home/&

Now we can create a user and their home directory. As we are exporting home, we won't need to move anything around.

# ipa user-add --first McCoy --last Pauley --password --shell=/bin/bash
User login [mpauley]: 
Password: 
Enter Password again to verify: 
--------------------
Added user "mpauley"
--------------------
  User login: mpauley
  First name: McCoy
  Last name: Pauley
  Full name: McCoy Pauley
  Display name: McCoy Pauley
  Initials: MP
  Home directory: /home/mpauley
  GECOS: McCoy Pauley
  Login shell: /bin/bash
  Principal name: mpauley@EXAMPLE.COM
  Principal alias: mpauley@EXAMPLE.COM
  User password expiration: 20210823214024Z
  Email address: mpauley@example.com
  UID: 873600003
  GID: 873600003
  Password: True
  Member of groups: ipausers
  Kerberos keys available: True

# mkhomedir_helper mpauley 077

I'm going to create a text file to verify our NFS automounted home on our client next:

# echo "It works!" > /home/mpauley/test-file.txt
# chown mpauley: /home/mpauley/test-file.txt

client.example.com

Our client will have no services installed but will be enrolled in the idm server to see if our effort has paid off. We should see that our test file exists in the user's home directory.

Setup

I won't repeat the full steps here. Refer back to the previous sections if you need guidance.

Update packages.
Install ipa-client.
Ensure the resolv.conf points to the idm server.
Run ipa-client-install.
Run ipa-client-automount.

I briefly tested this with GNOME as well, receiving subsequent AVC denials. In my case, this easily resolved by enabling an SELinux boolean*:

# sebool -P use_nfs_home_dirs 1

* Thanks to /u/Smithore for the reminder!

The Big Test

Once these steps are complete, log out of the server and log in as our newly created user, mpauley:

$ ssh mpauley@client.example.com

(mpauley@10.0.51.152) Password:

$ ls -lh
total 4.0K
-rw-r--r--. 1 mpauley mpauley 43 Aug 23 19:43 test-file.txt
$ cat test-file.txt
It works!

Conclusion

While this example was merely a proof-of-concept for my further planning and was deliberately quite simple, we can of course dive in to the rabbit-hole of complexity these tools provide. I look forward to rolling this out, but perhaps I'll wait until I can beg for a few more bits through tiny pipes at a couple of sites. ¯\_(ツ)_/¯

Raspberry Pi 4 and FreeBSD 13 - The Unbootening

kevstewa@protonmail.com (Kevin Stewart) — Mon, 16 Aug 2021 00:00:00 +0000

While it's relatively straight forward to install FreeBSD 13.0-RELEASE on the Raspberry Pi 4, I ran in to a particular issue that warrants additional visibility.

A simple dd gets our extracted image on the SD card:

$ sudo dd if=FreeBSD-13.0-RELEASE-arm64-aarch64-RPI.img of=/dev/{OUTPUT DEVICE} bs=4M status=progress
$ sync

After inserting the SD card and attempting to boot, however, is where the issue arose. I enabled the UART in the U-Boot config.txt within the MSDOSBOOT partition and hooked up a serial cable.

[all]
arm_64bit=1
dtparam=audio=on,i2c_arm=on,spi=on
dtoverlay=mmc
dtoverlay=disable-bt
device_tree_address=0x4000
kernel=u-boot.bin
enable_uart=1

...

After getting some output from U-Boot in the serial console, it appears that the bootloader is not recognizing the partition table (or a related issue that causes this error).

...

Hit any key to stop autoboot: 0 
switch to partitions #0, OK 
mmc0 is current device 
** No partition table - mmc 0**

Device 0: unknown device 
ethernet@7d580000 Waiting for PHY auto negotiation to complete...

...

I wasn't finding what I needed through my go-to search engines but a hop, skip, and a jump over to the FreeBSD Forums quickly yielded this post which helpfully pointed to Bug 255080 solving the issue.

Comment #15 provides a link to the 2021.04 build of the U-Boot binary. Overwrite the u-boot.bin file that lives in the MSDOSBOOT partition base directory and you'll be on your way!

It looks as though the part SKUs have been adjusted slightly and the 2020.10 U-Boot version does not account differing changes in certain models of the RPi 4 and Pi 400. From what it seems, the fix is expected in the next release.

Reviving the Ubiquiti loco M5

kevstewa@protonmail.com (Kevin Stewart) — Sat, 03 Jul 2021 00:00:00 +0000

I've had a pair of Ubiquiti NanoStation loco M5 devices operating continually for around 5 years. They were finally decommissioned in 2020, but recently were revived for a project at work temporarily bridging two buildings while I transferred premesis equipment. I suppose it goes without saying that of course I was pressed for time and of course this would be a simple in-and-out. It also goes without saying that of course things didn't work out as intended and of course these device decided that their previous life of working 24/7 was over and retirement was in full swing.

Hours went by, and every time I actually got the devices to boot and grab an IP they would mysteriously disappear on the network after any configuration changes. A seemingly endless cycle of reboots, resets, and re-applicaiton of configs and I felt like Jerry Seinfeld in the lobby of The Chinese Restaurant. After wishing, begging the Silicon Gods for mercy, they miraculously held a config. They booted back up and linked. Not wont for disrupting the delicate balance I just afforded myself, I tiptoed out convincing myself "Sure, they had been working for years with not even a peep - nothing to worry about". Not two hours later, they were down. Not three and an ethernet cable was run. My hours of hair-pulling were enshrined in two white plastic figurines and a long blue stretch of Cat6.

All said and done, I got them home and now neither were grabbing IPs, regardless of how many times I power cycled. There wasn't a hint of network traffic. No worries - I'll take any excuse to break out the serial cable and start poking around.

Opening the case we find an unpopulated header, J5. Heading over to the OpenWRT Table of Hardware shows us the pinout.

I'm going to use Minicom pointed at ttyUSB0, baud 115200, 8N1. Don't forget to disable hardware flow control and enable software flow control under cOnfigure Minicom -> Serial port setup.

$ minicom -D /dev/ttyUSB0

Adding a header, powering up the device, the hardware appears to initialize and we get...

U-Boot 1.1.4-gb02ecccc (Feb 14 2020 - 10:53:11) 

DRAM:  64 MB                                   
Flash:  8 MB (0xc2, 0x20, 0x17)
Net:   AR8032 Detected                         
eth0, eth1                                     
Board: Ubiquiti Networks AR9342 board (e845-32564.1122.0030)
Radio: 0777:e845                               
Reset: Normal                                  
Hit any key to stop autoboot:  0 
## Booting image at 9f050000 ...
   Image Name:   MIPS Ubiquiti Linux-2.6.32.71
   Created:      2020-07-15  13:28:25 UTC
   Image Type:   MIPS Linux Kernel Image (lzma compressed)
   Data Size:    979899 Bytes = 956.9 kB
   Load Address: 80002000
   Entry Point:  80002000
   Verifying Checksum at 0x9f050040 ...OK
   Uncompressing Kernel Image ... OK

Starting kernel ...

Booting Atheros AR934x

...nowhere. It sits mocking me with it's single blinking ~~eye~~ LED, going no further.

Well, it may be a hardware issue. There's no damage visible on the PCB or evidence of water intrusion. If a fault exists, it might be a component. This project might be hitting a dead end. No sense in wasting time, however; let's head back to OpenWRT and grab the latest bin for this device (19.07.7 at the time of writing). My particular units are the "newer" XW model, not the XM. The XW models use the Atheros AR9342 chips which can be seen in the initial serial output. I have attempted to upload an XM image to the XW model and the firmware check appropriately rejects it.

With the device powered off, hold the reset button, and power back on. Hold the reset button until you get alternating flashing lights on the device indicating the TFTP mode is initializing. On the serial output, you'll see:

BOOTP broadcast 1
Sending discovery response
*** Unhandled DHCP Option in OFFER/ACK: 28
*** Unhandled DHCP Option in OFFER/ACK: 28
DHCP client bound to address 192.168.1.108
Starting TFTP server... 
Using eth0 (192.168.1.108), address: 0x81000000 
Will reset device configuration (Reset button active after 10 seconds).
Erasing sector 123..126 

First 0x7b last 0x7e sector size 0x10000
.... done
Waiting for connection: Sending discovery response

If momentarily paused at "Starting TFTP server...", continue holding the reset button until the configuration is erased. At that point it will be ready for a TFTP connection. Hop over to the tftp utility or your equivalent. Be sure to put your client in binary mode and enable tracing for some additional feedback.

$ tftp 192.168.1.108
tftp> binary
tftp> trace
Packet tracing on.

When ready, upload the image and the M5 takes care of the rest.

tftp> put openwrt-19.07.7-ar71xx-generic-ubnt-loco-m-xw-squashfs-factory.bin

On the other end, you'll see the M5 receiving the data, writing the flash sectors, and confirmation when the update is complete.

Received 4194716 bytes
Firmware Version: XW.ar934x.v6.0.4-42.OpenWrt-r11306-c4a6851c72
Setting U-Boot environment variables
Un-Protected 1 sectors
Erasing Flash.... done
Erased 1 sectors
Writing to Flash... write addr: 9f040000
done
Protected 1 sectors
Copying partition 'kernel' to flash memory:

First 0x5 last 0x14 sector size 0x10000
................ done
write addr: 9f050000
Copying partition 'rootfs' to flash memory:

First 0x15 last 0x7a sector size 0x10000
................ done
write addr: 9f150000

Firmware update complete.

Resetting...

Okay, so the moment of truth. Are we going to get off, scot-free? Is it possible it's just going to work?

U-Boot 1.1.4-gb02ecccc (Feb 14 2020 - 10:53:11) 

DRAM:  64 MB                                   
Flash:  8 MB (0xc2, 0x20, 0x17)
Net:   AR8032 Detected
eth0, eth1
Board: Ubiquiti Networks AR9342 board (e845-32564.1122.0030)
Radio: 0777:e845
Reset: Normal
Hit any key to stop autoboot:  0 
## Booting image at 9f050000 ...
   Image Name:   MIPS OpenWrt Linux-4.14.221
   Created:      2021-02-15  15:22:37 UTC
   Image Type:   MIPS Linux Kernel Image (lzma compressed)
   Data Size:    1589435 Bytes =  1.5 MB
   Load Address: 80060000
   Entry Point:  80060000
   Verifying Checksum at 0x9f050040 ...OK
   Uncompressing Kernel Image ... OK

Starting kernel ...

[    0.000000] Linux version 4.14.221 (builder@buildhost) (gcc version 7.5.0 (1
[    0.000000] bootconsole [early0] enabled                                    
[    0.000000] CPU0 revision is: 0001974c (MIPS 74Kc)                          
[    0.000000] SoC: Atheros AR9342 rev 2                                       
[    0.000000] Determined physical RAM map:                                    
[    0.000000]  memory: 04000000 @ 00000000 (usable)
...

Turns out, yeah! It boots up and provides a serial terminal. We use UCI to set DHCP on the ethernet port to connect and configure, and to stop the DHCP server from attempting to hand out leases. Restart the network service and we've got a fully functioning device with OpenWRT.

  _______                     ________        __
 |       |.-----.-----.-----.|  |  |  |.----.|  |_
 |   -   ||  _  |  -__|     ||  |  |  ||   _||   _|
 |_______||   __|_____|__|__||________||__|  |____|
          |__| W I R E L E S S   F R E E D O M
 -----------------------------------------------------
 OpenWrt 19.07.7, r11306-c4a6851c72
 -----------------------------------------------------
=== WARNING! =====================================
There is no root password defined on this device!
Use the "passwd" command to set up a new password
in order to prevent unauthorized SSH logins.
--------------------------------------------------
root@OpenWrt:/# uci set network.lan.proto=dhcp
root@OpenWrt:/# uci commit && service network restart

Whaddya know? The devices appear to be stable and I haven't run in to any issues yet, though they certainly won't be seeing a production environment and can rest easy in retirement. Perhaps we'll see them again in a future project, but until then, thanks for stopping by and see you around!

GIS Beginnings

kevstewa@protonmail.com (Kevin Stewart) — Mon, 10 May 2021 00:00:00 +0000

Having patiently been awaiting attention on the always growing list of to-dos, I've finally directed focus towards GIS (geographic information system). Making sense of maps has been a big component in many of my personal pursuits and merging that with the extensibility of the digital world is an obvious next step.

I'm going to start with Mapbox to practice making basic requests to their API:

import os
import requests
import urllib.parse
import mercantile

ACCESS_TOKEN = os.environ['MAPBOX_ACCESS_TOKEN']
USER_NAME = os.environ['MAPBOX_USER_NAME']
BASE_PATH = "https://api.mapbox.com"

STYLES_ENDPOINT = "/styles/v1/"
TILESET_ENDPOINT = "/v4/"

if __name__ == "__main__":

    # List Styles ####################################################

    # Format: /styles/v1/{username}/{style_id}

    query_string = {'access_token': ACCESS_TOKEN}
    query_string = urllib.parse.urlencode(query_string)

    request_url = f"{BASE_PATH}{STYLES_ENDPOINT}{USER_NAME}?{query_string}"

    try:
        response = requests.get(request_url)
    except requests.exceptions.RequestException as error:
        print(error)
    else:
        print(request_url)
        print("Status: ", response.status_code)
        print(response.json())

A quick whip-up, no doubt, but here we test pulling custom styles first, not too interesting. I used their Outdoor map style and made a few tweaks to make a custom style.

Second, we pull vector tiles in mvt format. The tileset referenced was from my Bridger Ridge Run race in 2019, the good ol' pre-pandemic days.

The tileset was made by first taking the GPX file and running it through a Mapbox provided JavaScript tool togeojson to obtain, well, a GeoJSON file. Installing via NPM, you can feed in a GPX file and direct stdout to the required file type.

Once in the GeoJSON format, we can use tippecanoe to convert to an MBTiles database and upload to Mapbox either via Studio or the Uploads API. To save time for now though, I uploaded through Studio.

Now that a tileset exists in Studio, we can pull the associated tiles using the Vector Tiles API:

# Retrieve custom tileset #################################################
    
    # Format: /v4/{tileset_id}/{zoom}/{x}/{y}.{format}

    tileset_id = "kevstewa.2jgs4lck"
    zoom = "16"

    tile = mercantile.tile(-110.947, 45.848, 16)
    x = tile.x
    y = tile.y

    tile_format = "mvt"

    query_string = {'access_token': ACCESS_TOKEN}
    query_string = urllib.parse.urlencode(query_string)

    request_url = f"{BASE_PATH}{TILESET_ENDPOINT}{tileset_id}/{zoom}/{x}/{y}.{tile_format}?{query_string}"

    try:
        response = requests.get(request_url)
    except requests.exceptions.RequestException as error:
        print(error)
    else:
        print(request_url)
        print("Status: ", response.status_code)
        print(response.content)

Here we use mercantile to get a specific tile's X and Y based on the coordinates and zoom level provided. That is passed along with the zoom level and format to the endpoint and back we get our data.

Many of these steps can be skipped by uploading the original formats to Studio for automatic conversion to a tileset, but that wasn't the purpose of this exercise. Next I'll be looking at creating a heatmap of all my Strava activities, this time using the uploads API and other features provided by Mapbox. Their documentation is very good and can be found at docs.mapbox.com.

Getting Rusty

kevstewa@protonmail.com (Kevin Stewart) — Mon, 03 May 2021 00:00:00 +0000

My current (and very much WIP) application is written in Python. I utilize Metrc's API via GET requests to build a local database of facilities, packages, harvests, sales, and transfers for further data analysis and it also provides an extremely efficient way of interacting with the traceability system that isn't a web app. Currently taking advantage of SQLite, a local database makes for a much smoother experience.

As of late, I've been going through the Rust book and the exercises provided by Rustlings to wet my whistle, as it were. I've got some light background in embedded programming and moving back to a lower level language has been attractive recently. Why not dive in to Rust?

It's been a lot of fun getting familiar with Rust idioms and design patterns. The book has been amazing for grasping fundamentals and I'm constantly dreaming up all the new ways I can refactor what I've got so far.

All this fluff is really just to demonstrate my two Metrc "Hello, world." style first-steps to a full rewrite, one using reqwest:

// The first attempt using reqwest.

use std::env;
use serde_json;

fn print_json(data: &str) {
    let v: serde_json::Value = serde_json::from_str(data).unwrap();

    println!("{:#?}", v);
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let user = env::var("METRC_VENDOR_API_KEY")?;
    let pass = env::var("METRC_USER_API_KEY")?;

    let client = reqwest::Client::new();

    let resp = client.get("https://api-mt.metrc.com/facilities/v1")
        .basic_auth(user.clone(), Some(pass.clone()))
        .send()
        .await?
        .text()
        .await?;

    print_json(&resp);

    Ok(())
}

...and another using the more bare-bones hyper:

use std::env;
use std::io::Write;
use hyper::{Client, Method, Request, Body};
use hyper_tls::HttpsConnector;
use base64::write::EncoderWriter as Base64Encoder;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
    let username = env::var("METRC_VENDOR_API_KEY")?;
    let password = env::var("METRC_USER_API_KEY")?;

    let mut header_value = b"Basic ".to_vec();
    let mut encoder = 
        Base64Encoder::new(&mut header_value, base64::STANDARD);
    
    write!(encoder, "{}:", username).unwrap();
    write!(encoder, "{}", password).unwrap();

    let req = Request::builder()
        .method(Method::GET)
        .uri("https://api-mt.metrc.com/facilities/v1/")
        .header("Authorization", header_value)
        .body(Body::empty())
        .expect("request builder");

    let https = HttpsConnector::new();
    let client = Client::builder()
        .build::<_, hyper::Body>(https);

    let response = client.request(req).await?;

    println!("Status: {}", response.status());

    let buf = hyper::body::to_bytes(response).await?;

    println!("Body: {:?}", buf);

    Ok(())
}

Hyper remains as advertised - a bit more involved as it's more like the bricks to build custom libraries from the ground up. One has to set up the https connector, as well as generate the basic authorization header value. There is a const in the header struct that I have yet to piece together called AUTHORIZATION.

I'm still wrapping my head around ownership and returning results, options, and using traits but I can't wait to keep plugging away!