fcb_looper/firmware/guide.md

# STM32F042C4 Rust Development Guide

Setting up Rust for STM32F042C4 microcontroller development has never been more streamlined, with modern tooling like **probe-rs** and mature HAL crates providing production-ready embedded development capabilities. This guide covers the complete workflow from environment setup through debugging with cheap ST-Link programmers, focusing on 2024-2025 best practices.

The STM32F042C4 is a Cortex-M0-based microcontroller with 16KB Flash and 6KB RAM, requiring careful memory management but offering excellent USB and CAN capabilities. With probe-rs becoming the standard debugging tool and stm32f0xx-hal providing robust hardware abstraction, Rust embedded development now rivals traditional C/C++ toolchains while offering memory safety guarantees.

## Rust development environment setup

### Core toolchain installation

The foundation requires Rust with ARM compilation targets and modern embedded tooling:

```bash
# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Add ARM Cortex-M0 target for STM32F042C4
rustup target add thumbv6m-none-eabi

# Install essential binary utilities
rustup component add llvm-tools-preview
cargo install cargo-binutils

# Install modern debugging and flashing tools
cargo install probe-rs --features cli
cargo install cargo-generate  # For project templates
```

**probe-rs has emerged as the recommended tool** replacing OpenOCD for most STM32 Rust development. It provides native Rust integration, superior VS Code support, and built-in RTT logging without the complexity of GDB configuration.

### Platform-specific dependencies

**Linux systems** need additional development libraries:
```bash
# Ubuntu/Debian
sudo apt install libudev-dev pkg-config

# Fedora
sudo dnf install libudev-devel pkgconf-pkg-config

# Install udev rules for non-root probe access
sudo curl -L https://probe.rs/files/99-probe-rs.rules -o /etc/udev/rules.d/99-probe-rs.rules
sudo udevadm control --reload
```

**Windows systems** require Visual Studio Build Tools and will need WinUSB drivers for ST-Link clones using the Zadig tool. **macOS** typically works out of the box with Homebrew-installed dependencies.

## STM32F042C4 specifications and HAL integration

### Device characteristics

The STM32F042C4T6 features an **ARM Cortex-M0 core running up to 48 MHz** with constrained but sufficient resources for many embedded applications:

- **Flash Memory**: 16KB starting at 0x08000000
- **SRAM**: 6KB starting at 0x20000000  
- **Key Peripherals**: USB 2.0 Full-speed, CAN bus, 2x USART, 2x SPI, I2C, 12-bit ADC
- **Architecture Target**: `thumbv6m-none-eabi`

### Using stm32f0xx-hal crate

The **stm32f0xx-hal crate** provides comprehensive hardware abstraction for the STM32F0 family, including specific support for the F042 variant:

```toml
[dependencies]
cortex-m = "0.7"
cortex-m-rt = "0.7"
stm32f0xx-hal = { version = "0.18", features = ["stm32f042", "rt"] }
embedded-hal = "0.2"
panic-halt = "0.2"

# Optional: Enable USB or CAN support
stm32-usbd = { version = "0.6", optional = true }
bxcan = { version = "0.8", optional = true }
```

The **"stm32f042" feature flag** ensures chip-specific peripheral configurations are available. The HAL implements standard embedded-hal traits for portability across different HAL implementations.

## Project structure and configuration

### Recommended project layout

Modern STM32 Rust projects follow this structure:

```
stm32f042c4-project/
├── Cargo.toml
├── build.rs
├── memory.x
├── .cargo/
│   └── config.toml
├── src/
│   └── main.rs
├── examples/
│   └── blinky.rs
└── openocd.cfg (if using OpenOCD)
```

### Complete Cargo.toml configuration

```toml
[package]
edition = "2021"
name = "stm32f042c4-blinky"
version = "0.1.0"

[dependencies]
cortex-m = { version = "0.7", features = ["inline-asm"] }
cortex-m-rt = "0.7"
stm32f0xx-hal = { version = "0.18", features = ["stm32f042", "rt"] }
embedded-hal = "0.2"
panic-halt = "0.2"

# For debugging and logging
defmt = "0.3"
defmt-rtt = "0.4"

[profile.release]
debug = true        # Keep debug info for better debugging
opt-level = "s"     # Optimize for size (critical with 16KB Flash)
lto = true          # Link-time optimization
codegen-units = 1   # Better optimization
panic = 'abort'     # Reduce binary size
strip = false       # Keep symbols for debugging
```

### Cargo configuration (.cargo/config.toml)

```toml
[build]
target = "thumbv6m-none-eabi"

[target.thumbv6m-none-eabi]
runner = "probe-rs run --chip STM32F042C4T6"
rustflags = [
    "-C", "link-arg=-Tlink.x",
    "-C", "link-arg=--nmagic",
]

[env]
DEFMT_LOG = "info"  # Set logging level
```

### Build script (build.rs)

