# Rust on Robots ## Hands-on Embedded Rust on STM32 by WieErWill

# Today is about robot firmware architecture We use Rust to understand how robot software is structured: <div class="flow-chain"> <span>hardware signal</span> <span>software type</span> <span>robot event</span> <span>robot state</span> <span>decision</span> <span>actuator command</span> </div>

# Corpuls <img class="slide-image r-stretch" src="docs/Stage-madeingermany3.jpg" alt="Corpuls Devices" />

# We will not build a full robot in two hours We do not have: - full chassis - motors - motor drivers - camera module - ultrasonic hardware - playing field

# We will build a robot framework We do have: - STM32 Blue Pill - ST-Link programmer - RGB LED - 5-way button → The STM32 board is our small, reduced robot

# The workshop target By the end, we want this model: <div class="flow-chain"> <span>button / sensor input</span> <span>RobotEvent</span> <span>RobotMode</span> <span>MotionCommand</span> <span>LED status or wheel\-speed model</span> </div> Different hardware. Same architecture. Easy Adaptable.

# Room calibration 1. Who has written Rust before? 2. Who has programmed a microcontroller before? 3. Who has built, programmed or broken a robot before?

# Get the Repo Code along and try out yourself `git.wieerwill.dev/wieerwill/rust-stm32` 1. Clone it `git clone ...` 2. Install RustUp or Nix shell 3. Try it out (more in Chapter 0 later)

# My RoboCup Junior Soccer journey <img class="slide-image r-stretch" src="docs/JuniorCup.jpg" alt="Junior RoboCup" />

# A soccer robot starts simple 1. turn on 2. show status 3. wait for start 4. find the ball 5. drive toward the ball 6. avoid problems 7. recover and continue

# A (soccer) robot is a loop with consequences <div class="flow-chain"> <span>observe</span> <span>interpret</span> <span>decide</span> <span>move</span> <span>observe again</span> </div> The hard part is keeping this loop understandable when reality becomes messy

# Robot software touches the real world <div class="split-cards"> <div class="slide-card fragment"> <h3>Messy inputs</h3> <ul> <li>camera frame</li> <li>ball position</li> <li>line / field detection</li> <li>ultrasonic distance</li> <li>start button</li> <li>battery state</li> <li>motor feedback</li> </ul> </div> <div class="slide-card fragment"> <h3>Physical outputs</h3> <ul> <li>wheel speeds</li> <li>LED status</li> <li>logs</li> <li>stop behaviour</li> <li>recovery behaviour</li> </ul> </div> </div>

# The board is our reduced robot <div class="flow-chain"> <div><span>RGB LED -> actuator / status output</span></div> <div><span>5-way button -> input device / fake sensor rig</span></div> <div><span>STM32 loop -> robot control loop</span></div> <div><span>Rust types -> robot domain model</span></div> </div> Small hardware. Real architecture.

# Chapter map <div style="font-size:smaller;"> 1. <code>00_check</code> toolchain check 2. <code>01_rust_basics</code>values, functions, mutation 3. <code>02_ownership</code>ownership and borrowing 4. <code>03_types</code>domain types, enums 5. <code>04_first_firmware</code>minimal STM32 firmware 6. <code>05_rgb_output</code>LED as actuator 7. <code>06_button_events</code>button as sensor 8. <code>07_events</code>raw input to robot event 9. <code>08_state_machine</code>robot behaviour 10. <code>09_sensor_pipeline</code>camera and ultrasonic model 11. <code>10_motor_commands</code>motion intent to wheel speeds 12. <code>11_kinematics</code>geometry and inverse kinematics 13. <code>12_embassy</code>async Embassy loop and timers </div>

# Chapter 0: Toolchain

# Chapter 0: Toolchain check Open: `src/bin/00_check.rs` Run: `run-00` Expected result: `prints the toolchain check`

# Why Rust for this? - Who owns this peripheral? - Who may mutate robot state? - What happens when a sensor fails? - Which commands are valid? - Which states should be impossible? - Where does hardware end and behaviour begin? Rust makes many of those boundaries easily visible

