Initial commit

README.md

@@ -0,0 +1,95 @@
+# 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).