Manifesto

We must (re)write the foundations of system software on more solid ground. Even POTUS roots for it! For the Internet of Things, our cyberphysical world under continuous development, we need stronger cybersecurity.

So what does it mean for the main embedded operating systems targeting networked microcontrollers (Zephyr, FreeRTOS, or RIOT) which are primarily written in C?

Well, how about using instead a memory-safe language, Rust, as foundation. And for good measure, how about formal verification for the critical modules cherry-picked incrementally, along the way. Implementing the above guidelines is exactly the mission of RIOT-rs: collaboration to produce open source re-write(s) of RIOT core modules providing a basis for next-level cybersecurity in IoT.

Curious about more details on principles driving RIOT-rs development? Here you go.

Southbound, RIOT-rs builds on top of Embassy which provides an awesome open source HAL for a large variety of low-power IoT hardware, written in Rust.

Northbound, RIOT-rs provides high-level APIs working nicely across all supported hardware (work-in-progress) for generic sensors/actuators interaction (such as SAUL) and for generic network I/O (such as sock).

At the core, RIOT-rs provides a programming framework for both async and blocking (threads with priorities) paradigms and convenient scaffolding to bundle various the libraries and 3rd party modules you need.

True to the spirit of RIOT development, RIOT-rs aims at a level of integration and code portability such that ~95% of the code is reused as-is on all supported hardware. The targeted memory footprint (RAM & Flash) is measured in tens of kBytes. The targeted power consumption levels enable applications lasting 1+ years on a small battery.

Last but not least the CI process for each pull-request to RIOT-rs includes extensive and rigorous tests which are automated for all supported configuration and hardware. And for selected modules, a formal verification workflow is used based on hax, running directly on the functional Rust.

Long story short: RIOT-rs embodies the developing love affair between RIOT and embedded Rust, fostering stronger IoT cybersecurity. This is a joyous open source community, so... you're welcome to join us!

Introduction

RIOT-rs RIOT-rs is a project aiming to provide a general-purpose operating system adequate for low-power Internet of Things (IoT).

RIOT-rs is based on Rust from the ground up, and formal verification for critical modules. It combines the awesome Rust embedded ecosystem with RIOT OS.

RIOT-rs builds on top of the hardware abstraction layer and async programming framework provided by embassy and drivers via embedded-HAL.

Aiming to cover versatile use cases, RIOT-rs integrates and combines the above HAL with a preemptive scheduler, a set of efficient operating system facilities, a bootloader, and a curated ecosystem of libraries (available via crates.io) for cybersecure, memory-safe IoT.

As a result, a low-power IoT developer can focus on business logic sitting on top of APIs which remain close to the hardware but nevertheless stay the same across all supported hardware. The intent is three-fold: decrease application development time, increase code portability, and decrease core system vulnerabilities.

RIOT-rs can also be used to host legacy C application and libraries. However, the essence and ultimate goal of the RIOT-rs is to provide everything one might need in Rust.

Architecture

RIOT-rs Code of Conduct

RIOT-rs, like so many other free and open source software projects, is made up of a mixed group of professionals and volunteers from all over the world, working on every aspect of our goals - including teaching, steering, and connecting people.

We want diversity to be one of our greatest strengths, but it can also lead to communication issues and unhappiness. This is why we ask people to adhere to a few ground rules. They apply equally to founders, maintainers, contributors and those seeking help and guidance.

This is not meant to be an exhaustive list of things you are not allowed to do. We rather would like you to think of it as a guide to enrich our community and the technical community in general with new knowledge and perspectives by allowing everyone to participate.

This code of conduct applies to all spaces managed by the RIOT-rs community. This includes Matrix, the mailing lists, our GitHub projects, face to face events, and any other forums created by the community for communication within the community. In addition, violations of this code outside these spaces may also affect a person's ability to participate within them.

If you believe someone is violating the code of conduct, we ask that you report it by emailing conduct@riot-rs.org. For more details please see our Reporting Guidelines.

Be friendly and patient.
Be welcoming. We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
Be considerate. Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we're a world-wide community, so you might not be communicating in someone else's primary language.
Be respectful. Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the RIOT-rs community should be respectful when dealing with other members as well as with people outside the RIOT-rs community.
Be careful in the words that you choose. We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren't acceptable. This includes, but is not limited to:
- Violent threats or language directed against another person.
- Discriminatory jokes and language.
- Posting sexually explicit or violent material.
- Posting (or threatening to post) other people's personally identifying information ("doxing").
- Personal insults, especially those using racist or sexist terms.
- Unwelcome sexual attention.
- Advocating for, or encouraging, any of the above behavior.
- Repeated harassment of others. In general, if someone asks you to stop, then stop.
When we disagree, try to understand why. Disagreements, both social and technical, happen all the time and RIOT-rs is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. The strength of RIOT-rs comes from its varied community, people from a wide range of backgrounds. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.

