Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Preparation

Windows Terminal

It is recommended to use a terminal for some parts of this workshop. There will be a lot of steps and instructions which show terminal commands. On Windows, you should install a proper terminal unless you plan to use something like WSL.

For example, you can install PowerShell.

Cloning the project with git

It is strongly recommended to clone the project with git. If you have never worked with git before, you should work through a tutorial online first, for example this interactive one. Alternatively, have a look at the learning resources. If you are a git beginner, you can install it using the website instructions.

The project is hosted on GitHub publicly. It is also hosted on the IRS GitLab which you can access if you are an IRS employee.

You can clone this workshop by running the following git command:

git clone https://github.com/us-irs/embedded-rust-workshop.git

or with SSH:

git clone git@github.com:us-irs/embedded-rust-workshop.git

If you are an IRS employee and have access to the IRS GitLab:

git clone https://git.irs.uni-stuttgart.de/irs/embedded-rust-workshop.git

or with SSH:

git clone git@git.irs.uni-stuttgart.de:irs/embedded-rust-workshop.git

Have a look at the README of the repository. It explains the directory structure. The most relevant part of the repository for you is the firmware/exercises folder.

It is recommended that you create your own private branch as you progress through the exercises. For example, you can use

git switch -c my-exercise-branch

to create your own exercise branch.

Now that you have cloned the project, you might have to set up some software.

Rust and cargo

The first thing required is the Rust compiler and the cargo build and dependency management tool. The Rust installation includes the cargo tool, so all you need to do is install Rust by going to the Rust website and following the operating system specific instructions.

After you have done this, you can verify your installation by running:

cargo version

Normally, you would also have to install the thumbv7em-none-eabihf toolchain and some other useful tools, but this is performed automatically for you through the rust-toolchain.toml file in the code directory.

You need to install a special linker called flip-link for building the software. Run the following command in the terminal:

cargo install flip-link

Flasher tool probe-rs

Next, you need some software which allows flashing the micro:bit via the USB interface. We are going to use the probe-rs tool, which is well integrated into the Rust ecosystem.

The probe-rs website has install instructions for various operating systems. Follow these, and then test your installation using the following command

probe-rs --version

USB permission setup (Linux only)

Finally, if you are on Linux, you need to perform some steps related to udev to avoid permission issues. probe-rs has a page with steps you can follow.

WSL setup

If you use Windows + WSL, you need to perform some specific steps to allow using a USB device from WSL. The following page contains more detailed descriptions.

TLDR steps:

  1. Install USBPID in PowerShell

    winget install --interactive --exact dorssel.usbipd-win

  2. Reboot PC

  3. Detect the device using usbipd list inside PowerShell and determine the bus ID.

  4. Attach the USB to WSL using (in this case, bus ID was determined to be 2-4)

    usbipd attach --wsl --busid 2-4

  5. Now you can create a WSL shell and use lsusb to check for the USB device.

IDE

You can use any IDE of your choice which has good Rust Analyzer support.

If you are looking for a solid graphical IDE, VS Code is an excellent choice. Make sure to install the rust-analyzer plugin as well.

Testing everything

If you are preparing everything for the workshop, and you do not have access to the hardware yet, you are done! You can perform this step once you have access to the hardware in the workshop.

Now you should have everything you need to build and flash some application to the board. You can flash a test application now to verify the setup. We provide some test applications for you.

Connect the board to your computer using a Micro-USB cable. Make sure that your cable also supports the data interface and is not power-only.

Navigate into the firmware/apps directory.

Now, you can run the following command to build and flash a blinky application:

cargo run --bin blinky

On the console, you should see an output like this:

❯ cargo run --bin blinky
   Compiling rust-app v0.1.0 (/home/muellerr/Rust/rust-embedded-workshop/code/app)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.17s
     Running `probe-rs run --chip nRF52833_xxAA --allow-erase-all target/thumbv7em-none-eabihf/debug/blinky`
      Erasing ✔ 100% [####################]  48.00 KiB @  35.81 KiB/s (took 1s)     Finished in 3.55s
-- micro:bit Blinky application --

If probe-rs can not detect anything, make sure that (a) the board is connected through USB, and (b) the udev rules were setup properly if you are on Linux.

If everything goes right, you should see the LED in the top-left corner blinking with a frequency of 1 second. If this is the case, congratulations, you have built and flashed an embedded Rust app and you made it through the preparation chapter successfully!

In the first exercise, you are going to build most parts of a blinky.