```rust
use std::env;
use std::fs::File;
use std::io::Write;
use std::path::PathBuf;

fn main() {
    // Put memory.x in our output directory and ensure it's on linker search path
    let out = &PathBuf::from(env::var_os("OUT_DIR").unwrap());
    File::create(out.join("memory.x"))
        .unwrap()
        .write_all(include_bytes!("memory.x"))
        .unwrap();
    println!("cargo:rustc-link-search={}", out.display());
    println!("cargo:rerun-if-changed=memory.x");
    println!("cargo:rustc-link-arg=--nmagic");
}
```

## Memory.x configuration for STM32F042C4

The memory.x file defines the exact memory layout critical for proper linking:

```linker-script
MEMORY
{
  /* STM32F042C4T6 specific memory layout */
  FLASH : ORIGIN = 0x08000000, LENGTH = 16K
  RAM : ORIGIN = 0x20000000, LENGTH = 6K
}

/* Stack grows downward from end of RAM */
_stack_start = ORIGIN(RAM) + LENGTH(RAM);

/* Custom sections for USB descriptors if needed */
SECTIONS
{
  .usb_descriptors :
  {
    KEEP(*(.usb_descriptors.*));
  } > FLASH
}
```

**Critical memory constraints:** With only 16KB Flash and 6KB RAM, every byte matters. Always use release builds with size optimization (`opt-level = "s"`) and avoid dynamic allocation.

## Basic blinking LED example

Here's a complete blinking LED implementation optimized for STM32F042C4:

```rust
#![no_std]
#![no_main]

use panic_halt as _;
use cortex_m_rt::entry;
use stm32f0xx_hal::{
    prelude::*,
    stm32,
    delay::Delay,
    gpio::*,
};

#[entry]
fn main() -> ! {
    // Get device peripherals
    let mut dp = stm32::Peripherals::take().unwrap();
    let cp = cortex_m::Peripherals::take().unwrap();
    
    // Configure the clock to 48 MHz
    let mut rcc = dp.RCC.configure()
        .hsi48()
        .enable_crs(dp.CRS)
        .sysclk(48.mhz())
        .pclk(24.mhz())
        .freeze(&mut dp.FLASH);
    
    // Set up delay provider
    let mut delay = Delay::new(cp.SYST, &rcc);
    
    // Configure GPIO
    let gpioa = dp.GPIOA.split(&mut rcc);
    
    // Configure PA5 as push-pull output (common LED pin)
    let mut led = gpioa.pa5.into_push_pull_output(&mut gpioa.moder, &mut gpioa.otyper);
    
    // Blink loop
    loop {
        led.set_high().ok();
        delay.delay_ms(500u16);
        
        led.set_low().ok();
        delay.delay_ms(500u16);
    }
}
```

### Advanced LED example with RTT logging

For debugging, add RTT logging capability:

```rust
#![no_std]
#![no_main]

use defmt::info;
use defmt_rtt as _;
use panic_halt as _;
use cortex_m_rt::entry;
use stm32f0xx_hal::{prelude::*, stm32, delay::Delay};

#[entry]
fn main() -> ! {
    info!("Starting STM32F042C4 blinky with RTT logging");
    
    let mut dp = stm32::Peripherals::take().unwrap();
    let cp = cortex_m::Peripherals::take().unwrap();
    
    let mut rcc = dp.RCC.configure()
        .hsi48()
        .enable_crs(dp.CRS)
        .sysclk(48.mhz())
        .freeze(&mut dp.FLASH);
    
    let mut delay = Delay::new(cp.SYST, &rcc);
    let gpioa = dp.GPIOA.split(&mut rcc);
    let mut led = gpioa.pa5.into_push_pull_output(&mut gpioa.moder, &mut gpioa.otyper);
    
    let mut counter = 0u32;
    loop {
        led.toggle().ok();
        info!("LED toggle #{}", counter);
        counter += 1;
        delay.delay_ms(1000u16);
    }
}
```

## ST-Link clone setup and usage

### Understanding ST-Link clones

**ST-Link clones** are widely available Chinese copies of ST's official programming adapters, typically costing $2-5 versus $25+ for genuine hardware. However, they require careful setup and have reliability considerations.

**Common clone issues include:**
- Inconsistent pinouts that don't match labeling
- Poor build quality causing intermittent connections
- Power delivery problems affecting target stability
- Firmware limitations blocking certain features

### Essential wiring verification

**Always verify pinout with a multimeter** before connecting. Standard connections should be:

```
ST-Link Clone    STM32F042C4
GND          →   GND
SWDIO        →   SWDIO (PA13)
SWCLK        →   SWCLK (PA14) 
VAPP/VTref   →   3.3V (CRITICAL - sets programming voltage)
VDD          →   3.3V (if powering target from ST-Link)
```

**The VAPP connection is critical** - ST-Link determines programming voltage from this pin even when the target has external power.

### Driver installation

**Linux**: probe-rs works with standard udev rules:
```bash
sudo curl -L https://probe.rs/files/99-probe-rs.rules -o /etc/udev/rules.d/99-probe-rs.rules
sudo udevadm control --reload
```