# Rust is strict in useful places - memory safety without a garbage collector - explicit ownership - controlled mutation - strong enums and pattern matching - `Option` and `Result` - small `no_std` programs for microcontrollers

# But Rust does not fix everything - wrong wiring - noisy sensors - weak batteries - bad control logic - missing calibration

# Chapter 01: Values

# Chapter 01: Values are explicit ```rust let speed = 42; let mut target_speed = 0; target_speed = speed; ``` Default: values are immutable. Mutation must be requested with `mut`. For robot code, that is a good default

# Robot translation: Mutation should have a home Bad: `everything can change everything` Better: <div class="flow-chain"> <span>sensor reading</span> <span>event</span> <span>state transition</span> <span>command</span> </div> The robot state changes in one obvious place.

# Chapter 01 exercise Change behaviour without changing structure Open: `src/bin/01_rust_basics.rs` Tasks: 1. Change a constant. 2. Change a function return value. 3. Add a new status value. 4. Run the program. Checkpoint: `run-01`

# Chapter 02: Ownership

# Chapter 02: Ownership means responsibility ```rust let command = String::from("forward"); let next_command = command; // command is no longer usable here ``` One value has one owner. When ownership moves, responsibility moves.

# Robot translation: Peripherals are resources A GPIO pin is not just an integer. It represents access to real hardware. <div class="flow-chain"> <span>LED pin owner</span> <span>configure output</span> <span>set high / low</span> </div> Ownership makes accidental sharing harder.

# Borrowing means temporary access ```rust fn print_command(command: &str) { println!("command = {command}"); } let command = String::from("forward"); print_command(&command); // command is still usable here ``` A borrow can inspect without taking ownership

# Mutable borrowing: One writer at a time ```rust fn stop(command: &mut MotionCommand) { command.forward = 0.0; command.strafe = 0.0; command.rotate = 0.0; } ``` Rust does not like hidden shared mutation. For robot code, that is useful.

# Robot translation: Who may change the robot state? A robot state should not be mutated from everywhere. <div class="flow-chain"> <span>sensor module -> creates observations</span> <span>event module -> creates RobotEvent</span> <span>state machine -> changes RobotMode</span> <span>command module -> creates MotionCommand</span> <span>hardware module -> applies output</span> </div> Each layer has a job.

# Chapter 02 exercise: Fix the ownership error Open: `src/bin/02_ownership.rs` Tasks: 1. Run it. 2. Read the compiler error. 3. Fix it with a borrow. 4. Add a mutable command update. Checkpoint: `run-02`

# Chapter 03: Types

# Chapter 03: Numbers are not enough ```rust let value = 42; ``` What is it? - centimetres? - percent? - PWM duty cycle? - motor speed? - battery voltage? - camera pixel coordinate? Robot code needs meaning, not just numbers

# Types are safety rails A number alone does not tell us what it means. Types carry meaning. ```rust struct DistanceCm(u16); struct MotorPower(f32); struct BallXPixel(u16); struct BatteryMillivolts(u16); ```

# Enums model robot reality better than booleans ```rust enum BallObservation { NotSeen, Left, Center, Right, TooClose, } ``` This is clearer than: ```rust ball_seen: bool ball_left: bool ball_right: bool ``` Because impossible combinations disappear.

# Failure is part of the API A sensor may fail. The type should admit that. ```rust enum SensorError { Timeout, OutOfRange, NotCalibrated, } fn read_distance() -> Result<DistanceCm, SensorError> { todo!() } ```

# Robot translation: Sensor data is evidence A sensor reading is not behaviour. <div class="flow-chain"> <span>raw echo time</span> <span>distance</span> <span>classification</span> <span>RobotEvent</span> <span>state transition</span> </div> The robot should not directly react to raw numbers!

# Chapter 03 exercise: Replace loose values with domain types Open: `src/bin/03_types.rs` Tasks: 1. Replace a raw distance number with `DistanceCm`. 2. Replace booleans with `BallObservation`. 3. Return `Result` from a fake sensor function. 4. Match on the result. Checkpoint: `run-03`

# Chapter 04: Embedded Rust

# Chapter 04: First embedded Rust program On the STM32 we usually do not have: - an operating system - heap by default - files - a normal terminal - `std` We write `no_std` firmware!

