Rust for Arduboy

Running Rust on the Arduboy miniature game system.

The most important first. I didn't create this project from scratch, @Seeker14491 the legend has already done a lot in his old project ArduboyRust

I just updated and completed the project.

What do i mean by completed?

I provided all the important functions from the Arduboy2 library in a safe Rust API.

Most of the Arduboy2 funktions can be called the same way like in C.

How to use this Project

First clone the repo

git clone https://github.com/ZennDev1337/Rust-for-Arduboy

Install PlatformIO Core on your system. I recommend the pip install if you don't want to configure a new path variable for pio. Otherwise you will know how to do that.

The rust-analyzer will complain about a missing test crate to fix this add the following rule to the lsp settings :

{
  "rust-analyzer.checkOnSave.allTargets": false
}

If your using Visual Studio Code: Create a folder named .vscode and a file named settings.json inside. Past the setting above in the new file. (I have excluded my .vscode folder because I have many different settings there that you don't need)

Your game is located in the Project/game folder. This is also the folder you are working in

Inside the game folder you will find a lib.rs file which contains the setup and loop function as you know it from a normal Arduboy C project.

You can find the Docs here:

• arduboy-rust Crate Docs

or you can use the following command to open the arduboy-rust Crate docs locally

cargo doc -p arduboy-rust --open

Most of the time you will use the prelude. There is listed witch funktionality you will have.

And last but not least there are multiple examples inside of the Examples folder which shows you how to use the functions. I will from time to time also upload my projects to the Example folder so you have as much ressurces as possible.

Usage of the run tool

Both run scripts (only works if you use the given folder structure)

requirements:

• PlatformIO Core must be installed
• The Arduboy must be plugged in
• You are in the root directory of this project

All builded .hex files are saved inside of arduboy-rust/Wrapper-Project/build/<GAMENAME>.hex after you uploaded them to the Arduboy.

To upload your own game to the Arduboy use:

Linux:

./run <Project_Name>

Windows:

.\run.bat <Project_Name>

List of all the Example Games:

ZennDev1337 Games

• drboy

Rust Games

• snake
• rustacean

The demo games / tutorials from the official Arduboy forum [Rewritten in Rust]

• Make Your Own Arduboy Game: Part 1 - Setting Up Your Computer
• [demo2] Make Your Own Arduboy Game: Part 2 - Printing Text
• [demo3] Make Your Own Arduboy Game: Part 3 - Storing Data & Loops
• [demo4] Make Your Own Arduboy Game: Part 4 - Questions & Button Input
• [demo5] Make Your Own Arduboy Game: Part 5 - Your First Game!
• [demo6] Make Your Own Arduboy Game: Part 6 - Graphics! Link for the ZennDev1337 Tile Converter
• [demo7] Make Your Own Arduboy Game: Part 7 - Make Pong From Scratch!
• Prepare for demo9 Make Your Own Arduboy Game: Part 8 - Starting DinoSmasher
• [demo9] Make Your Own Arduboy Game: Part 9 - Mapping DinoSmasher
• [eeprom] Help, I’m struggling with EEPROM!
• [eeprom-byte] Help, I’m struggling with EEPROM!
• [progmem] Usage of the big 28'000 Bytes flash memory for Bitmaps Sound sequeces and Text.
• [tone] ArduboyTonesTest

Usage of the FX Chip

requirements:

python3 -m pip install pyserial pillow

You need to create a fxdata folder in your project directory.

Don't forget to uncomment the ArduboyFX_Library line in the import_config.h file.

run Commands:

|Project_Dir
->fxdata
->src
  ->lib.rs
>cargo.toml

You also need a fxdata.txt file in this new folder.

See the examples in Examples/ArduboyFX.

More information:

• Arduboy-Python-Utilities by MrBlinky

run Commands:

• fxbuild is used to build the fxdata.dat file.
• fxupload is used to upload the fxdata.dat file.
• fxall is used to build and upload the fxdata.dat file and build and upload the game all in one step.

Linux:

./run fxbuild <Project_Name>
./run fxupload <Project_Name>
./run fxall <Project_Name>

Windows:

.\run.bat fxbuild <Project_Name>
.\run.bat fxupload <Project_Name>
.\run.bat fxall <Project_Name>

Convert the fxdata.h file to Rust

FXdata Converter by ZennDev1337

Create a new project

In the root of the repo use the command:

(Don't use "-" in the name because of a cargo feature that takes the "-" and mixes sometimes with a "_". You will have some weird behavior with the run tool.)

cargo new --vcs=none --lib ./Project/newproject

Then open the Cargo.toml in your new project and add the following dependencies and settings:

[lib]
crate-type = ["staticlib"]

[dependencies]

arduboy-rust = { path = "../../arduboy-rust" }

Next jump in your lib.rs file and add the following:

#![no_std]
#![allow(non_upper_case_globals)]

//Include the Arduboy Library
#[allow(unused_imports)]
use arduboy_rust::prelude::*;

#[allow(dead_code)]
const arduboy: Arduboy2 = Arduboy2::new();

// Progmem data

// dynamic ram variables

// The setup() function runs once when you turn your Arduboy on
#[no_mangle]
pub unsafe extern "C" fn setup() {
    // put your setup code here, to run once:
}

// The loop() function repeats forever after setup() is done
#[no_mangle]
#[export_name = "loop"]
pub unsafe extern "C" fn loop_() {
    // put your main code here, to run repeatedly:
}

Now the last step. Go in the Cargo.toml in the root directory and add your project:

[workspace]
members = [
    #{All other Projects...}
    "Project/newproject",
]
resolver = "2"

To run and upload your game use the run tool

# Linux
./run newproject

# Windows
.\run.bat newproject

Creating and building an Arduboy crate [Outdated]

You can find instructions on how all build steps work in detail here ArduboyRust creating and building an arduboy crate

Linking the static library to the Arduino C++ project [Outdated]

Instructions on how to link all the static libraries in the Arduino C++ project can be found here ArduboyRust linking the static library to the arduino c++ project

Credits

Thanks to @Seeker14491 who wrote ArduboyRust, the starting point for me to create my own project based on this project. (you are a hero <3)

Thanks to @simon-i1-h who wrote arduboy-hello-rs, the proof of concept that inspired me to try Rust on the Arduboy.

License

You can license it under either one of those licenses:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

Whichever you may prefer.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.