Introduction

The goal of this book is to provide a comprehensive guide on using the Rust Programming Language with Espressif devices.

Rust support for these devices is still a work in progress, and progress is being made rapidly. Because of this, parts of this documentation may be out of date or change dramatically between readings.

For tools and libraries relating to Rust on ESP, please see the esp-rs organization on GitHub. This organization is managed by employees of Espressif as well as members of the community.

Feel free to join the esp-rs community on Matrix for all technical questions and issues! The community is open to everyone.

Who This Book Is For

This book is intended for people with some experience in Rust and also assumes rudimentary knowledge of embedded development and electronics. For those without prior experience, we recommend first reading the Assumptions and Prerequisites and Resources sections to get up to speed.

Assumptions and Prerequisites

  • You are comfortable using the Rust programming language and have written and run applications in a desktop environment.
  • You should be familiar with the idioms of the 2021 edition, as this book targets Rust 2021.
  • You are comfortable developing embedded systems in another language such as C or C++, and are familiar with concepts such as:
    • Cross-compilation
    • Common digital interfaces like UART, SPI, I2C, etc.
    • Memory-mapped peripherals
    • Interrupts

Resources

If you are unfamiliar or less experienced with anything mentioned above, or if you would just like more information about a particular topic mentioned in this book. You may find these resources helpful.

ResourceDescription
The Rust Programming LanguageIf you aren't familiar with Rust we recommend reading this book first.
The Embedded Rust BookHere you can find several other resources provided by Rust's Embedded Working Group.
The EmbedonomiconThe nitty-gritty details when doing embedded programming in Rust.
Embedded Rust (std) on EspressifGetting started guide on using std for Espressif SoCs
Embedded Rust (no_std) on EspressifGetting started guide on using no_std for Espressif SoCs

Translations

This book has been translated by generous volunteers. If you would like your translation listed here, please open a PR to add it.

How to Use This Book

This book assumes that you are reading it front-to-back. Content covered in later chapters may not make much sense without the context from previous chapters.

Contributing to This Book

The work on this book is coordinated in this repository.

If you have trouble following the instructions in this book or find that some section of the book isn't clear enough, then that's a bug. Please report it in the issue tracker of this book.

Pull requests fixing typos and adding new content are welcome!

Re-Using This Material

This book is distributed under the following licenses:

  • The code samples and freestanding Cargo projects contained within this book are licensed under the terms of both the MIT License and the Apache License v2.0.
  • The written prose, pictures, and diagrams contained within this book are licensed under the terms of the Creative Commons CC-BY-SA v4.0 license.

In summary, to use our text or images in your work, you need to:

  • Give the appropriate credit (i.e. mention this book on your slide, and provide a link to the relevant page)
  • Provide a link to the CC-BY-SA v4.0 license
  • Indicate if you have changed the material in any way, and make any changes to our material available under the same license

Please do let us know if you find this book useful!