# Bare metal means we own the loop <div class="flow-chain"> <span>configure hardware</span> <span>enter loop</span> <span>read input</span> <span>update state</span> <span>write output</span> <span>repeat</span> </div> That loop is the beginning of a robot controller.

# Firmware is not an app with a main window On a microcontroller: - startup code prepares the chip - firmware configures peripherals - the loop runs forever - timing is explicit - debugging is limited - output may be one LED

# First Embedded Firmware Open: `src/bin/04_first_firmware.rs` Build: `build-04` Flash: `run-04` Expected result: The board boots and reaches the firmware loop.

# Hardware silence is a valid embedded state If nothing happens, debug in layers: 1. Is the board powered? 2. Is the ST-Link visible? 3. Is the chip target correct? 4. Did the firmware flash? 5. Is the pin correct? 6. Is the LED orientation correct? Do not randomly change five things at once!

# Embedded debugging is layered 1. host build works? 2. target build works? 3. probe visible? 4. flash succeeds? 5. firmware boots? 6. pin toggles? 7. external wiring works? Debug from the outside in.

# Chapter 05: Output

# Chapter 05: Output - LED as actuator An LED is a tiny actuator. It gives us visible robot state. <div class="flow-chain"> <div><span>Off</span> <span>idle</span></div> <div><span>Blue blink</span> <span>searching</span></div> <div><span>Green</span> <span>driving</span></div> <div><span>Red blink</span> <span>obstacle / error</span></div> </div> The LED becomes the robot dashboard.

# Robot translation: Status output matters A robot needs visible state because: - it may not have a screen - logs may be unavailable - behaviour may look ambiguous - debugging happens on the floor/in the field - humans need to know if it is safe A status LED is not (just) decoration

# Chapter 05 exercise: Status output Open: `src/bin/05_rgb_output.rs` Tasks: 1. Make the LED blink. 2. Change the colour. 3. Add a status pattern. 4. Use one pattern for `Idle`. 5. Use one pattern for `Searching`. Checkpoint: `run-05`

# Chapter 06: Input

# Chapter 06: Input - button as sensor The 5-way button becomes our fake sensor rig <div class="flow-chain"> <div><span>Center</span><span>start / stop</span></div> <div><span>Left</span><span>ball left</span></div> <div><span>Right</span><span>ball right</span></div> <div><span>Up</span><span>ball centered</span></div> <div><span>Down</span><span>obstacle detected</span></div> </div> This lets us simulate camera or ultrasonic input.

# Raw input is not robot meaning Button press: ```text raw electrical state ``` Robot event: ```text BallLeft ObstacleDetected StartStop ``` We separate hardware reading from robot meaning.

# Robot translation: Perception is a boundary The controller should not care whether `BallLeft` came from: - a camera - a test file - a simulator - a button - a future ML model It only needs the event.

# Chapter 06 exercise: Button to event Open: `src/bin/06_button_events.rs` Tasks: 1. Read the 5-way button. 2. Convert direction to `RobotEvent`. 3. Show the event with LED status or logging. 4. Add a default `NoEvent` case. Checkpoint: `run-06`

# Chapter 07: Events

# Chapter 07: Events ```rust enum RobotEvent { NoEvent, StartStop, BallLeft, BallRight, BallCentered, BallLost, ObstacleDetected, Timeout, } ``` Events are interpreted facts. They are not raw hardware.

# Event priority matters ```text New Events: BallCentered + ObstacleDetected ``` What should win? Probably not: `drive forward` Some events are safety-critical.

# Chapter 07 exercise: Add event priority Open: `src/bin/07_events.rs` Tasks: 1. Convert button direction to `RobotEvent`. 2. Add a function `prioritize_event`. 3. Ensure `ObstacleDetected` wins. 4. Keep `NoEvent` harmless. Checkpoint: `test-07`

# Chapter 08: State Machine

# Chapter 08: Robot state machine The robot needs memory. ```rust enum RobotMode { Idle, SearchBall, AlignToBall, DriveToBall, AvoidObstacle, Error, } ``` It must know what it is currently trying to do.