**Windows**: Use Zadig to install WinUSB drivers for the ST-Link device. Download Zadig from https://zadig.akeo.ie/, select the ST-Link device, and install WinUSB driver.

### Programming workflow with probe-rs

**Basic commands:**
```bash
# List connected probes
probe-rs list

# Get target information
probe-rs info --chip STM32F042C4T6

# Flash and run with RTT output
probe-rs run --chip STM32F042C4T6 target/thumbv6m-none-eabi/debug/blinky

# Flash only without running
probe-rs download target/thumbv6m-none-eabi/release/blinky.elf --chip STM32F042C4T6
```

**Cargo integration** enables `cargo run` to automatically flash and run:
```bash
# Build and flash in one command
cargo run --release

# Build only
cargo build --release
```

## VS Code debugging and development workflow

### Essential VS Code extensions

1. **rust-analyzer** - Core Rust language support
2. **probe-rs** - Native debugging integration with DAP
3. **Cortex-Debug** - Alternative debugging option

### VS Code launch configuration

Create `.vscode/launch.json`:

```json
{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "probe-rs-debug",
            "request": "launch",
            "name": "Debug STM32F042C4",
            "chip": "STM32F042C4T6",
            "flashingConfig": {
                "flashingEnabled": true,
                "resetAfterFlashing": true,
                "haltAfterReset": true
            },
            "coreConfigs": [
                {
                    "coreIndex": 0,
                    "programBinary": "target/thumbv6m-none-eabi/debug/stm32f042c4-blinky",
                    "rttEnabled": true
                }
            ]
        }
    ]
}
```

This configuration enables **full debugging with breakpoints, variable inspection, and RTT logging** directly in VS Code.

## Troubleshooting common issues

### Memory and linking problems

**"RAM overflowed" error** indicates stack or static variable overflow in the 6KB RAM constraint:
- Reduce stack-allocated arrays
- Use `static` variables instead of stack allocation
- Monitor memory usage with `cargo size`

**"Load failed" during flashing** typically indicates incorrect memory.x values:
- Verify Flash size (16KB for STM32F042C4, not 32KB)
- Check SRAM size (6KB total)
- Ensure addresses match datasheet exactly

### ST-Link connection issues

**"No ST-Link detected" errors:**
1. Check USB cable quality and try different ports
2. Verify VAPP pin connection to target 3.3V
3. Ensure target has stable power supply
4. Try reducing programming speed: `--speed 1000`

**Intermittent connection losses:**
- ST-Link clones often have poor power regulation
- Use external 3.3V supply for target instead of ST-Link power
- Add decoupling capacitors near the microcontroller

### BOOT0 pin configuration

**Program flashes but doesn't run** often indicates BOOT0 pin issues:
- BOOT0 must be LOW (connected to GND) for normal flash execution
- BOOT0 HIGH boots into system bootloader instead of user program
- Some development boards have BOOT0 jumpers requiring proper positioning

### Debugging workflow optimization

**RTT logging setup** for efficient debugging:
```rust
use defmt_rtt as _;
use defmt::{info, debug, error};

// Use throughout your code
info!("System initialized");
debug!("Variable value: {}", variable);
error!("Critical error occurred");
```

**Avoid WFI instruction** when using RTT, as it can interfere with real-time transfer communication.

## Advanced considerations and best practices

### Memory optimization strategies

With only 16KB Flash, **aggressive optimization is essential:**

```toml
[profile.release]
opt-level = "s"       # Size optimization
lto = true           # Link-time optimization  
codegen-units = 1    # Better optimization
panic = 'abort'      # Smaller panic handler
```

**Use `heapless` collections** instead of `std` alternatives:
```rust
use heapless::Vec;
use heapless::String;

let mut buffer: Vec<u8, 64> = Vec::new();  // Stack-allocated vector
let mut text: String<32> = String::new();  // Stack-allocated string
```

### Power management integration

STM32F042C4 supports multiple low-power modes. **Basic sleep implementation:**

```rust
use cortex_m::asm;
use stm32f0xx_hal::power::PowerMode;

// Enter sleep mode
cortex_m::interrupt::free(|_| {
    asm::wfi();  // Wait for interrupt
});
```

### USB device development

The STM32F042C4's **crystal-less USB capability** makes it ideal for USB projects:

```rust
use stm32_usbd::UsbBus;
use usb_device::prelude::*;

// USB setup requires specific clock configuration
let mut rcc = dp.RCC.configure()
    .hsi48()
    .enable_crs(dp.CRS)  // Clock recovery system for crystal-less USB
    .sysclk(48.mhz())    // Required for USB
    .freeze(&mut dp.FLASH);
```

This comprehensive guide establishes a complete STM32F042C4 Rust development environment using modern 2024-2025 tooling. The combination of probe-rs for debugging, stm32f0xx-hal for hardware abstraction, and careful memory management provides a robust foundation for embedded development that rivals traditional C/C++ workflows while offering Rust's memory safety guarantees.