Hello VEX world,
Queen’s VEX U Robotics Team (QUEEN) is happy to announce the beta release of our Rust for V5 runtime, which allows you to write code for the V5 brain in the Rust programming language. This is a project which VP (Technical) Tim Morland and I have been working on for a few months now, and which our team is committed to using in the future as our primary means of writing code for the V5.
Before I delve into the technical part, you can take a look at the code on our team GitLab, and view the generated API docs on Docs.RS.
What?
Rust is a general-purpose programming language which was originally developed by Mozilla Research, and now features a range of community and corporate backers, from Mozilla to Amazon and Google. It is used in a variety of projects, from Firefox’s CSS engine to parts of the Discord backend. Recently, it has steadily been expanding into the world of embedded systems, through better support for running “baremetal” (i.e., without a proper operating system).
Our project provides a means for compiling Rust code into a program which can be uploaded to the V5 and a comprehensive Rust API for interacting with hardware and building robust programs, all built on top of PROS. Currently, this includes full support for the controller inputs and smart motors, as well as a large multitasking support library and support for smart ports in generic serial mode; we will be adding support for the ADI and smart sensors over the course of the beta, with the goal of having a fully-capable version 1.0 release by April-ish.
Why?
Rust’s features give it a significant edge over C++ for almost any use-case, including robotics control systems. Like C++, it compiles to efficient machine code; unlike C++, and thanks to the fact that it’s not trying to maintain backwards-compatibility with code from the 1970s, it has a robust method of memory safety which prevents the programmer from making many common mistakes to do with object lifetimes and data races, preventing a whole class of bugs. If you never use the unsafe keyword in your code (which you should never need to as you are not writing code to interact with the underlying hardware), you will never get a “data abort exception” or any other result of incorrect memory management. Code that crashes—or doesn’t crash, but gets in some unpredictable state—can ruin your ability to compete; Rust is designed to prevent exactly this problem.
How?
The runtime works behind the scenes by calling into the PROS C API. Everything from motor outputs to spawning tasks is done this way. In this way, we are building on top of an established, trusted framework.
Note: we currently only run on Linux and Mac OS X. Windows support is Coming Soon™; you can try yourself, but your mileage may vary. The following instructions also assume you have some comfort using the command line.
Installing the Toolchain
Our entire system is built on top of PROS, so you will need all the development tools that you would need to work with PROS code (the PROS editor is not required). See the PROS getting started docs here if you don’t already have those set up.
Next, you’ll need the Rust toolchain. This can be installed from rustup.rs. This will add a command-line utility rustup to manage the Rust toolchain, as well as cargo, Rust’s package manager. Run the following command to add a Cargo utility, cargo-generate, which helps with generating Rust projects from templates:
cargo install cargo-generate
Finally, you’ll need a couple extra packages, namely libclang-dev and llvm-config (or whatever these may be called on your system). On Ubuntu, for example, you can install those with apt-get install -yqq libclang-dev llvm-config.
(If you’re interested, we also have a Docker container, used to run our CI, which includes all of these).
Writing Code
We recommend Visual Studio Code as the editor to use for Rust projects. If you use our template (see below) using VS Code, it should prompt you to install some extensions which will provide all the integrations that you’d expect from a modern development enviornment.
We’ve provided a template project to get started. To make a new project, run the following command after setting up the toolchain:
cargo generate --git https://gitlab.com/qvex/vex-rt-template.git
Once your project is created, open it in VS Code. It should prompt you to install the recommended extensions and download the latest rust-analyzer, which is the tool it uses to show you errors and warnings in your code. You can then open a terminal in it and run cargo build to compile your code, or cargo run to compile and upload. (This internally runs prosv5 ut after generating the required files.) The README.md file contains more info on that.
Contributing
If you’re interested in contributing to this project, feel free to do so via issues and merge requests on GitLab. Contact me if you have any questions about this.
Cheers,
Nick