# State is not the same as event Event: `BallLeft` State: `AlignToBall` Command: `RotateLeft` Keep them separate.

# State produces command ```rust enum MotionCommand { Stop, Forward, RotateLeft, RotateRight, StrafeLeft, StrafeRight, Avoid, } ``` The robot should think in intent first.

# Decision function ```rust fn decide( mode: RobotMode, event: RobotEvent, ) -> (RobotMode, MotionCommand) { match (mode, event) { (_, RobotEvent::ObstacleDetected) → (RobotMode::AvoidObstacle, MotionCommand::Stop), (RobotMode::Idle, RobotEvent::StartStop) → (RobotMode::SearchBall, MotionCommand::RotateLeft), (RobotMode::SearchBall, RobotEvent::BallLeft) → (RobotMode::AlignToBall, MotionCommand::RotateLeft), (RobotMode::SearchBall, RobotEvent::BallRight) → (RobotMode::AlignToBall, MotionCommand::RotateRight), (RobotMode::SearchBall, RobotEvent::BallCentered) → (RobotMode::DriveToBall, MotionCommand::Forward), (mode, _) → (mode, MotionCommand::Stop), } } ``` One place. One transition table. Less mystery.

# Chapter 08 exercise: Make the robot behave Open: `src/bin/08_state_machine.rs` Tasks: 1. Add `BallLost -> SearchBall`. 2. Add `StartStop -> Idle`. 3. Ensure `ObstacleDetected` always wins. 4. Map `RobotMode` to LED status. 5. Add one new mode or command. Checkpoint: `run-08`

# We can test robot behaviour without a robot ```rust #[test] fn obstacle_wins_over_ball() { let (mode, command) = decide( RobotMode::DriveToBall, RobotEvent::ObstacleDetected, ); assert_eq!(mode, RobotMode::AvoidObstacle); assert_eq!(command, MotionCommand::Stop); } ``` Robot logic can be tested on the laptop.

# Chapter 09: more Sensors

# Chapter 09: Camera model Real camera pipeline: <div class="flow-chain"> <span>camera frame</span> <span>color / blob / ML detection</span> <span>BallObservation</span> <span>RobotEvent</span> </div>

# Camera model -> Workshop model ```rust enum BallObservation { NotSeen, Left, Center, Right, TooClose, } ``` The controller should not care *how* the ball was detected.

# Camera data is not clean A camera may give: - no ball - multiple candidates - wrong colour - motion blur - partial visibility - bad lighting - stale frame So convert pixels into a small domain model before logic processing.

# Chapter 09: Ultrasonic model ```rust struct RawEchoMicros(u32); struct DistanceCm(u16); enum ObstacleObservation { Clear, Warning, TooClose, } ``` Pipeline: <div class="flow-chain"> <span>raw echo</span> <span>distance</span> <span>classification</span> <span>event</span> </div>

# Sensor fusion starts small For a soccer robot with vision and Ultrasonic: <div class="flow-chain"> <div><span>BallCentered + Clear</span><span>DriveToBall</span></div> <div><span>BallCentered + TooClose</span><span>Stop or AvoidObstacle</span></div> <div><span>BallLost + Clear</span><span>SearchBall</span></div> <div><span>BallLeft + Warning</span><span>Align carefully</span></div> </div> Multiple inputs must become one decision.

# Chapter 09 exercise: Sensor pipeline Open: `src/bin/09_sensor_pipeline.rs` 1. Convert camera to `BallObservation`. 2. Convert distance to `ObstacleObservation`. 3. Observations to Event. 4. Feed event into `decide()`. 5. Add test for obstacle priority. Checkpoint: `test-09`

# Chapter 10: Motion

# Chapter 10: Motion commands The robot does not think in PWM first. It thinks in motion intent: ```rust struct MotionVector { forward: f32, strafe: f32, rotate: f32, } ``` Then a lower layer translates intent into wheel speeds.