Text based on the Code of Conduct of the Django community.

Questions?

If you have questions, please feel free to contact us.

If you believe someone is violating the code of conduct we ask that you report it to us by emailing conduct@riot-rs.org.

All reports will be kept confidential. In some cases we may determine that a public statement will need to be made. If that's the case, the identities of all victims and reporters will remain confidential unless those individuals instruct us otherwise.

If you believe anyone is in physical danger, please notify appropriate law enforcement first. If you are unsure what law enforcement agency is appropriate, please include this in your report and we will attempt to notify them.

If you are unsure whether the incident is a violation, or whether the space where it happened is covered by this Code of Conduct, we encourage you to still report it. We would much rather have a few extra reports where we decide to take no action, rather than miss a report of an actual violation. We do not look negatively on you if we find the incident is not a violation. And knowing about incidents that are not violations, or happen outside our spaces, can also help us to improve the Code of Conduct or the processes surrounding it.

In your report please include:

Your contact info (so we can get in touch with you if we need to follow up)
Names (real, nicknames, or pseudonyms) of any individuals involved. If there were other witnesses besides you, please try to include them as well.
When and where the incident occurred. Please be as specific as possible.
Your account of what occurred. If there is a publicly available record (e.g. a mailing list archive or a public Matrix logger) please include a link.
Any extra context you believe existed for the incident.
If you believe this incident is ongoing.
Any other information you believe we should have.

What happens after you file a report?

You will receive an email from one of the core community members as soon as possible. We promise to acknowledge receipt within 24 hours (and will aim for much quicker than that).

They will review the incident and determine:

What happened.
Whether this event constitutes a code of conduct violation.
Who the bad actor was.
Whether this is an ongoing situation, or if there is a threat to anyone's physical safety.

If this is determined to be an ongoing incident or a threat to physical safety, their immediate priority will be to protect everyone involved. This means we may delay an "official" response until we believe that the situation has ended and that everyone is physically safe.

Once the working group has a complete account of the events they will make a decision as to how to response. Responses may include:

Nothing (if we determine no violation occurred).
A private reprimand from us to the individual(s) involved.
A public reprimand.
An imposed vacation (i.e. asking someone to "take a week off" from a mailing list or Matrix).
A permanent or temporary ban from some or all RIOT-rs spaces (mailing lists, Matrix, etc.)
A request for a public or private apology.

We'll respond within one week to the person who filed the report with either a resolution or an explanation of why the situation is not yet resolved.

Once we've determined our final action, we'll contact the original reporter to let them know what action (if any) we'll be taking. We'll take into account feedback from the reporter on the appropriateness of our response, but we don't guarantee we'll act on it.

Reference

These reporting guidelines were adapted from the Django reporting guidelines

Appendices

Coding Conventions

Item Order in Rust Modules

Items SHOULD appear in Rust modules in the following order, based on the one used by rust-analyzer:

Inner doc comment
Inner attributes
Unconditional—i.e., not feature-gated—bodyless modules
Conditional—i.e., feature-gated—bodyless modules
Unconditional imports from the following:
1. std/alloc/core
2. External crates (including crates from the same workspace)
3. Current crate, paths prefixed by crate
4. Current module, paths prefixed by self
5. Super module, paths prefixed by super
6. Re-exports—i.e., pub imports not used in the module
Conditional imports from the same
Const items
Static items
Other items

TODO: type aliases before other items?

TODO: how to organize type definitions w.r.t. related logic?

Imports

Imports from the same crate with the same visibility MUST be merged into a single use statement.

Comments

Doc Comments

All public items listed in the documentation—i.e., not marked with #[doc(hidden)]—SHOULD be documented.

Doc comments MUST use the line comment style, not the block style.

Doc comments MUST be written in third person present, not in the imperative mood, as recommended by RFC 1574. Each sentence in doc comments—including the first one, before an empty line—SHOULD end with a period. For instance, instead of:

#![allow(unused)]
fn main() {
/// Get the underlying value
}

write:

#![allow(unused)]
fn main() {
/// Returns the underlying value.
}

More generally, use the std docs as inspiration.

When possible—i.e., when items are in scope—items mentioned in the documentation MUST be linked to (see C-LINK). This is useful for readers, to quickly access the mentioned item, but it also helps prevent the docs from lagging behind, as broken links are tested for in CI, making it easy to spot renamed or removed items.

RIOT-rs manual