Rusty Dog - Pico W Embedded Rust

This project is an embedded Rust application for the Raspberry Pi Pico W, utilizing the Embassy async framework.

LLM Agent Guidelines

This project uses LLM agents for configuration and housekeeping. Please refer to agents.md for the rules and guidelines governing their use.

Quick Start

nix develop
# or with direnv:
direnv allow

Automatic Environment Setup

When you enter the devShell (via direnv allow or nix develop), the following happens automatically:

✓ Git Repository: Initializes .git if not present ✓ Rust Targets: Automatically adds the RP2040 (Pico W) target: thumbv6m-none-eabi ✓ Cargo Paths: Sets up $HOME/.cargo/bin in PATH for cargo-installed binaries ✓ Welcome Banner: Displays available tools and quick commands

No manual setup needed! Just start coding.

Quickstart

nix flake init -t path:../flakes#rust
nix develop
cargo build

Embedded Rust Support

The devShell automatically installs the Raspberry Pi Pico W target via rustup:

Target	Platform	Use Case
thumbv6m-none-eabi	ARM Cortex-M0/M0+	RP2040 (Pico W)

Flatpak Packaging

This template supports building Flatpak packages for your Rust application.

Build Flatpak Package

1. Ensure you have flatpak-builder installed.
2. Run:

make flatpak-build

This will use the manifest at flatpak/app.flatpak.json to build a Flatpak bundle in the build-flatpak/ directory.

Customize Manifest

Edit flatpak/app.flatpak.json to update app ID, runtime, build commands, or sources as needed for your project.

Install/Run Flatpak Locally

You can install and run the built Flatpak locally:

flatpak install --user build-flatpak/org.example.rustdevshell.flatpak
flatpak run org.example.rustdevshell

Included Tools

Tool	Purpose
cargo	Rust package manager and build system
rustc	Rust compiler
clippy	Rust linter for catching common mistakes
rustfmt	Rust code formatter
rust-analyzer	Language server for IDE integration
rust-src	Rust source code (for tools like rust-analyzer)
probe-rs	Embedded debugger/flasher
openocd	JTAG/SWD debugger
minicom	Serial terminal for device output
elf2uf2-rs	Convert ELF to UF2 format (RP2040)
picotool	Pico-specific firmware operations
cargo-binutils	LLVM tools for size and object analysis
flip-link	Stack overflow protection for embedded
tea	Gitea CLI for repository management

Flashing & IDE Integration

This project is configured for seamless flashing from the IDE or terminal.

Flashing from IDE

If you are using RustRover or IntelliJ Rust, you can use the "Flash Pico W" run configuration provided in the .run folder. Just select it from the run menu and click "Run".

Flashing from Terminal

You can flash the Pico W by running:

cargo run --release

This uses probe-rs (configured in .cargo/config.toml) to flash and run the binary via a CMSIS-DAP debugger or similar.

If you prefer to use the UF2 bootloader (dragging to the drive or using elf2uf2-rs), you can change the runner in .cargo/config.toml to: runner = "elf2uf2-rs -d"

Testing & Development Features

Build and testing tools:

• cargo test - Run unit and integration tests
• cargo clippy - Lint code for common issues
• cargo fmt - Format code consistently with rustfmt

Example usage:

# Run tests
cargo test

# Check code with clippy
cargo clippy

# Format code
cargo fmt

# Build for embedded target
cargo build --target thumbv6m-none-eabi --release

# Analyze binary size
cargo size --target thumbv6m-none-eabi --release

Project Layout

Cargo.toml
Cargo.lock
src/
  └── main.rs (or lib.rs)
Makefile
.envrc
flake.nix

Legacy Usage

If you do not use flakes, run:

nix-shell

Project Metadata

See project.toml for example metadata.

Helper Tools

• nix run .#dev-helper - Display tool versions and availability
• cargo build - Build the project
• cargo check - Quick syntax check without building
• cargo doc --open - Generate and view documentation

Packaging for nixpkgs

This template is structured for easy packaging in nixpkgs:

• All sources in src/
• flake.nix provides a devShell and template
• Add a default.nix or package expression as needed for nixpkgs

See nixpkgs Rust packaging docs for more details.

Customization

Edit flake.nix to:

• Add additional Rust targets via rustup target add [target]
• Include additional cargo plugins
• Add board-specific tools (e.g., stm32cube, nrfjprog)