Skip to content

Latest commit

 

History

History
149 lines (104 loc) · 6.65 KB

README.md

File metadata and controls

149 lines (104 loc) · 6.65 KB
Raw

RIOT-rs

Build Status Book Documentation Matrix

Rust & RIOT combined for ergonomic embedded development

RIOT-rs is an operating system for secure, memory-safe, low-power Internet of Things (IoT). RIOT-rs is based on Rust from the ground up, and uses formal verification for critical modules. To learn more about our motivations, see this manifesto.

Hardware targets include varieties of IoT hardware based on 32-bit microcontroller architectures (such as Cortex-M, RISC-V).

In practice, RIOT-rs builds on top of Embassy. Compared to what Embassy already provides, RIOT-rs brings additional value in terms of abstraction, operating system functionalities, and integration for a (curated) set of software modules, tools and libraries, as well as a stronger focus on cybersecurity and formal verification.

In particular, RIOT-rs aims to combine:

  • application code portability across all supported hardware, via consistent memory/energy efficient APIs;
  • async programming paradigms, based on Embassy;
  • preemptive scheduler programming paradigms, based on formally verified modules using hax;
  • booting & update security, via measured boot and secure software updates, using formally verified modules.

Overall, RIOT-rs gives you a 'batteries-included' experience, on par with RIOT.

Supported hardware

The following list of hardware is currently supported:

Status

This is currently work-in-progress. Expect missing functionalities and frequent changes! If you are not so adventurous, but nevertheless looking for a way to run your Rust module on a microcontroller, you could try to glue it directly on top of Embassy, or instead, run your module in a riot-wrappers.

Quickstart

The following assumes you have a Nordic nrf52840dk connected to your PC. (For other supported boards, you can find your board's name in ./src/riot-rs-boards/Cargo.toml and use it instead of 'nrf52840dk' in the below guidelines.)

The following instructions will enable you to flash and run 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

  2. install rustup

  3. install laze: cargo install laze

  4. install probe-rs: cargo install probe-rs-tools --locked

  5. clone this repository and cd into it

  6. 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 run

Example

(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

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.