init basic examples and setup
This commit is contained in:
149
README.md
Normal file
149
README.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# Rust on STM32
|
||||
|
||||
## Hardware Baseline
|
||||
|
||||
- Default board: STM32F103C8T6 Blue Pill, Cortex-M3
|
||||
- Default target: `thumbv7m-none-eabi`
|
||||
- Default `probe-rs` chip name: `STM32F103C8`
|
||||
- Default probe: ST-Link v2
|
||||
- Also supported in docs: Rusty Probe and other `probe-rs` compatible probes
|
||||
- Onboard LED: usually `PC13`, active-low on most Blue Pill boards
|
||||
|
||||
See [blue-pill.md](docs/hardware/blue-pill.md) for wiring notes.
|
||||
|
||||
## Important Target Note
|
||||
|
||||
- Blue Pill `STM32F103` is Cortex-M3 and uses `thumbv7m-none-eabi`.
|
||||
- STM32F0 is Cortex-M0 and uses `thumbv6m-none-eabi`.
|
||||
- Do not mix them.
|
||||
- This repo leaves room for STM32F0 later, but the default path is STM32F103 only.
|
||||
|
||||
## Repo Layout
|
||||
|
||||
- [Cargo.toml](Cargo.toml) - workspace root and pinned shared dependencies
|
||||
- [flake.nix](flake.nix) - reproducible development shell
|
||||
- [.cargo/config.toml](.cargo/config.toml) - default target and linker settings
|
||||
- [memory.x](memory.x) - conservative Blue Pill memory map
|
||||
- [justfile](justfile) - build, flash, run, and lint commands
|
||||
- [examples/README.md](examples/README.md) - example index
|
||||
|
||||
## Nix Setup
|
||||
|
||||
Use Nix flakes. No global `rustup`. No global `cargo install`.
|
||||
|
||||
```bash
|
||||
nix develop
|
||||
```
|
||||
|
||||
The dev shell provides:
|
||||
|
||||
- pinned Rust toolchain
|
||||
- `cargo`, `rustc`, `rustfmt`, `clippy`
|
||||
- `rust-src`
|
||||
- targets for `thumbv7m-none-eabi` and `thumbv6m-none-eabi`
|
||||
- `probe-rs`
|
||||
- `flip-link`
|
||||
- `cargo-binutils`
|
||||
- `just`
|
||||
|
||||
## First Commands
|
||||
|
||||
```bash
|
||||
nix develop
|
||||
just build
|
||||
just flash-blinky
|
||||
just run-blinky
|
||||
```
|
||||
|
||||
If your chip name differs from the default, override it:
|
||||
|
||||
```bash
|
||||
PROBE_RS_CHIP=STM32F103C8 just flash-blinky
|
||||
```
|
||||
|
||||
If you need to inspect available names:
|
||||
|
||||
```bash
|
||||
probe-rs chip list | rg STM32F103
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
- `blinky-basic` - plain `no_std` blink with a simple delay
|
||||
- `blinky-timer` - periodic blink driven by a timer abstraction
|
||||
- `button-input` - poll a button on `PA0`, mirror state on the LED, log transitions
|
||||
- `embassy-blinky` - minimal async blink with Embassy
|
||||
- `embassy-button` - minimal Embassy polling loop for a button on `PA0`
|
||||
|
||||
The button examples assume a simple external button:
|
||||
|
||||
- one side to `PA0`
|
||||
- one side to `3V3`
|
||||
- internal pull-down enabled in firmware
|
||||
- common ground still required for the probe
|
||||
|
||||
## ST-Link Setup
|
||||
|
||||
Typical SWD wiring:
|
||||
|
||||
- `SWDIO` -> `SWDIO`
|
||||
- `SWCLK` -> `SWCLK`
|
||||
- `GND` -> `GND`
|
||||
- `3V3` -> `3V3` reference
|
||||
|
||||
Keep `BOOT0` low for normal flash-and-run.
|
||||
|
||||
## Rusty Probe / probe-rs Note
|
||||
|
||||
- `probe-rs` is the primary flash, run, and debug path in this repo.
|
||||
- Rusty Probe works if the host sees it as a `probe-rs` compatible probe.
|
||||
- Start with `probe-rs list` to confirm the probe is visible.
|
||||
|
||||
## Memory Note
|
||||
|
||||
Many Blue Pill boards have 64K or 128K flash despite markings.
|
||||
This repo uses a conservative 64K flash map in [memory.x](memory.x).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Probe not found
|
||||
|
||||
- Run `probe-rs list`.
|
||||
- Check USB cable and power.
|
||||
- Check `SWDIO`, `SWCLK`, `GND`, and `3V3`.
|
||||
|
||||
### Linux udev permissions
|
||||
|
||||
- You may need udev rules for ST-Link or your probe.
|
||||
- Install the vendor or distro rules, then replug the probe.
|
||||
|
||||
### Wrong chip selected
|
||||
|
||||
- Run `probe-rs chip list | rg STM32F103`.
|
||||
- Override the default with `PROBE_RS_CHIP=...`.
|
||||
|
||||
### No RTT or defmt output
|
||||
|
||||
- Use `just run-blinky` or `just run-embassy-blinky`.
|
||||
- Confirm the firmware did not crash early.
|
||||
- Confirm the probe stays attached.
|
||||
- Confirm `BOOT0` is low.
|
||||
|
||||
### Blue Pill LED looks inverted
|
||||
|
||||
- That is expected on most boards.
|
||||
- `PC13` is usually active-low, so driving it low turns the LED on.
|
||||
|
||||
## Safety
|
||||
|
||||
- Check board voltage before connecting anything.
|
||||
- Check `SWDIO`, `SWCLK`, `GND`, and `3V3` wiring before flashing.
|
||||
- Do not assume a random button or LED pinout without checking the board.
|
||||
|
||||
## Contribution
|
||||
|
||||
- Keep examples independent.
|
||||
- Keep demo reliability first.
|
||||
- Keep `nix develop`, `just fmt`, `just check`, and `just build` working.
|
||||
- Document hardware assumptions when they matter.
|
||||
- Do not claim hardware-tested behavior unless it was actually tested on hardware.
|
||||
Reference in New Issue
Block a user