# xiao-generate: A Rust Embedded Project Generator for the Seeed XIAO Family

## Introduction

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](https://www.seeedstudio.com/xiao-series-page.html?utm_source=blog&utm_medium=TER&utm_campaign=uFerris) 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.

## 🦀 What is `xiao-generate`?

xiao-generate is a project generator for the [Seeed XIAO](https://www.seeedstudio.com/xiao-series-page.html?utm_source=blog&utm_medium=TER&utm_campaign=uFerris) 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.

## 🛠️ Required Hardware

At a minimum, you need one of the supported XIAO devices (full supported list [here](https://github.com/theembeddedrustacean/xiao-generate#supported-devices)). ***Optionally***, you can also use the µFerris baseboard if you want to invoke µFerris BSP support.

%%[shop-xiao] 

%%[shop-uferris] 

## 💾 Installation

`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](https://www.rust-lang.org/tools/install).

**2\. Install** `xiao-generate`

```bash
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](https://github.com/esp-rs/esp-idf-template#prerequisites).

## 🚀 Usage

### Interactive

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:

```bash
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!

![](https://cdn.hashnode.com/uploads/covers/6227094756920671339a1788/129c3ffa-05b8-4a1e-84ff-d2d57accf253.png align="center")

### Headless

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:

```bash
xiao-generate --chip xiao-esp32c3
```

This generates a bare-metal `esp-hal` project for the XIAO ESP32-C3, ready to `cargo run`.

### Inspecting what's available

In headless mode, before generating, you can also ask `xiao-generate` what it supports:

```bash
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
```

### Key Options

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 |

### Examples

Here are some examples of configurations:

**Creating an Embassy async project on the ESP32-C6 with** `defmt` **logging:**

```bash
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:**

```bash
xiao-generate --chip xiao-esp32c3 --std --espidf-version v5.4.3
```

**An RP2040 project using the** `embassy-rp` **HAL stack and embassy framework:**

```bash
xiao-generate --chip xiao-rp2040 --stack embassy-rp --framework embassy
```

## 📦 After Generating

When generation finishes, `xiao-generate` prints a report and the next steps for your project. From there it's the usual loop:

```bash
cd my-project
cargo run --release
```

That's it! You are all set!

## Conclusion

`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.