# Rust on STM32 Blue Pill

This repository is a hands-on Rust and robotics workshop for the STM32F103C8T6 Blue Pill.
The workshop builds the software shape of a small soccer robot step by step:

## Hardware Baseline

- Board: STM32F103C8T6 Blue Pill
- Core: Cortex-M3
- Default target: `thumbv7m-none-eabi`
- Default `probe-rs` chip name: `STM32F103C8`
- Onboard LED: usually `PC13`, active-low on most Blue Pill boards

See [docs/blue-pill.md](docs/blue-pill.md) for wiring notes.

## Workshop Chapters

- `00_check` - toolchain and sanity check
- `01_rust_basics` - values, functions, mutation
- `02_ownership` - ownership and borrowing
- `03_types` - domain types, enums and `Result`
- `04_first_firmware` - first STM32 firmware loop
- `05_rgb_output` - RGB LED status output
- `06_button_events` - 5-way button as fake sensor rig
- `07_events` - event priority and safety-first interpretation
- `08_state_machine` - robot state machine and status LED
- `09_sensor_pipeline` - fake camera and ultrasonic pipeline
- `10_motor_commands` - motion intent to wheel speeds
- `11_kinematics` - geometry and inverse kinematics
- `12_embassy` - async Embassy loop and timers


## Start With Nix

```bash
nix develop
```

The shell provides Rust, `probe-rs`, `flip-link`, and aliases for the workshop flow.

Typical first commands:

```bash
fmt
check
verify
run-00
run-01
run-02
run-03
```

## Start With Rustup

If you do not want Nix, use the pinned toolchain directly:

```bash
rustup toolchain install 1.95.0
rustup target add thumbv7m-none-eabi
```

You also need `flip-link` and `probe-rs` on your `PATH` for embedded builds and flashing.

Then run the host chapter bins with Cargo:

```bash
cargo run --bin 00_check
cargo run --bin 01_rust_basics
cargo run --bin 02_ownership
cargo run --bin 03_types
```

For the Blue Pill chapters:

```bash
cargo build --target thumbv7m-none-eabi --bin 04_first_firmware
probe-rs run --chip STM32F103C8 target/thumbv7m-none-eabi/debug/04_first_firmware
cargo build --target thumbv7m-none-eabi --bin 12_embassy
probe-rs run --chip STM32F103C8 target/thumbv7m-none-eabi/debug/12_embassy
```

## Probe Wiring

Typical SWD wiring:

- `SWDIO` -> `SWDIO`
- `SWCLK` -> `SWCLK`
- `GND` -> `GND`
- `3V3` -> `3V3` reference

Keep `BOOT0` low for normal flash-and-run.

## Troubleshooting

See [docs/troubleshooting.md](docs/troubleshooting.md).