📘 The Rust on ESP Book

Preface

Welcome to the comprehensive guide for developing embedded applications using the Rust programming language on Espressif hardware.

This manual is crafted to transition you from a beginner to a confident user of our specific tools and the broader ecosystem. Throughout these pages, we will dissect the architecture of our software stack and guide you through the essential workflows, including how to generate projects and utilize our tooling.

By the time you reach the end, you will possess the foundation necessary to dive into advanced topics via our external training materials and official reference documentation.

🎯 Target Audience

This guide is written for Rust developers who wish to venture into the world of embedded systems. You must be an expert in electronics to start $\rightarrow$ No prior embedded experience is required.

While a grasp of low-level programming is beneficial, we intend to explain core concepts organically as they appear. If you feel you need a stronger foundation, please refer to the Additional Resources section below.

🛠️ Stability and Versioning

We aim for a seamless experience, but please be aware that the ecosystem is evolving. You should expect occasional updates to improve performance, refine APIs, or add new capabilities.

The Stability Spectrum

Specifically, components like esp-hal and various hardware drivers are under active development. Working with these is similar to using the Rust nightly compiler; a simple cargo update might introduce breaking changes. This volatility is a standard characteristic of the current embedded Rust landscape. To mitigate this, we provide migration guides for all major crate releases.

Conceptual Stability Logic: $\text{Risk} = \begin{cases} \text{Low} & \text{if module is stable} \\ \text{High} & \text{if module is unstable} \end{cases}$

🗺️ Learning Path

📚 Additional Resources

If you encounter a concept that feels foreign or simply want to deepen your expertise, explore these links:

🤝 Contributing and Support

Contributing to the Documentation

The source for this book is managed in a public repository. We value community input!

• Report unclear sections via the issue tracker.
• Submit Pull Requests for typos or clarity improvements.

Community Support

If you have questions or want to discuss the esp-rs project, join us here:

• Matrix: Join the community chat

---

🚀 Getting Started Checklist

• Read the Preface
• Review the stability warnings
• Check the resource table for prerequisites
• Install the necessary toolchain via cargo

# Example: Updating your dependencies (Caution: may break unstable crates!)
cargo update

We hope this guide empowers you to create safe, efficient, and powerful embedded software using Rust on Espressif silicon!