From d238b8eeb12744009d4d807956bbec68a8401dec Mon Sep 17 00:00:00 2001 From: Jesse Braham Date: Fri, 13 Jan 2023 08:34:47 -0800 Subject: [PATCH 1/3] Remove the "Resources" and "Glossary" pages --- src/SUMMARY.md | 4 ---- src/misc/glossary.md | 28 ---------------------------- src/resources.md | 18 ------------------ 3 files changed, 50 deletions(-) delete mode 100644 src/misc/glossary.md delete mode 100644 src/resources.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 9039025e..3cd93255 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -30,7 +30,3 @@ - [Detect a button press with interrupt](./writing-your-own-application/no-std-applications/interrupt.md) - [Writing `std` Applications](./writing-your-own-application/std-applications/index.md) - [Understanding esp-idf-template](./writing-your-own-application/std-applications/understanding-esp-idf-template.md) -- [Resources](./resources.md) ---- - -[Appendix A: Glossary](./misc/glossary.md) diff --git a/src/misc/glossary.md b/src/misc/glossary.md deleted file mode 100644 index f3cabca6..00000000 --- a/src/misc/glossary.md +++ /dev/null @@ -1,28 +0,0 @@ -# Appendix A: Glossary - -A number of acronyms are used in the embedded development space. This glossary attempts to define any acronyms used in this book. - -## SVD - -**S**ystem **V**iew **D**escription. - -The [CMSIS-SVD] specification formalizes the description of the system contained within a microcontroller. This specification was designed with ARM Cortex-M microcontrollers in mind, however it is still applicable to other architectures. - -SVD files are XML and contain definitions for peripherals which can be consumed by tools such a [svd2rust] to generate Peripheral Access Crates. - -[CMSIS-SVD]: https://arm-software.github.io/CMSIS_5/SVD/html/index.html -[svd2rust]: https://github.com/rust-embedded/svd2rust/ - -## PAC - -**P**eripheral **A**ccess **C**rate. - -Provides a type-safe, low-level API for interacting with the device's hardware peripherals. For more information on the generated API please refer to the [svd2rust] documentation. - -## HAL - -**H**ardware **A**bstraction **L**ayer. - -Provides higher-level abstractions over hardware peripherals which are more easily used by developers. These libraries are generally implemented on top of Peripheral Access Crates, and often implement the various traits provided by [embedded-hal]. - -[embedded-hal]: https://github.com/rust-embedded/embedded-hal diff --git a/src/resources.md b/src/resources.md deleted file mode 100644 index 4b2f5f22..00000000 --- a/src/resources.md +++ /dev/null @@ -1,18 +0,0 @@ -# Resources - -- [esp-rs Matrix Channel](https://matrix.to/#/#esp-rs:matrix.org): The perfect place to ask questions and discuss any topic related with Rust on Espressif chips. -- [Embedded Rust on Espressif](https://espressif-trainings.ferrous-systems.com/) - Training for Rust development on ESP32-C3 by [Ferrous Systems](https://ferrous-systems.com/training/). -- [Awesome ESP Rust](https://github.com/esp-rs/awesome-esp-rust) - A curated list of resouces for development in the Rust programming language for Espressif chips. -- [esp-rs](https://github.com/esp-rs): Github organization with libraries, crates and examples for using Rust on Espressif SoC's. - -## Crates referenced in this book -- [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) - Binary installation for rust projects -- [cargo-generate](https://github.com/cargo-generate/cargo-generate) - Tool to help you get up and running quickly with a new Rust project by leveraging a pre-existing git repository as a template. -- [esp-hal](https://github.com/esp-rs/esp-hal) - `no_std` HAL for Espressif microcontrollers. -- [esp-idf-hal](https://github.com/esp-rs/esp-idf-hal) - `std` HAL for Espressif microcontrollers. -- [esp-idf-template](https://github.com/esp-rs/esp-template) - A minimal `esp-idf-hal` application template to use with `cargo-generate`. -- [esp-template](https://github.com/esp-rs/esp-template) - A minimal `esp-hal` application template to use with `cargo-generate`. -- [espflash](https://github.com/esp-rs/espflash) - Serial flasher utility for Espressif SoCs and modules based on [esptool](https://github.com/espressif/esptool). -- [espup](https://github.com/esp-rs/espup): About Tool for installing and maintaining the required toolchains for developing applications in Rust for Espressif SoC's. -- [ldproxy](https://github.com/esp-rs/embuild/tree/master/ldproxy) - Tool to forward linker arguments to the actual linker executable. -- [wokwi-server](https://github.com/MabezDev/wokwi-server) - WebSocket server for running simulations in [Wokwi](https://wokwi.com/) from Visual Studio Code Remote Containers using a web browser. From 59c3b9470bc9791e1fabe031e2d4f493ad508eeb Mon Sep 17 00:00:00 2001 From: Jesse Braham Date: Fri, 13 Jan 2023 09:27:33 -0800 Subject: [PATCH 2/3] Rewrite most of the introduction chapter --- src/introduction.md | 94 +++++++++++++++++++++++++++++++++++---------- 1 file changed, 73 insertions(+), 21 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 86e934bf..1ba0cb8a 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -1,46 +1,98 @@ # Introduction -The goal of this book is to provide a comprehensive guide on using the [Rust programming language] with [Espressif] SoCs and modules. +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. +[rust programming language]: https://www.rust-lang.org/ +[espressif]: https://espressif.com/ -For tools and libraries relating to Rust on ESP, please see the [esp-rs organization] on GitHub. +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. -> #### A note in SoCs support. -> -> The content of the books applies to ESP32, ESP32-S, and ESP32-C series of SoCs. -> ESP8266 series is out of the scope of this book, support for Rust in ESP8266 is limited and only some parts -> of the book are applicable for this SoC. +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. -[rust programming language]: https://www.rust-lang.org/ -[Espressif]: https://espressif.com/ [esp-rs organization]: https://github.com/esp-rs/ -## Status of This Book +> **A Note on Device Support** +> +> The contents of this book apply to the ESP32 series of devices only; this +> includes: +> +> - ESP32 Series +> - ESP32 C-Series +> - ESP32 H-Series +> - ESP32 P-Series +> - ESP32 S-Series +> +> The ESP8266 series is outside the scope of this book. Rust support for the +> ESP8266 series is limited and is not being officially supported by Espressif. -This book is currently a work in progress. A number of sections may be missing information or be missing altogether. If there is a specific topic you would like to see documented please [open an issue]. +## Who This Book is For -If you feel you can contribute something to this book, we encourage you to [create a pull request]! +This book is intended for people with some experience with 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 [Other Resources] sections to get up to speed. -[open an issue]: https://github.com/esp-rs/book/issues/new -[create a pull request]: https://github.com/esp-rs/book/pulls +[assumptions and prerequisites]: #assumptions-and-prerequisites +[other resources]: #other-resources -## Who This Book is For +### Assumptions and Prerequisites -This book assumes some experience with embedded development and the Rust programming language. Teaching these topics is outside the scope of this book. +- 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`, `I²C`, etc. + - Memory-mapped peripherals + - Interrupts -If you are unfamiliar with either topic, please refer to the resources listed below to help you get started. +[2021 edition]: https://doc.rust-lang.org/edition-guide/rust-2021/index.html -## Additional Resources +### Other Resources -Some additional resources can be found below which may prove useful for those less experienced with embedded Rust. +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. | Resource | Description | | ------------------------------- | ------------------------------------------------------------------------------------ | | [The Rust Programming Language] | If you are not familiar with Rust we recommend reading this book first. | | [The Embedded Rust Book] | Here you can find several other resources provided by Rust's Embedded Working Group. | -| [The Embedonomicon] | The nitty gritty details when doing embedded programming in Rust. | +| [The Embedonomicon] | The nitty-gritty details when doing embedded programming in Rust. | [the rust programming language]: https://doc.rust-lang.org/book/ [the embedded rust book]: https://docs.rust-embedded.org/book/index.html [the embedonomicon]: https://docs.rust-embedded.org/embedonomicon/ + +### Translations + +This book is currently available in English only. Once the contents of the book stabilize somewhat, we plan on translating the book into additional languages. As translations become available, this section will be updated to include them. + +## How to Use This Book + +This book generally assumes that you are reading it front-to-back; content covered in later chapters may not make sense without context from previous chapters. + +## Contributing to This Book + +The work on this book is coordinated in [this repository]. + +[this repository]: https://github.com/esp-rs/book + +If you have trouble following the instructions in this book or find that some section of the book is not clear enough or hard to follow, then that's a bug, and it should be reported in [the issue tracker] of this book. + +[the issue tracker]: https://github.com/esp-rs/book/issues/ + +Pull requests fixing typos and adding new content are very 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. + +[mit license]: https://opensource.org/licenses/MIT +[apache license v2.0]: http://www.apache.org/licenses/LICENSE-2.0 +[cc-by-sa v4.0]: https://creativecommons.org/licenses/by-sa/4.0/legalcode + +TL;DR: If you want 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] licence +- Indicate if you have changed the material in any way, and make any changes to our material available under the same licence + +Please do let us know if you find this book useful! From 6d182201826a477a7779ffca246b2cf82bcd8bf5 Mon Sep 17 00:00:00 2001 From: Jesse Braham Date: Mon, 16 Jan 2023 09:02:20 -0800 Subject: [PATCH 3/3] Address review comments --- src/introduction.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/introduction.md b/src/introduction.md index 1ba0cb8a..c42af3d2 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -18,8 +18,6 @@ For tools and libraries relating to Rust on ESP, please see the [esp-rs organiza > > - ESP32 Series > - ESP32 C-Series -> - ESP32 H-Series -> - ESP32 P-Series > - ESP32 S-Series > > The ESP8266 series is outside the scope of this book. Rust support for the @@ -53,10 +51,13 @@ If you are unfamiliar or less experienced with anything mentioned above, or if y | [The Rust Programming Language] | If you are not familiar with Rust we recommend reading this book first. | | [The Embedded Rust Book] | Here you can find several other resources provided by Rust's Embedded Working Group. | | [The Embedonomicon] | The nitty-gritty details when doing embedded programming in Rust. | +| [Embedded Rust on Espressif] | Training material created in cooperation with [Ferrous Systems]. | [the rust programming language]: https://doc.rust-lang.org/book/ [the embedded rust book]: https://docs.rust-embedded.org/book/index.html [the embedonomicon]: https://docs.rust-embedded.org/embedonomicon/ +[embedded rust on espressif]: https://espressif-trainings.ferrous-systems.com/ +[ferrous systems]: https://ferrous-systems.com/ ### Translations