RIOT-rs

Rust & RIOT combined for ergonomic embedded development

This is an experimental project to provide a nice base OS for embedded development on low-end IoT devices (with some kilobytes of RAM/flash, think Cortex-M). It combines the awesome Rust embedded ecosystem with RIOT.

This is highly experimental. Expect heavy changes and breakage!

If you're looking for a more production ready way of writing RIOT applications in Rust, check out riot-wrappers.

Goals

• improve RIOT using the merits of Rust.
• provide a "rusty" development workflow (e.g., using cargo / crates.io)
• provide a nice Rust API, framework and collection of crates suitable for embedded development
• rewrite parts of RIOT in Rust to improve robustness and maintainability

Supported hardware

The following list of hardware is currently supported

• Nordic nRF52840 DK
• Raspberry Pi Pico

Status

The current iteration of RIOT-rs combines embassy with a preemptive scheduler and adds some integration and build system work.

Quickstart

Assuming you have a Nordic nrf52840dk connected, the following guidelines provides instructions for flashing and running the hello-world example:

Prerequisites

1.install needed system dependencies. On Ubuntu, the following is sufficient:

    apt install build-essential curl git python3 pkg-config \
               libssl-dev llvm-dev cmake libclang-dev gcc-arm-none-eabi \
               clang libnewlib-nano-arm-none-eabi unzip lld ninja-build

1. install rustup

2. install laze: cargo install laze

3. install probe-rs: cargo install probe-rs --features cli (2023-10-17: if that fails, try from git: cargo install --git https://github.com/probe-rs/probe-rs --features cli probe-rs)

4. clone this repository and cd into it

5. install rust targets: laze build install-toolchain

Run the example

1. Compile, flash and the hello-world example using probe-rs run

    laze -C examples/hello-world build -b nrf52840dk -s probe-rs-run run
   

(might fail if the flash is locked, click here for unlocking instructions)

This might fail due to a locked chip, e.g., on most nrf52840dk boards that are fresh from the factory. In that case, the above command throws an error that ends with something like this:

An operation could not be performed because it lacked the permission to do so: erase_all

The chip can be unlocked using this command:

laze -C examples/hello-world build -b nrf52840dk flash-erase-all

More information

Please look at the build system documentation for more usage information.

Minimum Supported Rust Version (MSRV)

RIOT-rs makes heavy use of Rust unstable features. For the time being, it is recommended to use a current nightly.

Coding Conventions

Please see the chapter on coding conventions in the documentation.

Copyright & License

RIOT-rs is licensed under either of

• 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)

at your option.

RIOT-rs links with many components of RIOT OS, which is licenced under the terms of LGPLv2.1.

Copyright (C) 2020-2023 Freie Universität Berlin, Inria, Kaspar Schleiser

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.