rust-stm32/AGENTS.md

AGENTS

Map

• Root has workspace files.
• examples/ has one crate per demo.
• docs/hardware/ has board and wiring notes.
• memory.x is shared.
• justfile is source of truth for commands.

Rules

• Read before edit.
• Keep fixes small.
• No broad refactor.
• No dependency upgrade unless asked.
• Keep examples independent.
• Keep demo reliability first.
• Use simple code.
• No hidden IDE steps.
• No fake hardware claims.

Preserve

• nix develop
• just fmt
• just check
• just build

Hardware

• Blue Pill first.
• thumbv7m-none-eabi first.
• Do not mix STM32F0 with STM32F103.
• If hardware detail is unclear:
  • write the assumption
  • add a TODO
  • keep build green

Style

• Caveman style.
• Short names.
• Short comments.
• Explain embedded idea.
• Do not explain obvious Rust syntax.
• No heap.
• No dynamic dispatch unless teaching needs it.
• No async before Embassy examples.
• unsafe only if required and justified.

Commands

• just build
• just build-blinky
• just build-timer
• just build-button
• just build-embassy-blinky
• just build-embassy-button
• just flash-blinky
• just flash-timer
• just flash-button
• just flash-embassy-blinky
• just flash-embassy-button
• just run-blinky
• just run-embassy-blinky
• just fmt
• just clippy
• just check
• just clean

Do Not

• Do not invent board output.
• Do not claim flash or debug worked on hardware unless tested.
• Do not hide chip mismatches.
• Do not add abstractions for one use.