rusty-dog/README.md

Rusty Dog - Pico W Embedded Rust

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

Build Commands

This project uses a Makefile to simplify common tasks. The Makefile is configured to automatically use direnv to load the Nix environment if direnv is installed on your system. This ensures that the correct Rust toolchain and dependencies are available even if you haven't manually run nix develop or direnv allow.

Command	Description
make build	Build the project using cargo build
make run	Run the project using cargo run
make test	Run tests using cargo test
make clean	Clean build artifacts
make flatpak-build	Build the Flatpak package

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 via USB (BOOTSEL mode)

If you don't have a physical debugger, you can flash the Pico W directly via USB using the BOOTSEL mode:

1. Enter BOOTSEL Mode: Hold the BOOTSEL button on your Pico W while plugging it into your computer's USB port. It should appear as a USB mass storage device.
2. Flash and Run: Run the following command (or use the IDE "Run" button):

   cargo run --release
   

   This project is configured to use elf2uf2-rs, which automatically detects the Pico W in BOOTSEL mode, converts the binary to UF2 format, and flashes it.

Troubleshooting: Flashing Issues

If you encounter issues flashing via USB:

1. Check BOOTSEL mode: Ensure the Pico W is mounted as a USB drive.
2. Udev Rules (Linux): You may need permissions to access the USB device.
   • Create a file named /etc/udev/rules.d/99-pico.rules.
   • Add: SUBSYSTEMS=="usb", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="0003", MODE="0666"
   • Reload rules: sudo udevadm control --reload and sudo udevadm trigger.
3. Cable: Ensure you are using a data-sync USB cable, not just a charging cable.

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".

Note: The project is configured to use direnv exec . in .cargo/config.toml to ensure elf2uf2-rs is available. Ensure direnv is installed and allowed (direnv allow) on your system. For the best experience, we recommend installing the direnv plugin for your IDE.

Flashing from Terminal

You can flash the Pico W by running:

cargo run --release

This uses elf2uf2-rs (configured in .cargo/config.toml) to flash the binary via the USB BOOTSEL mode.

If you prefer to use a physical debugger (e.g. CMSIS-DAP), you can change the runner in .cargo/config.toml to: runner = "direnv exec . probe-rs run --chip RP2040"

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)