README.md

tinyboot

Part of the tinyboot project — start with the top-level README and the handbook.

Host-side CLI for flashing firmware to tinyboot devices over UART / RS-485.

Install

cargo install tinyboot

Or from source:

cargo install --path cli

Usage

tinyboot info

Query device info (capacity, erase size, versions, mode).

tinyboot info [--port /dev/ttyUSB0] [--baud 115200]

tinyboot flash

Flash firmware to device. Accepts ELF or raw binary files.

tinyboot flash firmware.elf [--port /dev/ttyUSB0] [--baud 115200] [--reset]

tinyboot erase

Erase the entire app region.

tinyboot erase [--port /dev/ttyUSB0] [--baud 115200]

tinyboot reset

Reset the device. Use --bootloader to reboot into the bootloader instead of the app.

tinyboot reset [--port /dev/ttyUSB0] [--baud 115200] [--bootloader]

tinyboot bin

Convert an ELF to a flat binary (same extraction logic as flash).

tinyboot bin firmware.elf -o firmware.bin

Auto-detection

If --port is omitted, the CLI probes USB serial ports (usbmodem, ttyACM, ttyUSB) by sending an Info command with a 100ms timeout. Non-USB serial ports are skipped. Both the bootloader and apps running poll() respond to Info, so auto-detection works in either mode.

Single-wire bus echo

On a single-wire bus where the host's TX and RX are tied to the data line (DXL chains, most RS-485 hookups), the host hears its own request frame before the device replies. The CLI skips any frame whose status is Request — devices never reply with that status — so single-wire setups work without extra flags.

ELF handling

When given an ELF file, the CLI extracts ALLOC sections using physical addresses (LMA) from PT_LOAD segments. Sections named .uninit* are skipped. LMAs below 0x0800_0000 are adjusted by adding the CH32 flash base offset.

Raw binary files (no ELF magic) are used as-is.

Logging

Use -v (debug) or -vv (trace) for protocol-level diagnostics:

tinyboot -v flash firmware.elf
tinyboot -vv flash firmware.elf

Or set RUST_LOG directly:

RUST_LOG=debug tinyboot flash firmware.elf