Trowel

This is a sister project to the spade Sprig engine. It is a Sprig firmware implementation in rust.

Install rust

Follow these instructions to install rust on your computer.

Setup rust for cross platform development

Run these commands in a Unix shell or cmd.exe on Windows.

rustup target add thumbv6m-none-eabi
cargo install cargo-binutils
rustup component add llvm-tools-preview
cargo install elf2uf2-rs
cargo install probe-run
cargo install flip-link
cargo install wasm-server-runner

Ancillary Dependencies

For the most part cargo will handle all the dependencies. However, the rust sdl2 crate does require SDL2 to be installed for the PC simulator. Follow these instructions for your operating system to install SDL2.

Clone the repository

git clone https://github.com/shanecelis/trowel.git
cd trowel

Simulate on your PC

cargo run --example maze

Run on your sprig

cargo run --example maze --target thumbv6m-none-eabi

Or use the run-sprig alias.

cargo run-sprig --example maze

Run as a Web Assembly

cargo run --example maze --target wasm32-unknown-unknown

Or use the run-wasm alias.

cargo run-wasm --example maze

Build Web Assembly

./bin/build-wasm maze

Generates a web assembly files and index.html for deployment.

maze
├── index.html
└── wasm
    ├── maze.d.ts
    ├── maze.js
    ├── maze_bg.wasm
    └── maze_bg.wasm.d.ts

Examples

• hello_world
• maze
• draw_ferris

cargo run --example $example

Runty8 Examples

Runty8 is a pico-8 clone in rust. Trowel has an adapter so any runty8 games can run on the Sprig.

• bresenham
• moving-box
• celeste (!!!)

cargo run --example celeste --features runty8 --release

Notes

See the .cargo/config.toml for various build and run settings. You can generate uf2 files, write directly to the sprig if it's in BOOTSEL mode, or you can use a debug probe.

TODOs

• Add sound support
• Add SD card support
• Buffer the output to increase responsiveness

"The framerate is not great on this. But it's the tip of the iceberg. There's a ton that can be done to improve it. The screen is the big bottleneck, we can get maybe 10 or 20 fps redrawing the whole thing. But the screen also remembers everything, so if you don't draw to a part of it, you don't need to update it. So if we buffered the output with two framebuffers, we can check them for differences. Pretend we had only a 1-bit display, then we could XOR our buffers, that'd give us a table of all the pixels that would need to change. One could also double the framerate by interlacing, update odd and even rows or columns every other frame. So some neat opportunities there to make it more performant."

Runty8 TODOs

• Add a runty8 adapter
• Make examples run: bresenham, moving-box.
• Make celeste run (!!!).
• Add binary serialization support.
• Don't make copies upon binary deserialization. (Memory is precious here.)
• Add a mouse simulator mode.
• Make carts load-able.
• Add more optimizations for rendering (ideas)

Advanced: Setup probe

If you have an extra pico, you can set one up as a debug probe. It is super useful. You can run your code through the debugger. You'll get stacktraces and panic messages when your code fails.

Requirements

• sprig
• extra pico
• breadboard
• wires

Load probe firmware

The probe needs to have this uf2 installed.

Wire the probe to the target sprig

See this page and the Getting Started Guide for more information.

Change to use probe-run

Once you have that setup, you can change your runner in the .cargo/config.toml file.

runner = "probe-run --chip RP2040"

Troubleshooting debug probe

Once your debug probe has been flashed and it's plugged in, see if probe-run can find it.

$ probe-run --list-probes
the following probes were found:
[0]: Picoprobe CMSIS-DAP (VID: 2e8a, PID: 000c, Serial: E66164084367642A, CmsisDap)

Acknowledgments

• Thanks to Leo McElroy, Cedric Hutchings, Kognize, and the whole Hack Club team for creating the Sprig and for making it an open platform in both hardware and software.

• Thanks to Zach Latta, Christina Asquith, and the Hack Club donors who have made the Sprig free for teenagers, making it an accessible platform.

• Thanks to the hundreds of Hack Club members who have made hundreds of games for the Sprig, making it a vibrant platform.

• Thanks to Andrew Christiansen for the rp2040-examples in st7735-lcd-examples that provided a good basis for this project.

• Thanks to Grant Shandy for this article on raytracing in rust and the maze code ported as an example in this project.