The Embedded Rust Book

[jamesmunns]

This is a tracking issue for an official guide to using rustlang on microcontroller targets.

For now, these are the major steps:

• Add a book/ folder to this repository (until a better home is found)
  • Populate the book folder with an MdBook project
• Add some kind of CI to render the book
• Determine where to host the book (possibly gh-pages of this repo for now?) -- https://book.rust-embedded.org/
• Populate the book with some kind of content (see below)
• Submit for official inclusion in The Rust Bookshelf

Audience

I think the first step is to decide the audience of this book. I think the major factors are:

1. Do we expect that they already are relatively confident with microcontrollers?
2. Do we expect that they already are relatively confident with Rust?

This gives us four possible target audiences. I will leave it up to discussion which of these four audiences we would like to initially target. We may extend the Book to cover all four eventually, but we may try and target some subset to get something going at first.

Content

Once we have decided who the (initial) audience is, it will be necessary to determine the content of the book.

Initially, I would suggest the following organization:

1. The Rust Language itself, at least how developing microcontrollers differs from "regular" Rust applications
2. The Rust Tooling and Ecosystem, particularly Cargo, Crates, and crates.io.
   1. This should include a full "getting started guide", getting to hello world/blinkenlights for at least one target
   2. We have to make this guide good, as it could be a big "falling off point" if people's first attempts fail
3. Layers of developing embedded software in Rust:
   1. Writing/Integrating "Chip Support Crates" - i.e. register/peripheral level access and drivers
   2. Writing/Integrating "Board Support Crates" - i.e. constrained to a specific hardware configuration
   3. Writing/Integrating drivers for external components - i.e. sensors, radios, etc
   4. Writing/Integrating higher level applications
4. Perhaps a more advanced guide, covering all the topics of 3 from start to finish, similar to the Guessing Game in the Rust Book
5. Interoperability with existing C/C++ codebases
   1. Should consider "a little Rust with your C", and "a little C with your Rust" experiences
   2. May cover more advanced topics, like integrating with common RTOSs.

Concerns

We must decide how existing documentation, guides, and tooling falls into the following categories:

1. Required steps - these guides/tools cover MUST DO. For example, using rustc/cargo to produce a #[no_std] elf/hex that can run on a given target. We should expect these items to be officially supported by the Rust organization proper
2. Recommended steps - these guides/tools cover steps we expect MOST people to use. For example how to organize Chip/Board Support Crates, use of embedded-hal, etc. People should not expect these items to be officially supported or required. A parallel here would be nursery level crates like Futures, Tokio, Error Chain, etc.
3. Example steps - these guides/tools cover things that are community driven, but widely used. i.e. Tock-OS, RTFM, svd2rust, etc. A parallel here would be crates like Serde, Hyper, etc.

I say these items are a concern, because we must be careful to avoid "blessing" parts of the ecosystem that are not officially maintained, as it will cause us to update our documentation if these components fall out of maintenance or fashion (or expose our users to a "broken" experience).

Additionally, we must discuss what embedded targets we will use for these guides. Chips from different architectures and manufacturers have an extremely wide variance in how they act, and if the guide is only written for an STM32, developers may struggle with an nRF5x or AVR based chip. I think initially, we should at least cover the officially supported thumb* architectures, and if the MSP, AVR and/or RISC-V branches are merged upstream, we should expect to update the guide to cover them around the same time as they become officially supported by Rustlang (We could also cover them beforehand, but I would say we MUST cover them when officially supported).

Reuse of existing material

There are a lot of existing blog posts, projects, etc. that can be used. Care must be taken to make sure anything we integrate into the official guide must be up to date and correct. Additionally it may require editing to fit the "style" of the book, to make sure developers have a consistent experience.

Maintainers

We will need to have maintainers for the book. (@jamesmunns) is willing to take this up initially, but will absolutely need help. Additionally, we should probably reach out to the Docs working group for guidance here (CC @carols10cents @steveklabnik).

[jamesmunns]

Related issues:
#54 - IDE Development Guide
#49 - Material for the revamped website
#22 - Tools you need/want
#12 - Tools you frequently use
#15 - provide real content at rust-embedded domains

[ah-]

Oh fantastic! I've been thinking about how to document an embedded pet project of mine and it will be super useful to have an up to date book to point to for how to get started with microcontrollers and Rust.

Regarding the audience, I could see many people coming from a traditional embedded background being interested, without them having much prior Rust experience.

[ratkins]

If you mean to take an audience survey, I'm in the "confident with µCs, new to Rust" quadrant. I think a significant "market" for embedded Rust is people who like Arduino but have the hump with C++.

