212 lines
6.5 KiB
Markdown
212 lines
6.5 KiB
Markdown
# 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](agents.md) for the rules and guidelines governing their use.
|
|
|
|
## Quick Start
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
### Troubleshooting: No Connected Probes
|
|
|
|
If you encounter the error `Error: No connected probes were found` or udev rule warnings, check the following:
|
|
|
|
1. **Hardware Connection**: Ensure your Raspberry Pi Pico W is connected via a compatible debugger (e.g., another Pico running `picoprobe`, a CMSIS-DAP debugger, or an ESP-Prog).
|
|
2. **Udev Rules (Linux)**: `probe-rs` needs permission to access the USB device.
|
|
- Create a file named `/etc/udev/rules.d/69-probe-rs.rules`.
|
|
- Add the rules provided by the [probe-rs documentation](https://probe.rs/docs/getting-started/probe-setup/).
|
|
- Reload rules: `sudo udevadm control --reload` and `sudo udevadm trigger`.
|
|
3. **Group Membership**: Ensure your user is in the `plugdev` or `dialout` group (depending on your distro's udev rules).
|
|
|
|
### 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 `probe-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:
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```sh
|
|
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](https://nixos.org/manual/nixpkgs/stable/#rust) 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)
|