# From symbolic command to vector ```rust fn command_to_vector(command: MotionCommand) -> MotionVector { match command { MotionCommand::Stop → MotionVector { forward: 0.0, strafe: 0.0, rotate: 0.0, }, MotionCommand::Forward → MotionVector { forward: 0.6, strafe: 0.0, rotate: 0.0, }, MotionCommand::RotateLeft → MotionVector { forward: 0.0, strafe: 0.0, rotate: -0.4, }, ... _ → MotionVector { forward: 0.0, strafe: 0.0, rotate: 0.0, }, } } ``` Intent becomes a numeric movement request.

# Four-wheel omni drive: Command to wheels ```rust struct WheelSpeeds { front_left: f32, front_right: f32, rear_left: f32, rear_right: f32, } fn mix(cmd: MotionVector) -> WheelSpeeds { WheelSpeeds { front_left: cmd.forward + cmd.strafe + cmd.rotate, front_right: cmd.forward - cmd.strafe - cmd.rotate, rear_left: cmd.forward - cmd.strafe + cmd.rotate, rear_right: cmd.forward + cmd.strafe - cmd.rotate, } } ``` The formula is simple. The real robot is not.

# Real motors add boring but important details A real motor layer needs: - speed normalization - motor orientation calibration - PWM generation - motor driver limits - battery compensation - emergency stop behaviour - testing on the floor Rust helps keep the layers honest.

# Chapter 10 ex: command to wheel speeds Open: `src/bin/10_motor_commands.rs` 1. Convert `MotionCommand` to `MotionVector`. 2. Convert `MotionVector` to `WheelSpeeds`. 3. Normalize speeds. 4. Add a test for `Stop`. 5. Add a test for `RotateLeft`. Checkpoint: `test-10`

# Chapter 11: Kinematics

# Chapter 11: Kinematics enters when geometry matters For a mobile base: <div class="flow-chain"> <span>robot motion intent</span> <span>wheel speeds</span> </div> For a robot arm: <div class="flow-chain"> <span>target position</span> <span>joint angles</span> <span>motor commands</span> </div> That second step is inverse kinematics.

# Forward kinematics asks: Where did we end up? <div class="flow-chain"> <span>joint angles</span> <span>robot geometry</span> <span>tool position</span> </div> Example: ```text base angle + shoulder angle + elbow angle → x / y / z position ``` Good for checking and simulation.

# Inverse kinematics asks: How do we get there? <div class="flow-chain"> <span>target position</span> <span>robot geometry</span> <span>joint angles</span> </div> Example: ```rust struct ArmTarget { x_mm: f32, y_mm: f32, z_mm: f32, } struct JointAngles { base_deg: f32, shoulder_deg: f32, elbow_deg: f32, } ```

# Invalid movement should fail before hardware moves ```rust enum KinematicsError { TargetOutOfReach, JointLimitExceeded, CollisionRisk, } fn inverse_kinematics( target: ArmTarget, ) -> Result<JointAngles, KinematicsError> { todo!() } ``` The safest motor command is the one you never send.

# Chapter 11 exercise: Reject invalid motion Open: `src/bin/11_kinematics.rs` Tasks: 1. Run the tests. 2. Change one reachable target. 3. Add one rejected target. 4. Keep unsafe motion out of the command layer. Checkpoint: `test-11`

# Chapter 12: Embassy

# Chapter 12: Why Embassy? So far, we wrote the loop ourselves: <div class="flow-chain"> <span>configure hardware</span> <span>loop forever</span> <span>check time</span> <span>read input</span> <span>update state</span> <span>write output</span> </div> But it becomes noisy when several things must happen at different rates.

# Chapter 12: Robots rarely do only one thing * blink status LED every 500 ms * read buttons or sensors often * print diagnostics occasionally * update behaviour state * send motor commands regularly * wait without blocking everything else A single hand-written loop can do this. It just gets ugly.

# Chapter 12: established embedded crates We do not need to build every firmware primitive ourselves. Embassy gives us reusable embedded building blocks: * async executor * timers & tickers * task spawning * embedded-focused scheduling model The setup stays explicit. The waiting and task structure get cleaner.

# Chapter 12: What Embassy is Embassy is an embedded Rust framework built around async Rust. It provides an async executor designed for embedded systems. Important embedded properties: * no heap required * tasks are statically allocated * async/await works on microcontrollers * timers can express waiting without busy-loop plumbing