I think your points 1, 2 are a fantastic start, and I would consume them voraciously. One of the problems I've faced (and I've seen others mention) is that there are a number of "blink an LED with Rust!" blog posts/tutorials out there, but they all target different µCs, take different (from-scratch) approaches, and were written up to years apart, and therefore start with a different set of variously outdated assumptions. A canonical "this is how you get a functional embedded Rust environment" reference would be 💯.

Of particular note for section 2 ii) is how to install the correct dependencies on macOS, Windows and Linux. On macOS particularly, anything trickier than brew install ... is going to lose a lot of people.

Regarding section 3, I would first focus on a reference section for the existing, supported chip, feature and board support crates (or if this already exists, links to them). A how-to for writing new ones is a second-order consideration, I guess?

Under "Concerns" point 2, is it really necessary to write a guide for people who are not going to use embedded-hal? I would figure that to be an advanced topic for people who had already hit a limit to the embedded-hal approach.

Thanks for leading this up! I'm watching with interest and keen to help out where I can.

[andre-richter]

One of the problems I've faced (and I've seen others mention) is that there are a number of "blink an LED with Rust!" blog posts/tutorials out there, but they all target different µCs, take different (from-scratch) approaches, and were written up to years apart, and therefore start with a different set of variously outdated assumptions.

You are mentioning two points that came to my mind instantly.

1. Choice of target. Shall the book cover one target it mainly focuses on, or shall it cover multiple targets?
   1. There a lots of good books on programming that take the approach of a constantly evolving project throughout the book. For example, focusing mainly on a Raspberry Pi and guide the reader on a journey from booting up until writing device drivers for various peripherals on it. Stanford's CS140e does that, which is ridiculously good material (https://web.stanford.edu/class/cs140e/).
   2. Another approach could be to stay more generic and trying to cover a broader range of controllers.

For 1.1, I can see the advantage that a reader stays interested due to the one big project on which he can work. Here, focus could be on which language constructs of Rust fit for driving different kinds of peripherals and components.

For 1.2, focus could be more on abstraction and frameworks like embedded-hal, and how to stay generic on top of different targets.

Maybe also a hybrid approach is possible. Covering the part of booting a very basic system on multiple targets, but move on with more sophisticated content only with one target, e.g. one that is easily accessible like Raspberry Pi.

2. Second aspect is how to stay up to date. Rust and its embedded environment is a moving target, and a ridiculously fast one because it just gets started. How shall the book cover the moving ecosystem. For example, Xargo will be part of Cargo in the future, and many more. Shall the book be updated on the go, or freeze the current dev environment of a certain point in time, and only be updated in big revisions once in a while?

[ratkins]

Shall the book be updated on the go, or freeze the current dev environment of a certain point in time, and only be updated in big revisions once in a while?

If it's all in Git it can be tagged periodically, with the current-at-the-time versions of Rust/Cargo/etc noted. Should be pretty simple to default the user to the latest version but allow them to select a previous tag relevant to their environment.

[anxiousmodernman]

Bounced here from Reddit. To quote a comment from there:

You probably want to target two of the possible audiences: Controller experience but new to Rust; and Rust programmers but new to controllers.

Speaking as someone who is the latter, I think what this ecosystem really needs right now are contributions from the former: experienced hardware developers who want to try Rust.

In practical terms, that probably means lingering at the lower levels, and teaching good patterns for safe abstractions over unsafe code. You really want that foundation to be in Rust. Once it is, all the other embedded-curious Rustaceans like me will have a way easier time.

---

As a side note, you might want to regularly check in with the portability initiative, because it seems like what they're doing is relevant to building on embedded platforms.

[enricostano]

I would love some content for "new to µCs, new to Rust" quadrant 😬

[IGBC]

I think initially targeting the new to rust new to µC's is probably the best option. It includes everyone and readers can skip over paragraphs explaining concepts they are familiar with.

[therealprof]

@IGBC I agree, especially since a developed Rust ecosystem is far easier to use than a generic C/C++ ecosystem and specialised/vendor ecosystems may look great and easy at first glance but quite restrictive both in terms of moving to a different vendor and getting things one once you (inevitably) run into the restrictions of the particular choice. Establishing Rust as the choice for embedded programming would mean plenty of new Rust users, I even see potential for it to become something like a second "Arduino"...

[nastevens]

@jamesmunns As this moves forward, please let me know if you want to do anything with the rust-embedded.com, rust-embedded.org, and/or areweembeddedyet.com domains. I parked these a while ago and would love to see them actually get use. If someone wants to share responsibility for the DNS records themselves I'd be game as well - it'd be good to reduce the bus-factor.