Search for a command to run...
Go from a XIAO board to a ready-to-build bare-metal Rust project with a single command.
No comments yet. Be the first to comment.
A community giveaway program by The Embedded Rustacean × Seeed Studio to grow the embedded Rust ecosystem
Introduction Another year comes to an end; as always, it is an opportunity to reflect on the achievements of the past year and look forward to the next. It's been over 3.5 years since I embarked on my embedded Rust journey, and it only gets more exci...
Introduction Another year comes to an end, as such, this is an opportunity to reflect on the achievements of 2024 and look forward to 2025. It's been over 2.5 years since I embarked on my embedded Rust journey, and it remains as exciting as ever. If ...
Introduction 🚀 On Friday, May 17th, 2024, the release of Simplified Embedded Rust was announced marking a new kind of book in the embedded Rust learning space. I'm happy to say that this book, design
Starting a bare-metal Rust project for a microcontroller is rarely a one-liner. You need the right target installed, a flashing tool, a runner wired into .cargo/config.toml, the correct HAL and its version, a #![no_std] skeleton that actually links, and a dozen small settings that differ per chip. Get one wrong, and you're staring at a linker error instead of a blinking LED.
xiao-generate is a Cargo tool that removes that friction for the Seeed Studio XIAO line. Point it at a XIAO device, and it hands you a ready-to-build Rust project: correct target, flashing tool, HAL, and a working skeleton, already assembled. You go straight to writing application code.
It's the tool to reach for whenever starting a new project on a XIAO board.
xiao-generate?xiao-generate is a project generator for the Seeed XIAO family. It supports eleven XIAO variants across three architectures (RISC-V, Xtensa, and Arm Cortex-M), and it understands the common ways you'd want to build for them:
no_std bare-metal & std (for the ESP chips).
Device HALs and async (embassy) support.
Optional logging (defmt, log), editor configs (VS Code, Helix, Neovim, Zed), and crates baked in from the start.
It ships two ways to drive it: an interactive TUI for exploring options, and a fully headless mode for reproducible, scriptable generation.
At a minimum, you need one of the supported XIAO devices (full supported list here). Optionally, you can also use the µFerris baseboard if you want to invoke µFerris BSP support.
xiao-generate is a standard Cargo binary. Two steps are required for installation:
1. Install Rust & Cargo
If you don't already have it, install Rust and its tooling from rust-lang.org/tools/install.
2. Install xiao-generate
cargo install xiao-generate --locked
That's the whole setup. You do not need to pre-install chip targets or flashing tools by hand, xiao-generate auto-detects what a project needs and installs the target and flash tool for you (via rustup/cargo), prompting on first use.
🚨 IMPORTANT: The one exception is ESP-IDF (
std) projects, which additionally need the C ESP-IDF SDK installed for your OS. You can install the pre-requisites as indicated in the esp-idf-template repo.
The interactive mode is the friendlier option, as it comes with a terminal user interface (TUI) to select the project configuration. To use the interactive interface, simply navigate to the directory you'd like your project to be created in. Afterward, invoke xiao-generate passing only the --name flag along with the name you desire for your project as follows:
xiao-generate --name my-project
This would launch the TUI shown below, which walks you through device, HAL/stack, framework, logging, editor, and templates. Simply choose the device and the options you like, then press Enter. Afterward, a project directory will be generated for you.
That's it! You're off to code & flash!
In addition to the interactive mode, there is an alternative headless option that allows you to pass configuration through the CLI. To invoke headless mode, at a minimum you need to pass the --chip flag with the desired controller. This would create a project template with registry defaults for the desired controller. The following is an example of creating a project for the XIAO ESP32-C3:
xiao-generate --chip xiao-esp32c3
This generates a bare-metal esp-hal project for the XIAO ESP32-C3, ready to cargo run.
In headless mode, before generating, you can also ask xiao-generate what it supports:
xiao-generate --list-chips # all supported devices
xiao-generate --list-stacks --chip xiao-rp2040 # stacks for a given chip
xiao-generate --list-templates --chip xiao-esp32s3 # list all templates for a given chip
xiao-generate --check --chip xiao-nrf52840 # validate a config without generating
There are more options available. Essentially, the headless interface allows you to configure the project with the same options available in the TUI interface. The following table captures all the option flags available:
| Flag | What it does |
|---|---|
--chip <id> |
Target device |
--stack <id> |
HAL/stack to use (e.g. esp-hal, embassy-rp, rp2040-hal) |
--std |
Shorthand for the ESP-IDF std stack (ESP chips) |
--framework <id> |
none (bare-metal) or embassy (async) |
--logging <id> |
none, defmt, or log (log is esp-hal only) |
--flashing <id> |
Flash tool (per chip; defaults to the board's no-probe cargo route) |
--editor <id> |
none, vscode, helix, neovim, zed |
--template <id> |
base skeleton or a component template |
--add-crate <spec> |
Add a dependency (repeatable) |
--name <name> |
Crate name. Also launches the TUI when passed on its own. |
--out <dir> / -o |
Output directory (default ./<name>) |
--yes / -y |
Skip prompts |
--no-install |
Don't auto-install target/flash tool |
Here are some examples of configurations:
Creating an Embassy async project on the ESP32-C6 with defmt logging:
xiao-generate --chip xiao-esp32c6 --framework embassy --logging defmt --name my-embassy-project
An ESP-IDF std project on the C3, pinned to a specific IDF version:
xiao-generate --chip xiao-esp32c3 --std --espidf-version v5.4.3
An RP2040 project using the embassy-rp HAL stack and embassy framework:
xiao-generate --chip xiao-rp2040 --stack embassy-rp --framework embassy
When generation finishes, xiao-generate prints a report and the next steps for your project. From there it's the usual loop:
cd my-project
cargo run --release
That's it! You are all set!
xiao-generate is a cargo tool for XIAO devices that collapses the error-prone setup of an embedded Rust project down to a single command. It supports the whole XIAO line, with several types of HALs, and both no_std and ESP-IDF std, so it's a single entry point regardless of which controller you reach for. It's the toolchain foundation for the µFerris series, and a handy default for any XIAO project. Give it a try on your next board.