# Chapter 12: From one loop to tasks Manual loop model: <div class="flow-chain"> <span>main loop</span> <span>do everything</span> <span>manually track time</span> <span>repeat</span> </div> Embassy model: <div class="flow-chain"> <span>init hardware</span> <span>spawn tasks</span> <span>await timers</span> <span>executor resumes work</span> </div> The firmware still owns the hardware. The structure is cleaner.

# Chapter 12: Timer-driven waiting Instead of manual delay plumbing: ```rust loop { do_work(); busy_wait(); } ``` Embassy lets us express waiting directly: ```rs loop { do_work(); Timer::after(Duration::from_millis(500)).await; } ``` The code says what it means: `do work, then wait`

# Chapter 12: Periodic work with Ticker For periodic work: ```rs let mut ticker = Ticker::every(Duration::from_millis(500)); loop { ticker.next().await; hprintln!("heartbeat"); } ``` useful for: * periodic sensor sampling * regular status updates * control-loop prototypes

# Chapter 12: Async task shape ```rs #[embassy_executor::task] async fn heartbeat_task() { let mut ticker = Ticker::every(Duration::from_millis(500)); loop { ticker.next().await; hprintln!("heartbeat"); } } ``` The task looks sequential. The executor handles waiting and resuming.

# Chapter 12: Main task stays explicit ```rs #[embassy_executor::main] async fn main(spawner: Spawner) { spawner.spawn(heartbeat_task()).unwrap(); loop { hprintln!("main task alive"); Timer::after(Duration::from_secs(2)).await; } } ``` The structure is still visible: <div class="flow-chain"> <span>start executor</span> <span>spawn heartbeat</span> <span>main task keeps running</span> </div>

# Chapter 12: Embassy example Open: `src/bin/12_embassy.rs` Tasks: 1. Change the heartbeat text. 2. Change the timer period. 3. Add a second async task. Run: `run-12`

# Chapter 12: What Embassy does not solve Embassy does not remove: * hardware setup * ownership rules * bad wiring * wrong pin mapping * sensor noise * control logic bugs * the need for testing on real hardware It helps structure waiting and concurrent tasks. It does not make the robot correct by itself.

# The full architecture we built toward ```text camera / ultrasonic / button (Sensors) | raw reading | domain observation | RobotEvent | RobotMode | MotionCommand | MotionVector | WheelSpeeds | motor driver (Output) ```

# Hardware and software work together in layers ```text Hardware layer GPIO, timers, PWM, ADC, buses Driver layer LED, button, motor driver, sensor Domain layer BallObservation, ObstacleObservation Behaviour layer RobotMode, state machine Control layer MotionCommand, wheel speeds ``` Do not mix this into one loop!

# What Rust helped with - explicit ownership of resources - visible mutation - clear domain types - enums for valid states - `Result` for sensor failure - testable robot logic - separation between hardware and behaviour - small embedded programs without `std` Rust did not remove the need for calibration, physics or debugging!

# What robotics taught us - Raw input is not meaning - Meaning is not behaviour - Behaviour is not motor output - Motor output is not guaranteed motion - Real systems need feedback - Safety should win over ambition The robot is a loop, not a script

# Where to continue 0. Get yourself a microcontroller 1. Add real ultrasonic hardware 2. Add motor driver output 3. Add a camera module or external vision process 4. Add logs and host-side tests 5. Move repeated tasks to Embassy async 6. Put the board onto a small chassis 7. Test on the floor Build one layer at a time

# Useful references - The Rust Book: ownership and borrowing - The Embedded Rust Book: `no_std` and bare-metal concepts - probe-rs: flashing and embedded debugging tooling - RoboCupJunior Soccer rules and description

# Questions? more at wieerwill.dev & corpuls.world <img class="slide-image r-stretch" src="docs/corpuls_heart.jpg" alt="Corpuls Heart" />

# Feedback? more at wieerwill.dev & corpuls.world <img class="slide-image r-stretch" src="docs/rust-on-robots-hands-on-embedded-rust-on-stm32_jeutter_1154375_feedback-code.png" alt="WAD Feedback Form" />