Physical boards

A board profile identifies one physical device. Its name is your local label; its model, backend and transport determine the supported operations. A profile or successful image build is not proof of a UART boot.

Implemented models and transports

Model	Backend	Supported transport	Required core inputs
rpi3 (Pi 3B+ DTB contract)	raspberry-pi	native-tftp	ARM KOBJ triplet and model DTB
rpi4	raspberry-pi	native-tftp, uboot-usb-ecm	AArch64 KOBJ triplet and model DTB
rpi5	raspberry-pi	native-tftp	AArch64 KOBJ triplet and model DTB
milk-v-titan	opensbi-uefi	uefi-esp	RISC-V legacy core objects

The validator rejects USB-ECM on Pi 3/5 and rejects a Pi transport for the OpenSBI/UEFI backend. Debug transport and power-control fields are metadata; the CLI does not automate JTAG, SWD or power equipment.

Source: board schema and validation.

The portable board registry contains the four stable model IDs used by the CLI and template generator. Those IDs resolve from the registry embedded in the tools build; the CLI does not discover an external registry. A local profile name is an alias and stays separate from the model ID. No ESP32-P4 model or support is advertised. The --model help and generated Bash, Zsh and Fish completions use the same catalog as the parser.

Create and diagnose a profile

For a Pi 4 USB-ECM profile, preview the generated template:

aros board init --profile rpi4-usb --model rpi4 --transport uboot-usb-ecm

Then create a new config file explicitly:

aros board init --profile rpi4-usb --model rpi4 --transport uboot-usb-ecm --apply
aros board scan

Model and transport are explicit

--profile is only your local label. --model is required and selects the hardware contract; it is never inferred from the label. --transport is optional only where the model has one conservative default: Pi 3, Pi 4 and Pi 5 default to native-tftp; Milk-V Titan defaults to uefi-esp. Pi 4 USB-ECM must be selected explicitly, as shown above.

The generated build defaults come from the embedded reviewed registry. The example file at support/rpi-debug/boards.example.toml is a legacy local-profile example; it is not discovered as a model registry. Network addresses and MAC values in generated or example profiles are placeholders. Adapt them to the local network and the actual device identity; do not infer network or device values from a model ID. Unsupported model/transport pairs fail before a file is written. For example, Pi 3 and Pi 5 cannot select USB-ECM, and Titan cannot select a Pi TFTP path.

Edit the printed file (normally ~/.config/aros/boards.toml) with the real paths, interfaces, serial device and device identity. Use a matching target preset declared by your selected AROS checkout. The built-in four toolchain profiles are not the example registry’s board-specific debug presets.

For Pi 4 USB-ECM, copy the stable USB descriptor values from board scan; do not persist a guessed dynamic interface name. Then, inside the AROS tree:

aros board doctor --profile rpi4-usb

Build, deploy and serve

With the profile’s exact DTB and legacy core objects present:

aros board build --profile rpi4-usb
aros board deploy --profile rpi4-usb
aros board deploy --profile rpi4-usb --apply
aros board serve --profile rpi4-usb --dry-run
aros board serve --profile rpi4-usb

Deploy previews by default; --apply stages the bundle to the configured TFTP destination. The configured tftp_prefix must resolve through real directories below tftp_root; symbolic links in that path are rejected. Serve binds restricted DHCP and read-only TFTP to the validated interface and board identity. The host address must already be configured. These network commands are not the Milk-V UEFI-ESP boot path.

Open a serial console separately:

aros board console --profile rpi4-usb --dry-run
aros board console --profile rpi4-usb --program picocom

Supported terminal programs are picocom, screen and minicom. Auto mode searches in that order. Save and interpret the resulting UART evidence using your board’s bring-up procedure.

SD-card safety sequence

Image creation needs an external boot-bundle.toml plus its hash-declared firmware and artifact inputs. A build directory alone is not a boot bundle. Use the prepared bundle for the exact model/transport. The reviewed Pi 4 U-Boot USB-ECM and Milk-V Titan UEFI file layouts are defined in the media-profile registry; the local board name does not select a different layout. Native Pi SD and PC ISO profiles are not yet available through this SD command.

aros board sd image --profile rpi4-usb --boot-bundle /verified/bundle --output /new/artifact
aros board sd image --profile rpi4-usb --boot-bundle /verified/bundle --output /new/artifact --apply
aros board sd scan --artifact /new/artifact

If the intended removable disk is mounted, inspect and explicitly unmount it:

aros board sd unmount
aros board sd unmount --device SCAN_ID --apply

Run sd scan --artifact again after unmounting. Substitute its exact scan ID and confirmation token in the write sequence:

aros board sd write --profile rpi4-usb --artifact /new/artifact --device SCAN_ID --dry-run
aros board sd write --profile rpi4-usb --artifact /new/artifact --device SCAN_ID --confirm TOKEN

The final command writes the selected medium. Candidates must be whole, removable, writable and unmounted. Raw device paths are rejected; the token binds the measured image and device identity. The writer performs read-back verification. SD image creation uses the implemented MBR/FAT32 format; it is not a general disk-partitioning frontend.

Evidence still required

For a physical-boot claim, record the model, firmware, source commit, cross-toolchain identity, legacy core inputs, artifact digests and UART log. Do not infer boot support from an available profile or compiler.

The detailed Raspberry Pi lab guide covers the prepared firmware and external-debugger workflow.