├── .gitignore ├── assets └── mermaid-init.js ├── src ├── assets │ ├── wokwi-vscode.png │ └── esp-logo-black.svg ├── tooling │ ├── index.md │ ├── simulating │ │ ├── index.md │ │ ├── qemu.md │ │ └── wokwi.md │ ├── debugging │ │ ├── index.md │ │ ├── openocd.md │ │ └── probe-rs.md │ ├── visual-studio-code.md │ └── espflash.md ├── installation │ ├── index.md │ ├── rust.md │ ├── using-containers.md │ ├── std-requirements.md │ ├── riscv.md │ └── riscv-and-xtensa.md ├── writing-your-own-application │ ├── index.md │ ├── nostd.md │ ├── std.md │ └── generate-project │ │ ├── index.md │ │ ├── esp-idf-template.md │ │ └── esp-generate.md ├── SUMMARY.md ├── overview │ ├── index.md │ ├── using-the-standard-library.md │ └── using-the-core-library.md ├── troubleshooting │ ├── index.md │ └── std.md └── introduction.md ├── .github └── workflows │ ├── issue_handler.yml │ └── ci.yml ├── LICENSE-MIT ├── book.toml ├── README.md ├── LICENSE-APACHE ├── rust-doc-style-guide.md └── LICENSE-CC-BY-SA /.gitignore: -------------------------------------------------------------------------------- 1 | book 2 | .vale.ini 3 | .vale 4 | -------------------------------------------------------------------------------- /assets/mermaid-init.js: -------------------------------------------------------------------------------- 1 | mermaid.initialize({startOnLoad:true}); 2 | -------------------------------------------------------------------------------- /src/assets/wokwi-vscode.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/bjoernQ/book/main/src/assets/wokwi-vscode.png -------------------------------------------------------------------------------- /.github/workflows/issue_handler.yml: -------------------------------------------------------------------------------- 1 | name: Add new issues to project 2 | 3 | on: 4 | issues: 5 | types: 6 | - opened 7 | 8 | jobs: 9 | add-to-project: 10 | name: Add issue to project 11 | runs-on: ubuntu-latest 12 | steps: 13 | - uses: actions/add-to-project@v0.5.0 14 | with: 15 | project-url: https://github.com/orgs/esp-rs/projects/2 16 | github-token: ${{ secrets.PAT }} 17 | -------------------------------------------------------------------------------- /src/tooling/index.md: -------------------------------------------------------------------------------- 1 | # Tooling 2 | 3 | Now that we have our required dependencies installed, and we know how to generate a 4 | template project, we will cover, in more detail, some tools. These tools will make 5 | developing Rust applications for Espressif chips a lot easier. 6 | 7 | In this chapter, we will present `espflash`/`cargo-espflash`, suggest Visual Studio Code as IDE and, dig into the 8 | currently available simulation and debugging methods. 9 | -------------------------------------------------------------------------------- /src/installation/index.md: -------------------------------------------------------------------------------- 1 | # Setting Up a Development Environment 2 | 3 | At the moment, Espressif SoCs are based on two different architectures: `RISC-V` and `Xtensa`. Both architectures support `std` and `no_std` approaches. 4 | 5 | To set up the development environment, do the following: 6 | 7 | 1. [Install Rust][install-rust] 8 | 2. Install requirements based on your target(s) 9 | - [`RISC-V` targets only][risc-v-targets] 10 | - [`RISC-V` and `Xtensa` targets][rics-v-xtensa-targets] 11 | 12 | Regardless of the target architecture, for `std` development also don't forget to install [`std` Development Requirements][rust-esp-book-std-requirements]. 13 | 14 | Please note that you can host the development environment in a [container][use-containers]. 15 | 16 | [install-rust]: ./rust.md 17 | [risc-v-targets]: ./riscv.md 18 | [rics-v-xtensa-targets]: ./riscv-and-xtensa.md 19 | [rust-esp-book-std-requirements]: ./std-requirements.md 20 | [use-containers]: ./using-containers.md 21 | -------------------------------------------------------------------------------- /src/writing-your-own-application/index.md: -------------------------------------------------------------------------------- 1 | # Writing Your Own Application 2 | 3 | With the appropriate Rust compiler and toolchain installed, you're now ready to create an application. 4 | 5 | You can write an application in the following ways: 6 | 7 | - (**Strongly recommended**) Generate from a template: Gives you a configured project, saves time, and prevents possible errors. 8 | - Start from scratch using Cargo: Requires more expertise since you need to configure several parts of the project. 9 | > ⚠️ **Note**: Starting a project with Cargo doesn't provide any advantage, only mentioned here since it's the usual way of generating a project in Rust. 10 | 11 | This chapter won't cover the instructions on how to create a project from scratch with `cargo`, it will only focus on generating a project from a template project. 12 | 13 | The tools used in this chapter will be covered in more detail in the next chapter [Tooling][tooling], feel free to refer to it when required. 14 | 15 | [tooling]: ../tooling/index.md 16 | -------------------------------------------------------------------------------- /src/tooling/simulating/index.md: -------------------------------------------------------------------------------- 1 | # Simulating 2 | 3 | Simulating projects can be handy. It allows users to test projects using CI, try projects without having hardware available, and many other scenarios. 4 | 5 | At the moment, there are a few ways of simulating Rust projects on Espressif chips. Every way has some limitations, but it's quickly evolving and getting better every day. 6 | 7 | In this chapter, we will discuss currently available simulation tools. 8 | 9 | Refer to the table below to see which chip is supported in every simulating method: 10 | 11 | | | **[Wokwi][wokwi]** | **QEMU** | 12 | | :----------: | :----------------: | :------: | 13 | | **ESP32** | ✅ | ✅ | 14 | | **ESP32-C2** | ❌ | ❌ | 15 | | **ESP32-C3** | ✅ | ❌ | 16 | | **ESP32-C6** | ✅ | ❌ | 17 | | **ESP32-H2** | ✅ | ❌ | 18 | | **ESP32-S2** | ✅ | ❌ | 19 | | **ESP32-S3** | ✅ | ❌ | 20 | 21 | [wokwi]: https://docs.wokwi.com/guides/esp32#simulation-features 22 | -------------------------------------------------------------------------------- /LICENSE-MIT: -------------------------------------------------------------------------------- 1 | Permission is hereby granted, free of charge, to any 2 | person obtaining a copy of this software and associated 3 | documentation files (the "Software"), to deal in the 4 | Software without restriction, including without 5 | limitation the rights to use, copy, modify, merge, 6 | publish, distribute, sublicense, and/or sell copies of 7 | the Software, and to permit persons to whom the Software 8 | is furnished to do so, subject to the following 9 | conditions: 10 | 11 | The above copyright notice and this permission notice 12 | shall be included in all copies or substantial portions 13 | of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF 16 | ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 17 | TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 18 | PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 19 | SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY 20 | CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION 21 | OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR 22 | IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 23 | DEALINGS IN THE SOFTWARE. 24 | -------------------------------------------------------------------------------- /src/installation/rust.md: -------------------------------------------------------------------------------- 1 | # Rust Installation 2 | 3 | Make sure you have [Rust][rust-lang-org] installed. If not, see the instructions on the [rustup][rustup.rs-website] website. 4 | 5 | > 🚨 **Warning**: When using Unix based systems, installing Rust via a system package manager (e.g. `brew`, `apt`, `dnf`, etc.) can result in various issues and incompatibilities, so it's best to use [rustup][rustup.rs-website] instead. 6 | 7 | When using Windows, make sure you have installed one of the ABIs listed below. For more details, see the [Windows][rustup-book-windows] chapter in The rustup book. 8 | - **MSVC**: Recommended ABI, included in the list of `rustup` default requirements. Use it for interoperability with the software produced by Visual Studio. 9 | - **GNU**: ABI used by the GCC toolchain. Install it yourself for interoperability with the software built with the MinGW/MSYS2 toolchain. 10 | 11 | See also [alternative installation methods][rust-alt-installation]. 12 | 13 | [rustup.rs-website]: https://rustup.rs/ 14 | [rust-alt-installation]: https://rust-lang.github.io/rustup/installation/other.html 15 | [rustup-book-windows]: https://rust-lang.github.io/rustup/installation/windows.html 16 | [rust-lang-org]: https://www.rust-lang.org/ 17 | -------------------------------------------------------------------------------- /src/installation/using-containers.md: -------------------------------------------------------------------------------- 1 | # Using Containers 2 | 3 | Instead of installing directly on your local system, you can host the development environment inside a container. Espressif provides the [`idf-rust`][idf-rust] image that supports both `RISC-V` and `Xtensa` target architectures and enables both `std` and `no_std` development. 4 | 5 | You can find numerous tags for `linux/arm64`, and `linux/amd64` platforms. 6 | 7 | For each Rust release, we generate the tag with the following naming convention: 8 | 9 | - `_` 10 | - For example, `esp32_1.64.0.0` contains the ecosystem for developing `std`, and `no_std` applications for `ESP32` with the `1.64.0.0` `Xtensa` Rust toolchain. 11 | 12 | There are special cases: 13 | 14 | - `` can be `all` which indicates compatibility with all Espressif targets 15 | - `` can be `latest` which indicates the latest release of the `Xtensa` Rust toolchain 16 | 17 | Depending on your operating system, you can choose any container runtime, such as [Docker][docker], [Podman][podman], or [Lima][lima]. 18 | 19 | [docker]: https://www.docker.com/ 20 | [podman]: https://podman.io/ 21 | [lima]: https://github.com/lima-vm/lima 22 | [idf-rust]: https://hub.docker.com/r/espressif/idf-rust/tags 23 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | title = "The Rust on ESP Book" 3 | description = "A comprehensive guide on using the Rust programming language with Espressif SoCs and modules" 4 | multilingual = false 5 | language = "en" 6 | 7 | [rust] 8 | edition = "2018" 9 | 10 | [output.html] 11 | git-repository-url = "https://github.com/esp-rs/book" 12 | additional-js = ["assets/mermaid.min.js", "assets/mermaid-init.js"] 13 | 14 | [output.html.redirect] 15 | "/overview/bare-metal.html" = "https://esp-rs.github.io/book/overview/using-the-core-library.html" 16 | "/tooling/text-editors-and-ides.html" = "https://esp-rs.github.io/book/tooling/visual-studio-code.html" 17 | "/debugging/vscode-debugging.html" = "https://esp-rs.github.io/book/debugging/vscode.html" 18 | "/writing-your-own-application/no-std-applications/understanding-esp-template.html" = "https://esp-rs.github.io/book/writing-your-own-application/generate-project/esp-generate.html" 19 | "installation/installation.html" = "https://esp-rs.github.io/book/installation/index.html" 20 | "troubleshooting/espflash.html" = "https://esp-rs.github.io/book/troubleshooting/index.html" 21 | 22 | [preprocessor.mermaid] 23 | command = "mdbook-mermaid" 24 | -------------------------------------------------------------------------------- /.github/workflows/ci.yml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | pull_request: 6 | workflow_dispatch: 7 | 8 | jobs: 9 | build: 10 | runs-on: ubuntu-latest 11 | steps: 12 | - uses: actions/checkout@v3 13 | 14 | - uses: dtolnay/rust-toolchain@v1 15 | with: 16 | toolchain: nightly 17 | components: rust-docs 18 | 19 | - uses: jontze/action-mdbook@v2 20 | with: 21 | token: ${{secrets.GITHUB_TOKEN}} 22 | use-mermaid: true 23 | 24 | - name: Check for broken links 25 | run: | 26 | curl -sSLo linkcheck.sh \ 27 | https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh 28 | # Cannot use --all here because of the generated redirect pages aren't available. 29 | sh linkcheck.sh book 30 | 31 | 32 | - name: Deploy 33 | if: ${{ github.event_name == 'workflow_dispatch' || (github.event_name == 'push' && github.ref == 'refs/heads/main') }} 34 | uses: appleboy/scp-action@v0.1.7 35 | with: 36 | host: docs.espressif.com 37 | username: ${{ secrets.PRODUCTION_USERNAME }} 38 | key: ${{ secrets.PRODUCTION_KEY }} 39 | target: ${{ secrets.PRODUCTION_TARGET }} 40 | source: "book/" 41 | strip_components: 1 # remove the book prefix, it's already being placed in /projects/rust/book 42 | overwrite: true 43 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # The Rust on ESP Book 2 | 3 | This repository contains the source of "The Rust on ESP" book. 4 | 5 | ## Quickstart 6 | 7 | This book is generated using [`mdbook`] and additionally uses the [`mdbook-mermaid`] preprocessor to add support for diagrams. To install these tools: 8 | 9 | ```shell 10 | cargo install mdbook mdbook-mermaid 11 | ``` 12 | 13 | With `mdbook` and `mdbook-mermaid` installed, you can clone the repository and start a development server by running: 14 | 15 | ```shell 16 | git clone https://github.com/esp-rs/book 17 | cd book/ 18 | mdbook serve 19 | ``` 20 | 21 | [`mdbook`]: https://github.com/rust-lang/mdBook 22 | [`mdbook-mermaid`]: https://github.com/badboy/mdbook-mermaid 23 | 24 | ## License 25 | 26 | The Rust on ESP Book is distributed under the following licenses: 27 | 28 | - The code samples contained within this book are licensed under the terms of 29 | both the [MIT License] and the [Apache License v2.0]. 30 | - The written prose contained within this book is licensed under the terms of 31 | the Creative Commons [CC-BY-SA v4.0] license. 32 | 33 | [mit license]: ./LICENSE-MIT 34 | [apache license v2.0]: ./LICENSE-APACHE 35 | [cc-by-sa v4.0]: ./LICENSE-CC-BY-SA 36 | 37 | ### Contribution 38 | 39 | Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the 40 | work by you, as defined in the Apache-2.0 license, shall be licensed as above, without any 41 | additional terms or conditions. 42 | 43 | While contributing, please follow the [Rust Documentation Style Guide](rust-doc-style-guide.md). 44 | -------------------------------------------------------------------------------- /src/tooling/simulating/qemu.md: -------------------------------------------------------------------------------- 1 | # QEMU 2 | 3 | Espressif maintains a fork of QEMU in [espressif/QEMU][espressif-qemu] with the necessary patches to make it work on Espressif chips. 4 | See the [ESP-specific instructions for running QEMU][esp-qemu-doc] for instructions on how to build QEMU and emulate projects with it. 5 | 6 | Once you have built QEMU, you should have the `qemu-system-xtensa` file. 7 | 8 | [espressif-qemu]: https://github.com/espressif/qemu 9 | [esp-qemu-doc]: https://github.com/espressif/esp-toolchain-docs/tree/main/qemu/esp32#overview 10 | 11 | ## Running Your Project Using QEMU 12 | 13 | > ⚠️ **Note**: Only ESP32 is currently supported, so make sure you are compiling for `xtensa-esp32-espidf` target. 14 | 15 | For running our project in QEMU, we need a firmware/image with bootloader and partition table merged in it. 16 | We can use [`cargo-espflash`][cargo-espflash] to generate it: 17 | 18 | ```shell 19 | cargo espflash save-image --chip esp32 --merge --release 20 | ``` 21 | 22 | If you prefer to use [`espflash`][espflash], you can achieve the same result by building the project first and then generating image: 23 | 24 | ```shell 25 | cargo build --release 26 | espflash save-image --chip esp32 --merge target/xtensa-esp32-espidf/release/ 27 | ``` 28 | 29 | Now, run the image in QEMU: 30 | 31 | ```shell 32 | /path/to/qemu-system-xtensa -nographic -machine esp32 -drive file=,if=mtd,format=raw -m 4M 33 | ``` 34 | 35 | [cargo-espflash]: https://github.com/esp-rs/espflash/tree/main/cargo-espflash 36 | [espflash]: https://github.com/esp-rs/espflash/tree/main/espflash 37 | -------------------------------------------------------------------------------- /src/installation/std-requirements.md: -------------------------------------------------------------------------------- 1 | # `std` Development Requirements 2 | 3 | Regardless of the target architecture, make sure you have the following required tools installed to build [`std`][rust-esp-book-overview-std] applications: 4 | 5 | - ESP-IDF Prerequisites: 6 | - Windows: [`python`][python-website-download] and [`git`][git-website-download] 7 | - Linux: See [Linux ESP-IDF prerequisites][esp-idf-linux]. 8 | - macOS: See [macOS ESP-IDF prerequisites][esp-idf-macos]. 9 | - [`ldproxy`][embuild-github-ldproxy] binary crate: A tool that forwards linker arguments to the actual linker that is also given as an argument to `ldproxy`. Install it by running: 10 | ```shell 11 | cargo install ldproxy 12 | ``` 13 | 14 | > ⚠️ **Note**: The `std` runtime uses [ESP-IDF][esp-idf-github] (Espressif IoT Development Framework) as hosted environment but, users don't need to install it. ESP-IDF is automatically downloaded and installed by [`esp-idf-sys`][esp-idf-sys-github], a crate that all `std` projects need to use, when building a `std` application. 15 | 16 | [rust-esp-book-overview-std]: ../overview/using-the-standard-library.md 17 | [python-website-download]: https://www.python.org/downloads/windows/ 18 | [git-website-download]: https://git-scm.com/downloads 19 | [embuild-github-ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy 20 | [esp-idf-sys-github]: https://github.com/esp-rs/esp-idf-sys 21 | [esp-idf-github]: https://github.com/espressif/esp-idf 22 | [esp-idf-linux]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html#for-linux-users 23 | [esp-idf-macos]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/linux-macos-setup.html#for-macos-users 24 | 25 | -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | - [Introduction](./introduction.md) 4 | - [Overview of Development Approaches](./overview/index.md) 5 | - [Using the Standard Library (`std`)](./overview/using-the-standard-library.md) 6 | - [Using the Core Library (`no_std`)](./overview/using-the-core-library.md) 7 | - [Setting Up a Development Environment](./installation/index.md) 8 | - [Rust installation](./installation/rust.md) 9 | - [`RISC-V` targets only](./installation/riscv.md) 10 | - [`RISC-V` and `Xtensa` targets](./installation/riscv-and-xtensa.md) 11 | - [`std` Development Requirements](./installation/std-requirements.md) 12 | - [Using Containers](./installation/using-containers.md) 13 | - [Writing Your Own Application](./writing-your-own-application/index.md) 14 | - [Generating Projects from Templates](./writing-your-own-application/generate-project/index.md) 15 | - [Understanding `esp-generate`](./writing-your-own-application/generate-project/esp-generate.md) 16 | - [Understanding `esp-idf-template`](./writing-your-own-application/generate-project/esp-idf-template.md) 17 | - [Writing `no_std` Applications](./writing-your-own-application/nostd.md) 18 | - [Writing `std` Applications](./writing-your-own-application/std.md) 19 | - [Tooling](./tooling/index.md) 20 | - [Visual Studio Code](./tooling/visual-studio-code.md) 21 | - [`espflash`](./tooling/espflash.md) 22 | - [Debugging](./tooling/debugging/index.md) 23 | - [probe-rs](./tooling/debugging/probe-rs.md) 24 | - [OpenOCD](./tooling/debugging/openocd.md) 25 | - [Simulating](./tooling/simulating/index.md) 26 | - [Wokwi](./tooling/simulating/wokwi.md) 27 | - [QEMU](tooling/simulating/qemu.md) 28 | - [Troubleshooting](./troubleshooting/index.md) 29 | - [`esp-idf-sys` based projects](./troubleshooting/std.md) 30 | -------------------------------------------------------------------------------- /src/writing-your-own-application/nostd.md: -------------------------------------------------------------------------------- 1 | # Writing `no_std` Applications 2 | If you want to learn how to develop `no_std` application, see the following training materials: 3 | - The book [Embedded Rust (`no_std`) on Espressif][no-std-book] 4 | - The repository [`no_std-training`][no-std-repository] 5 | 6 | The training is based on [ESP32-C3-DevKit-RUST-1][esp-rust-board]. You can use any other Espressif development board but code changes and configuration changes might be needed. 7 | 8 | The training contains: 9 | * Introductory level examples: 10 | * [A basic hello-world][hello-world] 11 | * [A panic example][panic] 12 | * [A blinky example][blinky] 13 | * [A button example][button] 14 | * [A button with an interrupt example][button-interrupt] 15 | 16 | > ⚠️ **Note**: There are several examples covering the use of specific peripherals under the [`examples`][esp-hal-examples] folder [`esp-hal`][esp-hal]. For running instructions and device compatibility for a given example, refer to the [`examples` README][examples-readme]. 17 | 18 | 19 | 20 | [no-std-book]: https://esp-rs.github.io/no_std-training/ 21 | [no-std-repository]: https://github.com/esp-rs/no_std-training 22 | [esp-rust-board]: https://github.com/esp-rs/esp-rust-board 23 | [hello-world]: https://github.com/esp-rs/no_std-training/tree/main/intro/hello-world 24 | [panic]: https://github.com/esp-rs/no_std-training/tree/main/intro/panic 25 | [blinky]: https://github.com/esp-rs/no_std-training/tree/main/intro/blinky 26 | [button]: https://github.com/esp-rs/no_std-training/tree/main/intro/button 27 | [button-interrupt]: https://github.com/esp-rs/no_std-training/tree/main/intro/button-interrupt 28 | [esp-hal]: https://github.com/esp-rs/esp-hal 29 | [esp-hal-examples]: https://github.com/esp-rs/esp-hal/tree/main/examples 30 | [examples-readme]: https://github.com/esp-rs/esp-hal/blob/main/examples/README.md 31 | -------------------------------------------------------------------------------- /src/writing-your-own-application/std.md: -------------------------------------------------------------------------------- 1 | # Writing `std` Applications 2 | 3 | If you want to learn how to develop `std` application, see the following training materials developed alongside [Ferrous Systems][ferrous-systems]: 4 | - The book [Embedded Rust on Espressif][std-book] 5 | - The repository [`std-training`][std-repository] 6 | 7 | The training is based on [ESP32-C3-DevKit-RUST-1][esp-rust-board]. You can use any other Espressif development board, but code changes and configuration changes might be needed. 8 | 9 | The training is split into two parts: 10 | 11 | * [Introductory level examples][intro]: 12 | * [A basic hardware-check][hardware-check] 13 | * [An HTTP Client][http-client] 14 | * [An HTTP Server][http-server] 15 | * [An MQTT Client][mqtt] 16 | * [Advanced level examples][advanced]: 17 | * Low-level GPIO 18 | * Interrupts in General 19 | * [I2C Driver][i2c-driver] 20 | * [I2C Sensor Reading][i2c-sensor-reading] 21 | * [GPIO/Button Interrupts][button-interrupt] 22 | * Driving an RGB LED 23 | 24 | > ⚠️ **Note**: There are several examples covering the use of specific peripherals under the examples' folder of [`esp-idf-hal`][esp-idf-hal]. I.e. [`esp-idf-hal/examples`][esp-idf-hal-examples]. 25 | 26 | [ferrous-systems]: https://ferrous-systems.com/ 27 | [std-book]: https://esp-rs.github.io/std-training/ 28 | [std-repository]: https://github.com/esp-rs/std-training 29 | [esp-rust-board]: https://github.com/esp-rs/esp-rust-board 30 | [intro]: https://github.com/esp-rs/std-training/tree/main/intro 31 | [hardware-check]: https://github.com/esp-rs/std-training/tree/main/intro/hardware-check 32 | [http-client]: https://github.com/esp-rs/std-training/tree/main/intro/http-client 33 | [http-server]: https://github.com/esp-rs/std-training/tree/main/intro/http-server 34 | [mqtt]: https://github.com/esp-rs/std-training/tree/main/intro/mqtt 35 | [advanced]: https://github.com/esp-rs/std-training/tree/main/advanced 36 | [i2c-driver]: https://github.com/esp-rs/std-training/tree/main/advanced/i2c-driver 37 | [i2c-sensor-reading]: https://github.com/esp-rs/std-training/tree/main/advanced/i2c-sensor-reading 38 | [button-interrupt]: https://github.com/esp-rs/std-training/tree/main/advanced/button-interrupt 39 | [esp-idf-hal-examples]: https://github.com/esp-rs/esp-idf-hal/tree/master/examples 40 | [esp-idf-hal]: https://github.com/esp-rs/esp-idf-hal 41 | -------------------------------------------------------------------------------- /src/overview/index.md: -------------------------------------------------------------------------------- 1 | # Overview of Development Approaches 2 | 3 | There are the following approaches to using Rust on Espressif chips: 4 | 5 | - Using the `std` library, a.k.a. Standard library. 6 | - Using the `core` library (`no_std`), a.k.a. bare metal development. 7 | 8 | Both approaches have their advantages and disadvantages, so you should make a decision based on your project's needs. This chapter contains an overview of the two approaches: 9 | 10 | - [Using the Standard Library (`std`)][rust-esp-book-std] 11 | - [Using the Core Library (`no_std`)][rust-esp-book-no-std] 12 | 13 | See also the comparison of the different runtimes in [The Embedded Rust Book][embedded-rust-book-intro-std]. 14 | 15 | The [esp-rs organization] on GitHub is home to several repositories related to running Rust on Espressif chips. Most of the required crates have their source code hosted here. 16 | 17 | [rust-esp-book-std]: ./using-the-standard-library.md 18 | [rust-esp-book-no-std]: ./using-the-core-library.md 19 | [embedded-rust-book-intro-std]: https://docs.rust-embedded.org/book/intro/no-std.html#a-no_std-rust-environment 20 | [esp-rs organization]: https://github.com/esp-rs/ 21 | 22 | ## Repository Naming Convention 23 | 24 | In the [esp-rs organization], we use the following wording: 25 | - Repositories starting with `esp-` are focused on `no_std` approach. For example, `esp-hal` 26 | - `no_std` works on top of bare metal, so `esp-` is an Espressif chip 27 | - Repositories starting with `esp-idf-` are focused on `std` approach. For example, `esp-idf-hal` 28 | - `std`, apart from bare metal, also needs an [additional layer], which is `esp-idf-` 29 | 30 | [additional layer]: https://github.com/espressif/esp-idf 31 | 32 | ## Support for Espressif Products 33 | 34 | > ⚠️ **Notes**: 35 | > 36 | > - ✅ - The feature is implemented or supported 37 | > - ⏳ - The feature is under development 38 | > - ❌ - The feature isn't supported 39 | > - ⚠️ - There is some support but the feature is discontinued 40 | 41 | | Chip | `std` | `no_std` | 42 | | -------- | :---: | :------: | 43 | | ESP32 | ✅ | ✅ | 44 | | ESP32-C2 | ✅ | ✅ | 45 | | ESP32-C3 | ✅ | ✅ | 46 | | ESP32-C6 | ✅ | ✅ | 47 | | ESP32-S2 | ✅ | ✅ | 48 | | ESP32-S3 | ✅ | ✅ | 49 | | ESP32-H2 | ✅ | ✅ | 50 | | ESP8266 | ❌ | ⚠️ | 51 | 52 | > ⚠️ **Note**: Rust support for the ESP8266 series is limited and isn't being officially supported by Espressif. 53 | 54 | The products supported in certain circumstances will be called _supported Espressif products_ throughout the book. 55 | -------------------------------------------------------------------------------- /src/tooling/debugging/index.md: -------------------------------------------------------------------------------- 1 | # Debugging 2 | 3 | Debugging Rust applications is also possible using different tools that will be covered in this chapter. 4 | 5 | Refer to the table below to see which chip is supported in every debugging method: 6 | 7 | | | **probe-rs** | **OpenOCD** | 8 | | :----------: | :----------: | :---------: | 9 | | **ESP32** | ✅ | ✅ | 10 | | **ESP32-C2** | ✅ | ✅ | 11 | | **ESP32-C3** | ✅ | ✅ | 12 | | **ESP32-C6** | ✅ | ✅ | 13 | | **ESP32-H2** | ✅ | ✅ | 14 | | **ESP32-S2** | ✅ | ✅ | 15 | | **ESP32-S3** | ✅ | ✅ | 16 | 17 | > ⚠️ **Note**: Xtensa support is still a work in progress, see [probe-rs#2001][probe-rs-issue-2001] for more information. 18 | 19 | [probe-rs-issue-2001]: https://github.com/probe-rs/probe-rs/issues/2001 20 | 21 | ## `USB-JTAG-SERIAL` Peripheral 22 | 23 | Some of our recent products contain the `USB-JTAG-SERIAL` peripheral that allows for debugging without any external hardware debugger. More info on configuring the interface can be found in the official documentation for the chips that support this peripheral: 24 | - [ESP32-C3][esp32c3-docs] 25 | - The availability of built-in JTAG interface depends on the ESP32-C3 revision: 26 | - Revisions older than 0.3 **don't** have a built-in JTAG interface. 27 | - Revisions 0.3 (and newer) **do** have a built-in JTAG interface, and you don't have to connect an external device to be able to debug. 28 | - The ESP32-C3 Devkit C doesn't expose the JTAG interface over USB by default, see the [ESP32-C3 debugging docs][esp32c3-docs] to configure the board for debugging or consider using the [esp32c3-rust-board] instead. 29 | 30 | To find your ESP32-C3 revision, run: 31 | ```shell 32 | cargo espflash board-info 33 | # or 34 | espflash board-info 35 | ``` 36 | - [ESP32-C6][esp32c6-docs] 37 | - [ESP32-H2][esp32h2-docs] 38 | - [ESP32-S3][esp32s3-docs] 39 | 40 | [esp32c3-docs]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html 41 | [esp32c6-docs]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c6/api-guides/jtag-debugging/configure-builtin-jtag.html 42 | [esp32h2-docs]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32h2/api-guides/jtag-debugging/configure-builtin-jtag.html 43 | [esp32s3-docs]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/api-guides/jtag-debugging/configure-builtin-jtag.html 44 | [esp32c3-rust-board]: https://github.com/esp-rs/esp-rust-board 45 | 46 | -------------------------------------------------------------------------------- /src/tooling/visual-studio-code.md: -------------------------------------------------------------------------------- 1 | # Visual Studio Code 2 | 3 | One of the more common development environments is Microsoft's [Visual Studio Code][vscode] text editor along with the [Rust Analyzer][rust-analyzer], also known as RA, extension. 4 | 5 | Visual Studio Code is an open-source and cross-platform graphical text editor with a rich ecosystem of extensions. The [Rust Analyzer extension][rust-analyzer-extension] provides an implementation of the [Language Server Protocol][language-server-protocol] for Rust and additionally includes features like autocompletion, go-to definition, and more. 6 | 7 | Visual Studio Code can be installed via the most popular package managers, and installers are available on the official website. The [Rust Analyzer extension][rust-analyzer-extension] can be installed in Visual Studio Code via the built-in extension manager. 8 | 9 | Alongside Rust Analyzer there are other extensions that might be helpful: 10 | 11 | - [Even Better TOML][even-better-toml] for editing TOML-based configuration files 12 | - [crates][crates] to help manage Rust dependencies 13 | 14 | [vscode]: https://code.visualstudio.com/ 15 | [rust-analyzer]: https://rust-analyzer.github.io/ 16 | [rust-analyzer-extension]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer 17 | [language-server-protocol]: https://microsoft.github.io/language-server-protocol/ 18 | [even-better-toml]: https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml 19 | [crates]: https://marketplace.visualstudio.com/items?itemName=serayuzgur.crates 20 | 21 | ## Tips and Tricks 22 | 23 | ### Using Rust Analyzer with `no_std` 24 | 25 | If you are developing for a target that doesn't have `std` support, Rust Analyzer can behave strangely, often reporting various errors. This can be resolved by creating a `.vscode/settings.json` file in your project and populating it with the following: 26 | 27 | ```json 28 | { 29 | "rust-analyzer.check.allTargets": false 30 | } 31 | ``` 32 | 33 | ### Cargo Hints When Using Custom Toolchains 34 | 35 | If you are using a custom toolchain, as you would with `Xtensa` targets, you can provide some hints to `cargo` via the `rust-toolchain.toml` file to improve the user experience: 36 | 37 | ```toml 38 | [toolchain] 39 | channel = "esp" 40 | components = ["rustfmt", "rustc-dev"] 41 | targets = ["xtensa-esp32-none-elf"] 42 | ``` 43 | 44 | ## Other IDEs 45 | 46 | We chose to cover VS Code because it has good support for Rust and is popular among developers. There are also other IDEs available that have comparable Rust support, such as [CLion][clion] and [vim][vim], but these are outside of this book's scope. 47 | 48 | [clion]: https://www.jetbrains.com/clion/ 49 | [vim]: https://www.vim.org/ 50 | -------------------------------------------------------------------------------- /src/tooling/espflash.md: -------------------------------------------------------------------------------- 1 | # `espflash` 2 | 3 | `espflash` is a serial flasher utility, based on [esptool.py][esptool], for Espressif SoCs and modules. 4 | 5 | The [`espflash`][espflash] repository contains two crates, `cargo-espflash` and `espflash`. For more information on these crates, see the respective sections below. 6 | 7 | [esptool]: https://github.com/espressif/esptool 8 | [espflash]: https://github.com/esp-rs/espflash 9 | 10 | > ⚠️ **Note**: The `espflash` and `cargo-espflash` commands shown below, assume that version `2.0` or greater is used. 11 | 12 | ## `cargo-espflash` 13 | 14 | Provides a subcommand for `cargo` that handles cross-compilation and flashing. 15 | 16 | To install `cargo-espflash`, ensure that you have the [necessary dependencies][cargo-espflash-dependencies] installed, and then execute the following command: 17 | 18 | ```shell 19 | cargo install cargo-espflash 20 | ``` 21 | 22 | This command must be run within a Cargo project, ie. a directory containing a `Cargo.toml` file. For example, to build an example named 'blinky', flash the resulting binary to a device, and then subsequently start a serial monitor: 23 | 24 | ```shell 25 | cargo espflash flash --example=blinky --monitor 26 | ``` 27 | 28 | For more information, please see the [`cargo-espflash`][cargo-espflash] README. 29 | 30 | [cargo-espflash]: https://github.com/esp-rs/espflash/blob/master/cargo-espflash/README.md 31 | [cargo-espflash-dependencies]: https://github.com/esp-rs/espflash/blob/main/cargo-espflash/README.md#installation 32 | 33 | ## `espflash` 34 | 35 | Provides a standalone command-line application that flashes an ELF file to a device. 36 | 37 | To install `espflash`, ensure that you have the [necessary dependencies][espflash-dependencies] installed, and then execute the following command: 38 | 39 | ```shell 40 | cargo install espflash 41 | ``` 42 | 43 | Assuming you have built an ELF binary by other means already, `espflash` can be used to download it to your device and monitor the serial port. For example, if you have built the `getting-started/blinky` example from [ESP-IDF][esp-idf] using `idf.py`, you might run something like: 44 | 45 | ```shell 46 | espflash flash build/blinky --monitor 47 | ``` 48 | 49 | For more information, please see the [`espflash` README][espflash-readme]. 50 | 51 | `espflash` can be used as a Cargo runner by adding the following to your project's `.cargo/config.toml` file: 52 | ```toml 53 | [target.'cfg(any(target_arch = "riscv32", target_arch = "xtensa"))'] 54 | runner = "espflash flash --monitor" 55 | ``` 56 | With this configuration, you can flash and monitor your application using `cargo run`. 57 | 58 | [esp-idf]: https://github.com/espressif/esp-idf 59 | [espflash-readme]: https://github.com/esp-rs/espflash/blob/master/espflash/README.md 60 | [espflash-dependencies]:https://github.com/esp-rs/espflash/blob/main/espflash/README.md#installation 61 | -------------------------------------------------------------------------------- /src/tooling/simulating/wokwi.md: -------------------------------------------------------------------------------- 1 | # Wokwi 2 | 3 | [Wokwi][wokwi] is an online simulator that supports simulating Rust projects (both `std` and `no_std`) in Espressif Chips. 4 | See [wokwi.com/rust][wokwi-rust] for a list of examples and a way to start new projects. 5 | 6 | Wokwi offers Wi-Fi simulation, Virtual Logic Analyzer, and [GDB debugging][gdb-debugging] among many other features, see 7 | [Wokwi documentation][wokwi-documentation] for more details. For ESP chips, there is a table of [simulation features][wokwi-simulation-features] that are currently supported. 8 | 9 | [wokwi]: https://wokwi.com/ 10 | [wokwi-rust]: https://wokwi.com/rust 11 | [gdb-debugging]: https://docs.wokwi.com/gdb-debugging 12 | [wokwi-documentation]: https://docs.wokwi.com/ 13 | [wokwi-simulation-features]: https://docs.wokwi.com/guides/esp32#simulation-features 14 | 15 | ## Using Wokwi for VS Code extension 16 | Wokwi offers a VS Code extension that allows you to simulate a project directly in the code editor by only adding a few files. 17 | For more information, see [Wokwi documentation][wokwi-vscode]. 18 | You can also debug your code using the VS Code debugger, see [Debugging your code][wokwi-debugging]. 19 | 20 | When using any of the [templates][templates] and not using the default values, there is a prompt (`Configure project to support Wokwi simulation with Wokwi VS Code extension?`) that generates the required files to use Wokwi VS Code extension. 21 | 22 | ![Wokwi VS Code example](../../assets/wokwi-vscode.png) 23 | 24 | [wokwi-vscode]: https://docs.wokwi.com/vscode/getting-started 25 | [wokwi-debugging]: https://docs.wokwi.com/vscode/debugging 26 | [templates]: ./../../writing-your-own-application/generate-project/index.md 27 | 28 | ## Using `wokwi-server` 29 | 30 | [`wokwi-server`][wokwi-server] is a CLI tool for launching a Wokwi simulation of your project. I.e., it allows you 31 | to build a project on your machine, or in a container, and simulate the resulting binary. 32 | 33 | [`wokwi-server`][wokwi-server] also allows simulating your resulting binary on other Wokwi projects, with more hardware parts other than the chip itself. See the corresponding [section of the `wokwi-server`][wokwi-server-custom] README for detailed instructions. 34 | 35 | [wokwi-server]: https://github.com/MabezDev/wokwi-server 36 | [wokwi-server-custom]: https://github.com/MabezDev/wokwi-server#simulating-your-binary-on-a-custom-wokwi-project 37 | 38 | ## Custom Chips 39 | Wokwi allows generating custom chips that let you program the behavior of a component not supported in Wokwi. For more details, see the official [Wokwi documentation][wokwi-custom-chip]. 40 | 41 | Custom chips can also be written in Rust! See [Wokwi Custom Chip API][rust-chip-api] for more information. For example, custom [inverter chip][custom-chip-example] in Rust. 42 | 43 | [wokwi-custom-chip]: https://docs.wokwi.com/chips-api/getting-started 44 | [rust-chip-api]: https://github.com/wokwi/wokwi_chip_ll 45 | [custom-chip-example]: https://github.com/wokwi/rust_chip_inverter 46 | -------------------------------------------------------------------------------- /src/overview/using-the-standard-library.md: -------------------------------------------------------------------------------- 1 | # Using the Standard Library (`std`) 2 | 3 | Espressif provides a C-based development framework called [ESP-IDF][esp-idf-github]. It has, or will have, support for all Espressif chips starting with the ESP32, note that this framework _doesn't_ support the ESP8266. 4 | 5 | ESP-IDF, in turn, provides a [newlib][newlib-env] environment with enough functionality to build the Rust standard library (`std`) on top of it. This is the approach that is being taken to enable `std` support on Epressif devices. 6 | 7 | [esp-idf-github]: https://github.com/espressif/esp-idf 8 | [newlib-env]: https://sourceware.org/newlib/ 9 | 10 | ## Current Support 11 | 12 | The Espressif products supported for Rust `std` development are the ones supported by the ESP-IDF framework. For details on different versions of ESP-IDF and support of Espressif chips, see [this table][esp-idf-release-compatibility]. 13 | 14 | [esp-idf-release-compatibility]: https://github.com/espressif/esp-idf#esp-idf-release-and-soc-compatibility/ 15 | 16 | When using `std`, you have access to a lot of features that exist in [ESP-IDF][esp-idf-github], including threads, mutexes and other synchronization primitives, collections, random number generation, sockets, etc. 17 | 18 | ### Relevant `esp-rs` Crates 19 | 20 | | Repository | Description | 21 | | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | 22 | | [`embedded-svc`][embedded-svc] | Abstraction traits for embedded services (`WiFi`, `Network`, `Httpd`, `Logging`, etc.) | 23 | | [`esp-idf-svc`][esp-idf-svc] | An implementation of [embedded-svc] using `esp-idf` drivers. | 24 | | [`esp-idf-hal`][esp-idf-hal] | An implementation of the `embedded-hal` and other traits using the `esp-idf` framework. | 25 | | [`esp-idf-sys`][esp-idf-sys] | Rust bindings to the `esp-idf` development framework. Gives raw (`unsafe`) access to drivers, Wi-Fi and more. | 26 | 27 | The aforementioned crates have interdependencies, and this relationship can be seen below. 28 | 29 | ```mermaid 30 | graph TD; 31 | esp-idf-hal --> esp-idf-sys & embedded-svc 32 | esp-idf-svc --> esp-idf-sys & esp-idf-hal & embedded-svc 33 | ``` 34 | 35 | [embedded-svc]: https://github.com/esp-rs/embedded-svc 36 | [esp-idf-svc]: https://github.com/esp-rs/esp-idf-svc 37 | [esp-idf-sys]: https://github.com/esp-rs/esp-idf-sys 38 | [esp-idf-hal]: https://github.com/esp-rs/esp-idf-hal 39 | 40 | ### When You Might Want to Use the Standard Library (`std`) 41 | 42 | - Rich functionality: If your embedded system requires lots of functionality like support for networking protocols, file I/O, or complex data structures, you will likely want to use hosted-environment approach because `std` libraries provide a wide range of functionality that can be used to build complex applications. 43 | - Portability: The `std` crate provides a standardized set of APIs that can be used across different platforms and architectures, making it easier to write code that is portable and reusable. 44 | - Rapid development: The `std` crate provides a rich set of functionality that can be used to build applications quickly and efficiently, without worrying, too much, about low-level details. 45 | 46 | 47 | 48 | -------------------------------------------------------------------------------- /src/writing-your-own-application/generate-project/index.md: -------------------------------------------------------------------------------- 1 | # Generating Projects from Templates 2 | 3 | We currently maintain two template repositories: 4 | - [`esp-generate`][esp-generate] - `no_std` template. 5 | - [`esp-idf-template`][esp-idf-template] - `std` template. 6 | 7 | 8 | ## `esp-generate` 9 | 10 | `esp-generate` is project generation tool that can be used to generate an application with all the required configurations and dependencies 11 | 12 | 1. Install `esp-generate`: 13 | ```shell 14 | cargo install esp-generate 15 | ``` 16 | 2. Generate a project based on the template, selecting the chip and the name of the project: 17 | ```shell 18 | esp-generate --chip=esp32c6 your-project 19 | ``` 20 | See [Understanding `esp-generate`][understanding-esp-generate] for more details on the template project. 21 | 22 | When the `esp-generate` subcommand is invoked, you will be prompted with a TUI where you can select the configuration of your application. Upon completion of this process, you will have a buildable project with all the correct configurations. 23 | 24 | 3. Build/Run the generated project: 25 | - Use `cargo build` to compile the project using the appropriate toolchain and target. 26 | - Use `cargo run` to compile the project, flash it, and open a serial monitor with our target device. 27 | 28 | [esp-generate]: https://github.com/esp-rs/esp-generate 29 | [understanding-esp-generate]: ./esp-generate.md 30 | 31 | ## `esp-idf-template` 32 | 33 | `esp-idf-template` is based on [`cargo-generate`][cargo-generate], a tool that allows you to create a new project based on some existing template. In our case, [`esp-idf-template`][esp-idf-template] can be used to generate an application with all the required configurations and dependencies. 34 | 35 | 1. Install `cargo generate`: 36 | ```shell 37 | cargo install cargo-generate 38 | ``` 39 | 2. Generate a project based on the template: 40 | ```shell 41 | cargo generate esp-rs/esp-idf-template cargo 42 | ``` 43 | See [Understanding `esp-idf-template`][understanding-esp-idf-template] for more details on the template project. 44 | 45 | When the `cargo generate` subcommand is invoked, you will be prompted to answer several questions regarding the target of your application. Upon completion of this process, you will have a buildable project with all the correct configurations. 46 | 47 | 3. Build/Run the generated project: 48 | - Use `cargo build` to compile the project using the appropriate toolchain and target. 49 | - Use `cargo run` to compile the project, flash it, and open a serial monitor with our target device. 50 | 51 | [cargo-generate]: https://github.com/cargo-generate/cargo-generate 52 | [esp-idf-template]: https://github.com/esp-rs/esp-idf-template 53 | [understanding-esp-idf-template]: ./esp-idf-template.md 54 | 55 | ## Using Dev Containers in the Templates 56 | 57 | Both template repositories have a prompt for Dev Containers support. 58 | 59 | Dev Containers use the [`idf-rust`][idf-rust] container image, which was explained in the [Using Container][using-container] section of the [Setting up a Development Environment][setting-env] chapter. This image provides an environment ready to develop Rust applications for Espressif chips with no installation required. Dev Containers also have integration with [Wokwi simulator][wokwi], to simulate the project, and allow flashing from the container using [`web-flash`][web-flash]. 60 | 61 | [idf-rust]: https://hub.docker.com/r/espressif/idf-rust/tags 62 | [using-container]: ../../installation/using-containers.md 63 | [wokwi]: https://wokwi.com/ 64 | [web-flash]: https://github.com/bjoernQ/esp-web-flash-server 65 | [setting-env]: ../../installation/index.md 66 | -------------------------------------------------------------------------------- /src/tooling/debugging/openocd.md: -------------------------------------------------------------------------------- 1 | 2 | # OpenOCD 3 | 4 | Similar to [`probe-rs`][probe-rs], OpenOCD doesn't have support for the `Xtensa` architecture. However, Espressif does maintain a fork of OpenOCD under [`espressif/openocd-esp32`][espressif-openocd-esp32] which has support for Espressif's chips. 5 | 6 | Instructions on how to install `openocd-esp32` for your platform can be found in [the Espressif documentation][espressif-documentation]. 7 | 8 | GDB with all the Espressif products supported can be obtained in [`espressif/binutils-gdb`][binutils-repo]. 9 | 10 | Once installed, it's as simple as running `openocd` with the correct arguments. For chips with the built-in [`USB-JTAG-SERIAL` peripheral][usb-jtag-serial], there is normally a config file that will work out of the box, for example on the ESP32-C3: 11 | 12 | ```shell 13 | openocd -f board/esp32c3-builtin.cfg 14 | ``` 15 | 16 | For other configurations, it may require specifying the chip and the interface, for example, ESP32 with a J-Link: 17 | 18 | ```shell 19 | openocd -f interface/jlink.cfg -f target/esp32.cfg 20 | ``` 21 | 22 | [probe-rs]: ./probe-rs.md 23 | [espressif-openocd-esp32]: https://github.com/espressif/openocd-esp32 24 | [espressif-documentation]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/index.html#setup-of-openocd 25 | [binutils-repo]: https://github.com/espressif/binutils-gdb 26 | [usb-jtag-serial]: index.md#usb-jtag-serial-peripheral 27 | 28 | ## VS Code Extension 29 | 30 | OpenOCD can be used in VS Code via the [`cortex-debug`][cortex-debug] extension to debug Espressif products. 31 | 32 | [cortex-debug]: https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug 33 | 34 | ### Configuration 35 | 36 | 1. If required, connect the external JTAG adapter. 37 | 1. See Configure Other JTAG Interfaces section of ESP-IDF Programming Guide. Eg: [Section for ESP32][jtag-interfaces-esp32] 38 | > ⚠️ **Note**: On Windows, `USB Serial Converter A 0403 6010 00` driver should be WinUSB. 39 | 2. Set up VSCode 40 | 1. Install [Cortex-Debug][cortex-debug] extension for VS Code. 41 | 2. Create the `.vscode/launch.json` file in the project tree you want to debug. 42 | 3. Update `executable`, `svdFile`, `serverpath` paths, and `toolchainPrefix` fields. 43 | 44 | ```json 45 | { 46 | // Use IntelliSense to learn about possible attributes. 47 | // Hover to view descriptions of existing attributes. 48 | // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387 49 | "version": "0.2.0", 50 | "configurations": [ 51 | { 52 | // more info at: https://github.com/Marus/cortex-debug/blob/master/package.json 53 | "name": "Attach", 54 | "type": "cortex-debug", 55 | "request": "attach", // launch will fail when attempting to download the app into the target 56 | "cwd": "${workspaceRoot}", 57 | "executable": "target/xtensa-esp32-none-elf/debug/.....", //!MODIFY 58 | "servertype": "openocd", 59 | "interface": "jtag", 60 | "toolchainPrefix": "xtensa-esp32-elf", //!MODIFY 61 | "openOCDPreConfigLaunchCommands": ["set ESP_RTOS none"], 62 | "serverpath": "C:/Espressif/tools/openocd-esp32/v0.11.0-esp32-20220411/openocd-esp32/bin/openocd.exe", //!MODIFY 63 | "gdbPath": "C:/Espressif/tools/riscv32-esp-elf-gdb/riscv32-esp-elf-gdb/bin/riscv32-esp-elf-gdb.exe", //!MODIFY 64 | "configFiles": ["board/esp32-wrover-kit-3.3v.cfg"], //!MODIFY 65 | "overrideAttachCommands": [ 66 | "set remote hardware-watchpoint-limit 2", 67 | "mon halt", 68 | "flushregs" 69 | ], 70 | "overrideRestartCommands": ["mon reset halt", "flushregs", "c"] 71 | } 72 | ] 73 | } 74 | ``` 75 | 76 | [jtag-interfaces-esp32]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/jtag-debugging/configure-other-jtag.html 77 | 78 | # Debugging with Multiple Cores 79 | 80 | Sometimes you may need to debug each core individually in GDB or with VSCode. In this case, change `set ESP_RTOS none` to `set ESP_RTOS hwthread`. This will make each core appear as a hardware thread in GDB. This is not currently documented in Espressif official documentation but in OpenOCD docs: https://openocd.org/doc/html/GDB-and-OpenOCD.html 81 | -------------------------------------------------------------------------------- /src/installation/riscv.md: -------------------------------------------------------------------------------- 1 | # `RISC-V` Targets Only 2 | 3 | To build Rust applications for the Espressif chips based on `RISC-V` architecture, do the following: 4 | 5 | 1. Install the proper toolchain with the `rust-src` [component][rustup-book-components]: 6 | - For `no_std` (bare-metal) applications, you can use both `stable` or [`nightly`][rustup-book-channel-nightly]: 7 | ```shell 8 | rustup toolchain install stable --component rust-src 9 | ``` 10 | or 11 | ```shell 12 | rustup toolchain install nightly --component rust-src 13 | ``` 14 | - For `std` applications, you need to use `nightly`: 15 | ```shell 16 | rustup toolchain install nightly --component rust-src 17 | ``` 18 | 19 | The above command downloads the rust source code. `rust-src` contains things like the std-lib, core-lib and build-config files. 20 | Downloading the `rust-src` is important because of two reasons : 21 | - **Determinism** - You get the chance to inspect the internals of the core and std library. If you are building software that needs to be determinate, you may need to inspect the libraries that you are using. 22 | - **Building custom targets** - The `rustc` uses the `rust-src` to create the components of a new custom-target. If you are targeting a triple-target that is not yet supported by rust, it becomes essential to download the `rust-src`. 23 | 24 | For more info on custom targets, read this [Chapter][embedonomicon-creating-a-custom-target] from the [Embedonomicon][embedonomicon-official-book]. 25 | 26 | 2. Set the target: 27 | - For `no_std` (bare-metal) applications, run: 28 | 29 | ```shell 30 | rustup target add riscv32imc-unknown-none-elf # For ESP32-C2 and ESP32-C3 31 | rustup target add riscv32imac-unknown-none-elf # For ESP32-C6 and ESP32-H2 32 | ``` 33 | 34 | This target is currently [Tier 2][rust-lang-book--platform-support-tier2]. Note the different flavors of `riscv32` target in Rust covering different [`RISC-V` extensions][wiki-riscv-standard-extensions]. 35 | 36 | - For `std` applications: 37 | 38 | Since this target is currently [Tier 3][rust-lang-book--platform-support-tier3], it doesn't have pre-built objects distributed through `rustup` and, unlike the `no_std` target, **nothing needs to be installed**. Refer to the [*-esp-idf][rust-lang-book--platform-support--esp-idf] section of the rustc book for the correct target for your device. 39 | 40 | - `riscv32imc-esp-espidf` for SoCs which don't support atomics, like ESP32-C2 and ESP32-C3 41 | - `riscv32imac-esp-espidf` for SoCs which support atomics, like ESP32-C6, ESP32-H2, and ESP32-P4 42 | 3. To build `std` projects, you also need to install: 43 | - [`LLVM`][llvm-website] compiler infrastructure 44 | - Other [`std` development requirements][rust-esp-book-std-requirements] 45 | - In your project's file `.cargo/config.toml`, add the unstable Cargo [feature][cargo-book-unstable-features] `-Z build-std`. Our [template projects][rust-esp-book-write-app-generate-project] that are discussed later in this book already include this. 46 | 47 | Now you should be able to build and run projects on Espressif's `RISC-V` chips. 48 | 49 | [rustup-book-channel-nightly]: https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust 50 | [rustup-book-components]: https://rust-lang.github.io/rustup/concepts/components.html 51 | [rust-lang-book--platform-support-tier2]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-2 52 | [wiki-riscv-standard-extensions]: https://en.wikichip.org/wiki/risc-v/standard_extensions 53 | [rust-lang-book--platform-support-tier3]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-3 54 | [rust-lang-book--platform-support--esp-idf]: https://doc.rust-lang.org/nightly/rustc/platform-support/esp-idf.html 55 | [llvm-website]: https://llvm.org/ 56 | [cargo-book-unstable-features]: https://doc.rust-lang.org/cargo/reference/unstable.html 57 | [rust-esp-book-write-app-generate-project]: ../writing-your-own-application/generate-project/index.md 58 | [rust-esp-book-std-requirements]: ./std-requirements.md 59 | [embedonomicon-creating-a-custom-target]: https://docs.rust-embedded.org/embedonomicon/custom-target.html 60 | [embedonomicon-official-book]: https://docs.rust-embedded.org/embedonomicon/ 61 | -------------------------------------------------------------------------------- /src/troubleshooting/index.md: -------------------------------------------------------------------------------- 1 | # Troubleshooting 2 | 3 | This chapter lists certain questions and common problems we have encountered over time, along with their solutions. This page collects common issues independent of the chosen ESP ecosystem. If you can't find your issue listed here, feel free to open an issue in the appropriate repository or ask on our [Matrix room][matrix]. 4 | 5 | [matrix]: https://matrix.to/#/#esp-rs:matrix.org 6 | 7 | ## Using the Wrong Rust Toolchain 8 | 9 | ```text 10 | $ cargo build 11 | error: failed to run `rustc` to learn about target-specific information 12 | 13 | Caused by: 14 | process didn't exit successfully: `rustc - --crate-name ___ --print=file-names --target xtensa-esp32-espidf --crate-type bin --crate-type rlib --crate-type dylib --crate-type cdylib --crate-type staticlib --crate-type proc-macro --print=sysroot --print=cfg` (exit status: 1) 15 | --- stderr 16 | error: Error loading target specification: Could not find specification for target "xtensa-esp32-espidf". Run `rustc --print target-list` for a list of built-in targets 17 | ``` 18 | 19 | If you are encountering the previous error or a similar one, you are probably not using the proper Rust toolchain. Remember that for `Xtensa` targets, you need to use Espressif Rust fork toolchain, there are several ways to do it: 20 | - A [toolchain override][toolchain-override] shorthand used on the command-line: `cargo +esp`. 21 | - Set `RUSTUP_TOOLCHAIN` environment variable to `esp`. 22 | - Set a [directory override][directory-override]: `rustup override set esp` 23 | - Add a [`rust-toolchain.toml`][rust-toolchain-toml] file to you project: 24 | ```toml 25 | [toolchain] 26 | channel = "esp" 27 | ``` 28 | - Set `esp` as [default toolchain][default-toolchain]. 29 | 30 | For more information on toolchain overriding, see the [Overrides chapter][overrides-rust-book] of The rustup book. 31 | 32 | [toolchain-override]: https://rust-lang.github.io/rustup/overrides.html#toolchain-override-shorthand 33 | [directory-override]: https://rust-lang.github.io/rustup/overrides.html#directory-overrides 34 | [rust-toolchain-toml]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file 35 | [default-toolchain]: https://rust-lang.github.io/rustup/overrides.html#default-toolchain 36 | [overrides-rust-book]: https://rust-lang.github.io/rustup/overrides.html#overrides 37 | 38 | ## Windows 39 | 40 | ### Long Path Names 41 | 42 | When using Windows, you may encounter issues building a new project if using long path names. 43 | Moreover - and if you are trying to build a `std` application - the build will fail with a hard error if your project path 44 | is longer than ~ 10 characters. 45 | 46 | To workaround the problem, you need to shorten your project name, and move it to the drive root, as in e.g. `C:\myproj`. 47 | Note also that while using the Windows `subst` utility (as in e.g. `subst r: `) might look like an easy 48 | solution for using short paths during build while still keeping your project location intact, 49 | it simply *does not work*, as the short, substituted paths are expanded to their actual (long) locations by the Windows APIs. 50 | 51 | Another alternative is to install Windows Subsystem for Linux (WSL), move your project(s) inside the native Linux file partition, 52 | build inside WSL and only flash the compiled MCU ELF file from outside of WSL. 53 | 54 | ### Missing ABI 55 | 56 | ```powershell 57 | Compiling cc v1.0.69 58 | error: linker `link.exe` not found 59 | | 60 | = note: The system cannot find the file specified. (os error 2) 61 | 62 | note: the msvc targets depend on the msvc linker but `link.exe` was not found 63 | 64 | note: please ensure that VS 2013, VS 2015, VS 2017 or VS 2019 was installed with the Visual C++ option 65 | 66 | error: could not compile `compiler_builtins` due to previous error 67 | warning: build failed, waiting for other jobs to finish... 68 | error: build failed 69 | ``` 70 | 71 | The reason for this error is that we are missing the MSVC C++, hence we aren't meeting the [Compile-time Requirements]. Please, install [Visual Studio 2013 (or later) or the Visual C++ Build Tools 2019]. For Visual Studio, make sure to check the "C++ tools" and "Windows 10 SDK" options. 72 | If using GNU ABI, install [MinGW/MSYS2 toolchain]. 73 | 74 | [Compile-time Requirements]: https://github.com/rust-lang/cc-rs#compile-time-requirements 75 | [Visual Studio 2013 (or later) or the Visual C++ Build Tools 2019]: https://rust-lang.github.io/rustup/installation/windows.html 76 | [MinGW/MSYS2 toolchain]: https://www.msys2.org/ 77 | -------------------------------------------------------------------------------- /src/troubleshooting/std.md: -------------------------------------------------------------------------------- 1 | # `esp-idf-sys` based projects 2 | 3 | ## Wrong Xtal Frequency 4 | 5 | Using a 26 Mhz crystal instead of a 40 MHz requires modifying the [`sdkconfig`][sdkconfig]. Add the following configuration option to your `sdkconfig` file: 6 | 7 | ``` 8 | CONFIG_XTAL_FREQ_26=y 9 | ``` 10 | 11 | After making this adjustment, execute `cargo clean` to ensure that the changes are properly incorporated into your project. See [`sdkconfig` section](#sdkconfigdefaults-file-is-updated-but-it-doesnt-appear-to-have-had-any-effect). 12 | 13 | When using an `esp-idf-sys` based project, you should also prefer using `cargo-espflash` instead of `espflash`. `cargo-espflash` integrates with your 14 | project and it will flash the bootloader and partition table that is built for your project instead of the default one, see the corresponding [`cargo-espflash` readme section][cargo-espflash-bootloader]. 15 | 16 | If you want to use `espflash`, you can specify an appropriate bootloader and partition table using `--bootloader` and `--partition-table`. You can find the bootloader in `target///bootloader.bin` and partition table in `target///partition-table.bin` 17 | 18 | [sdkconfig]: https://github.com/esp-rs/esp-idf-sys/blob/master/BUILD-OPTIONS.md#sdkconfig 19 | [cargo-espflash-bootloader]: https://github.com/esp-rs/espflash/tree/main/cargo-espflash#bootloader-and-partition-table 20 | 21 | ## Environment Variable `LIBCLANG_PATH` Not Set 22 | 23 | ```text 24 | thread 'main' panicked at 'Unable to find libclang: "couldn't find any valid shared libraries matching: ['libclang.so', 'libclang-*.so', 'libclang.so.*', 'libclang-*.so.*'], set the `LIBCLANG_PATH` environment variable to a path where one of these files can be found (invalid: [])"', /home/esp/.cargo/registry/src/github.com-1ecc6299db9ec823/bindgen-0.60.1/src/lib.rs:2172:31 25 | ``` 26 | 27 | We need `libclang` for [`bindgen`] to generate the Rust bindings to the ESP-IDF C headers. 28 | Make sure you have sourced the export file generated by `espup`, see [Set up the environment variables][set-up-the-environment-variables]. 29 | 30 | [`bindgen`]: https://github.com/rust-lang/rust-bindgen 31 | [set-up-the-environment-variables]: ./../installation/riscv-and-xtensa.md#3-set-up-the-environment-variables 32 | 33 | ## Missing `ldproxy` 34 | 35 | ```shell 36 | error: linker `ldproxy` not found 37 | | 38 | = note: No such file or directory (os error 2) 39 | ``` 40 | 41 | If you are trying to build a `std` application [`ldproxy`][ldproxy] must be installed. See [`std` Development Requirements][rust-esp-book-std-requirements] 42 | 43 | ```shell 44 | cargo install ldproxy 45 | ``` 46 | 47 | [ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy 48 | [rust-esp-book-std-requirements]: ./../installation/std-requirements.md 49 | 50 | ## `sdkconfig.defaults` File is Updated but it Doesn't Appear to Have Had Any Effect 51 | 52 | You must clean your project and rebuild for changes in the `sdkconfig.defaults` to take effect: 53 | 54 | ```shell 55 | cargo clean 56 | cargo build 57 | ``` 58 | 59 | ## The Documentation for the Crates Mentioned on This Page is out of Date or Missing 60 | 61 | Due to the [resource limits] imposed by [docs.rs], internet access is blocked while building documentation. For this reason, we are unable to build the documentation for `esp-idf-sys` or any crate depending on it. 62 | 63 | Instead, we are building the documentation and hosting it ourselves on GitHub Pages: 64 | 65 | - [`esp-idf-hal` Documentation] 66 | - [`esp-idf-svc` Documentation] 67 | - [`esp-idf-sys` Documentation] 68 | 69 | [resource limits]: https://docs.rs/about/builds#hitting-resource-limits 70 | [docs.rs]: https://docs.rs 71 | [`esp-idf-hal` documentation]: https://esp-rs.github.io/esp-idf-hal/esp_idf_hal/ 72 | [`esp-idf-svc` documentation]: https://esp-rs.github.io/esp-idf-svc/esp_idf_svc/ 73 | [`esp-idf-sys` documentation]: https://esp-rs.github.io/esp-idf-sys/esp_idf_sys/ 74 | 75 | ## A Stack Overflow in Task `main` has Been Detected 76 | 77 | If the second-stage bootloader reports this error, you likely need to increase the stack size for the main task. This can be accomplished by adding the following to the `sdkconfig.defaults` file: 78 | 79 | ```text 80 | CONFIG_ESP_MAIN_TASK_STACK_SIZE=7000 81 | ``` 82 | 83 | In this example, we are allocating 7 kB for the main task's stack. 84 | 85 | ## How to Disable Watchdog Timer(s)? 86 | 87 | Add to your `sdkconfig.defaults` file: 88 | 89 | ```text 90 | CONFIG_INT_WDT=n 91 | CONFIG_ESP_TASK_WDT=n 92 | ``` 93 | 94 | Recall that you must clean your project before rebuilding when modifying these configuration files. 95 | -------------------------------------------------------------------------------- /src/installation/riscv-and-xtensa.md: -------------------------------------------------------------------------------- 1 | # `RISC-V` and `Xtensa` Targets 2 | 3 | [`espup`][espup-github] is a tool that simplifies installing and maintaining the components required to develop Rust applications for the `Xtensa` and `RISC-V` architectures. 4 | 5 | ### 1. Install `espup` 6 | 7 | To install `espup`, run: 8 | ```shell 9 | cargo install espup 10 | ``` 11 | 12 | You can also directly download pre-compiled [release binaries][release-binaries] or use [`cargo-binstall`][cargo-binstall]. 13 | 14 | [espup-github]: https://github.com/esp-rs/espup 15 | [release-binaries]: https://github.com/esp-rs/espup/releases 16 | [cargo-binstall]: https://github.com/cargo-bins/cargo-binstall 17 | 18 | ### 2. Install Necessary Toolchains 19 | 20 | Install all the necessary tools to develop Rust applications for all supported Espressif targets by running: 21 | ```shell 22 | espup install 23 | ``` 24 | 25 | > ⚠️ **Note**: `std` applications require installing additional software covered in [`std` Development Requirements][rust-esp-book-std-requirements] 26 | 27 | [rust-esp-book-std-requirements]: ./std-requirements.md 28 | 29 | ### 3. Set Up the Environment Variables 30 | `espup` will create an export file that contains some environment variables required to build projects. 31 | 32 | On Windows (`%USERPROFILE%\export-esp.ps1`) 33 | - There is **no need** to execute the file for Windows users. It is only created to show the modified environment variables. 34 | 35 | On Unix-based systems (`$HOME/export-esp.sh`). There are different ways of sourcing the file: 36 | - Source this file in every terminal: 37 | 1. Source the export file: `. $HOME/export-esp.sh` 38 | 39 | This approach requires running the command in every new shell. 40 | - Create an alias for executing the `export-esp.sh`: 41 | 1. Copy and paste the following command to your shell’s profile (`.profile`, `.bashrc`, `.zprofile`, etc.): `alias get_esprs='. $HOME/export-esp.sh'` 42 | 2. Refresh the configuration by restarting the terminal session or by running `source [path to profile]`, for example, `source ~/.bashrc`. 43 | 44 | This approach requires running the alias in every new shell. 45 | - Add the environment variables to your shell profile directly: 46 | 1. Add the content of `$HOME/export-esp.sh` to your shell’s profile: `cat $HOME/export-esp.sh >> [path to profile]`, for example, `cat $HOME/export-esp.sh >> ~/.bashrc`. 47 | 2. Refresh the configuration by restarting the terminal session or by running `source [path to profile]`, for example, `source ~/.bashrc`. 48 | 49 | This approach **doesn't** require any sourcing. The `export-esp.sh` script will be sourced automatically in every shell. 50 | 51 | ### What `espup` Installs 52 | 53 | To enable support for Espressif targets, `espup` installs the following tools: 54 | 55 | - Espressif Rust fork with support for Espressif targets 56 | - `nightly` toolchain with support for `RISC-V` targets 57 | - `LLVM` [fork][llvm-github-fork] with support for `Xtensa` targets 58 | - [GCC toolchain][gcc-toolchain-github-fork] that links the final binary 59 | 60 | The forked compiler can coexist with the standard Rust compiler, allowing both to be installed on your system. The forked compiler is invoked when using any of the available [overriding methods][rustup-overrides]. 61 | 62 | > ⚠️ **Note**: We are making efforts to upstream our forks 63 | > 1. Changes in `LLVM` fork. Already in progress, see the status in this [tracking issue][llvm-github-fork-upstream issue]. 64 | > 2. Rust compiler forks. If `LLVM` changes are accepted, we will proceed with the Rust compiler changes. 65 | 66 | If you run into an error, please, check the [Troubleshooting][troubleshooting] chapter. 67 | 68 | [llvm-github-fork]: https://github.com/espressif/llvm-project 69 | [gcc-toolchain-github-fork]: https://github.com/espressif/crosstool-NG/ 70 | [rustup-overrides]: https://rust-lang.github.io/rustup/overrides.html 71 | [llvm-github-fork-upstream issue]: https://github.com/espressif/llvm-project/issues/4 72 | [troubleshooting]: ../troubleshooting/index.md 73 | 74 | ### Other Installation Methods for `Xtensa` Targets 75 | 76 | - Using [`rust-build`][rust-build] installation scripts. This was the recommended way in the past, but now the installation scripts are feature frozen, and all new features will only be included in `espup`. See the repository README for instructions. 77 | - Building the Rust compiler with `Xtensa` support from source. This process is computationally expensive and can take one or more hours to complete depending on your system. It isn't recommended unless there is a major reason to go for this approach. Here is the repository to build it from source: [`esp-rs/rust` repository][esp-rs-rust]. 78 | 79 | [rust-build]: https://github.com/esp-rs/rust-build#download-installer-in-bash 80 | [esp-rs-rust]: https://github.com/esp-rs/rust 81 | -------------------------------------------------------------------------------- /src/overview/using-the-core-library.md: -------------------------------------------------------------------------------- 1 | # Using the Core Library (`no_std`) 2 | 3 | Using `no_std` may be more familiar to embedded Rust developers. It doesn't use `std` (the Rust [`standard`][rust-lib-std] library) but instead uses a subset, the [`core`][rust-lib-core] library. [The Embedded Rust Book][embedded-rust-book] has a great [section][embedded-rust-book-no-std] on this. 4 | 5 | It is important to note that `no_std` uses the Rust `core` library. As this library is part of the Rust `standard` library, a `no_std` crate can compile in `std` environment. However, the opposite isn't true: an `std` crate can't compile in `no_std` environment. This information is worth remembering when deciding which library to choose. 6 | 7 | [embedded-rust-book]: https://docs.rust-embedded.org/ 8 | [embedded-rust-book-no-std]: https://docs.rust-embedded.org/book/intro/no-std.html 9 | [rust-lib-core]: https://doc.rust-lang.org/core/index.html 10 | [rust-lib-std]: https://doc.rust-lang.org/std/index.html 11 | 12 | ## Current Support 13 | 14 | The table below covers the current support for `no_std` at this moment for different Espressif products. 15 | 16 | | | [HAL][esp-hal] | [Wi-Fi/BLE/ESP-NOW][esp-wifi] | [Backtrace][esp-backtrace] | [Storage][esp-storage] | 17 | | -------- | :------------: | :---------------------------: | :------------------------: | :--------------------: | 18 | | ESP32 | ✅ | ✅ | ✅ | ✅ | 19 | | ESP32-C2 | ✅ | ✅ | ✅ | ✅ | 20 | | ESP32-C3 | ✅ | ✅ | ✅ | ✅ | 21 | | ESP32-C6 | ✅ | ✅ | ✅ | ✅ | 22 | | ESP32-H2 | ✅ | ✅ | ✅ | ✅ | 23 | | ESP32-S2 | ✅ | ✅ | ✅ | ✅ | 24 | | ESP32-S3 | ✅ | ✅ | ✅ | ✅ | 25 | 26 | > ⚠️ **Note**: 27 | > 28 | > - ✅ in Wi-Fi/BLE/ESP-NOW means that the target supports, at least, one of the listed technologies. For details, see [Current support][esp-wifi-current-support] table of the esp-wifi repository. 29 | > - [ESP8266 HAL][esp8266-hal] is in maintenance mode and no further development will be done for this chip. 30 | 31 | [esp-hal]: https://github.com/esp-rs/esp-hal/tree/main/esp-hal "Hardware abstraction layer" 32 | [esp-wifi]: https://github.com/esp-rs/esp-hal/tree/main/esp-wifi "Wi-Fi, BLE and ESP-NOW support" 33 | [esp-backtrace]: https://github.com/esp-rs/esp-hal/tree/main/esp-backtrace "Exception and panic handlers" 34 | [esp-storage]: https://github.com/esp-rs/esp-hal/tree/main/esp-storage "Embedded-storage traits to access unencrypted flash memory" 35 | [esp-wifi-current-support]: https://github.com/esp-rs/esp-hal/tree/main/esp-wifi#current-support 36 | [esp8266-hal]: https://github.com/esp-rs/esp8266-hal "ESP8266 Hardware abstraction layer" 37 | 38 | ### Relevant `esp-rs` Crates 39 | 40 | | Repository | Description | 41 | | -------------------------------- | ---------------------------------------------------------- | 42 | | [`esp-hal`][esp-hal] | Hardware abstraction layer | 43 | | [`esp-pacs`][esp-pacs] | Peripheral access crates | 44 | | [`esp-wifi`][esp-wifi] | Wi-Fi, BLE and ESP-NOW support | 45 | | [`esp-alloc`][esp-alloc] | Simple heap allocator | 46 | | [`esp-println`][esp-println] | `print!`, `println!` | 47 | | [`esp-backtrace`][esp-backtrace] | Exception and panic handlers | 48 | | [`esp-storage`][esp-storage] | Embedded-storage traits to access unencrypted flash memory | 49 | 50 | ### When You Might Want to Use the Core Library (`no_std`) 51 | 52 | - Small memory footprint: If your embedded system has limited resources and needs to have a small memory footprint, you will likely want to use bare-metal because `std` features add a significant amount of final binary size and compilation time. 53 | - Direct hardware control: If your embedded system requires more direct control over the hardware, such as low-level device drivers or access to specialized hardware features you will likely want to use bare-metal because `std` adds abstractions that can make it harder to interact directly with the hardware. 54 | - Real-time constraints or time-critical applications: If your embedded system requires real-time performance or low-latency response times because `std` can introduce unpredictable delays and overhead that can affect real-time performance. 55 | - Custom requirements: bare-metal allows more customization and fine-grained control over the behavior of an application, which can be useful in specialized or non-standard environments. 56 | 57 | [esp-pacs]: https://github.com/esp-rs/esp-pacs "Peripheral access crates" 58 | [esp-alloc]: https://github.com/esp-rs/esp-hal/tree/main/esp-alloc "Simple heap allocator" 59 | [esp-println]: https://github.com/esp-rs/esp-hal/tree/main/esp-println "print!, println!" 60 | -------------------------------------------------------------------------------- /src/introduction.md: -------------------------------------------------------------------------------- 1 |

2 | 3 | # Introduction 4 | 5 | The goal of this book is to provide a comprehensive guide on using the [Rust Programming Language][rust] with [Espressif][espressif] devices. 6 | 7 | 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. 8 | 9 | For tools and libraries relating to Rust on ESP, please see the [esp-rs organization][esp-rs] on GitHub. This organization is managed by employees of Espressif as well as members of the community. 10 | 11 | Feel free to join the [`esp-rs` community on Matrix][matrix] for all technical questions and issues! The community is open to everyone. 12 | 13 | [rust]: https://www.rust-lang.org/ 14 | [espressif]: https://espressif.com/ 15 | [esp-rs]: https://github.com/esp-rs/ 16 | [matrix]: https://matrix.to/#/#esp-rs:matrix.org 17 | 18 | ## Who This Book Is For 19 | 20 | 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][prerequisites] and [Resources][resources] sections to get up to speed. 21 | 22 | [prerequisites]: #assumptions-and-prerequisites 23 | [resources]: #resources 24 | 25 | ### Assumptions and Prerequisites 26 | 27 | - You are comfortable using the Rust programming language and have written and run applications in a desktop environment. 28 | - You should be familiar with the idioms of the [2021 edition][rust-2021], as this book targets Rust 2021. 29 | - You are comfortable developing embedded systems in another language such as C or C++, and are familiar with concepts such as: 30 | - Cross-compilation 31 | - Common digital interfaces like `UART`, `SPI`, `I2C`, etc. 32 | - Memory-mapped peripherals 33 | - Interrupts 34 | 35 | [rust-2021]: https://doc.rust-lang.org/edition-guide/rust-2021/index.html 36 | 37 | ### Resources 38 | 39 | 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. 40 | 41 | | Resource | Description | 42 | | ------------------------------------------------------ | ------------------------------------------------------------------------------------ | 43 | | [The Rust Programming Language][rust-book] | If you aren't familiar with Rust we recommend reading this book first. | 44 | | [The Embedded Rust Book][embedded-rust-book] | Here you can find several other resources provided by Rust's Embedded Working Group. | 45 | | [The Embedonomicon][embedonomicon] | The nitty-gritty details when doing embedded programming in Rust. | 46 | | [Embedded Rust (std) on Espressif][std-training] | Getting started guide on using `std` for Espressif SoCs | 47 | | [Embedded Rust (no_std) on Espressif][no_std-training] | Getting started guide on using `no_std` for Espressif SoCs | 48 | 49 | [rust-book]: https://doc.rust-lang.org/book/ 50 | [embedded-rust-book]: https://docs.rust-embedded.org/book/index.html 51 | [embedonomicon]: https://docs.rust-embedded.org/embedonomicon/ 52 | [std-training]: https://esp-rs.github.io/std-training/ 53 | [no_std-training]: https://esp-rs.github.io/no_std-training/ 54 | 55 | ## Translations 56 | 57 | This book has been translated by generous volunteers. If you would like your translation listed here, please open a PR to add it. 58 | 59 | - [简体中文](https://narukara.github.io/rust-on-esp-book-zh-cn/) ([repository](https://github.com/Narukara/rust-on-esp-book-zh-cn)) 60 | - [한국어](https://ing03201.github.io/rust-on-esp-book-ko-kr/) ([repository](https://github.com/ing03201/rust-on-esp-book-ko-kr)) 61 | ## How to Use This Book 62 | 63 | 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. 64 | 65 | ## Contributing to This Book 66 | 67 | The work on this book is coordinated in [this repository][book-repository]. 68 | 69 | 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][book-issues] of this book. 70 | 71 | Pull requests fixing typos and adding new content are welcome! 72 | 73 | [book-issues]: https://github.com/esp-rs/book/issues/ 74 | [book-repository]: https://github.com/esp-rs/book 75 | 76 | ## Re-Using This Material 77 | 78 | This book is distributed under the following licenses: 79 | 80 | - The code samples and freestanding Cargo projects contained within this book are licensed under the terms of both the [MIT License][mit-license] and the [Apache License v2.0][apache-license]. 81 | - The written prose, pictures, and diagrams contained within this book are licensed under the terms of the Creative Commons [CC-BY-SA v4.0][cc-license] license. 82 | 83 | In summary, to use our text or images in your work, you need to: 84 | 85 | - Give the appropriate credit (i.e. mention this book on your slide, and provide a link to the relevant page) 86 | - Provide a link to the [CC-BY-SA v4.0][cc-license] license 87 | - Indicate if you have changed the material in any way, and make any changes to our material available under the same license 88 | 89 | Please do let us know if you find this book useful! 90 | 91 | [mit-license]: https://opensource.org/licenses/MIT 92 | [apache-license]: http://www.apache.org/licenses/LICENSE-2.0 93 | [cc-license]: https://creativecommons.org/licenses/by-sa/4.0/legalcode 94 | -------------------------------------------------------------------------------- /src/tooling/debugging/probe-rs.md: -------------------------------------------------------------------------------- 1 | # `probe-rs` 2 | 3 | The [`probe-rs`][probe-rs] project is a set of tools to interact with embedded MCU's using various debug probes. It is similar to [OpenOCD][openocd], [pyOCD][pyocd], [Segger tools][segger-tools], etc. There is support for `Xtensa` & `RISC-V` architectures along with a collection of tools, including but not limited to: 4 | 5 | - Debugger 6 | - GDB support. 7 | - CLI for interactive debugging. 8 | - VS Code extension. 9 | - [Real Time Transfer (RTT)][rtt] 10 | - Similar to [`app_trace` component of IDF][app-trace-idf]. 11 | - Flashing algorithms 12 | 13 | Follow the [installation][prober-rs-installation] and [setup][prober-rs-setup] instructions at the [`probe-rs`][probe-rs] website. 14 | 15 | Espressif products containing the [`USB-JTAG-SERIAL` peripheral][usb-jtag-serial] can use `probe-rs` without any external hardware. 16 | 17 | [probe-rs]: https://probe.rs/ 18 | [openocd]: https://openocd.org/ 19 | [pyocd]: https://pyocd.io/ 20 | [segger-tools]: https://www.segger.com/ 21 | [app-trace-idf]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/app_trace.html 22 | [rtt]: https://wiki.segger.com/RTT 23 | [prober-rs-installation]: https://probe.rs/docs/getting-started/installation/ 24 | [prober-rs-setup]: https://probe.rs/docs/getting-started/probe-setup/ 25 | [usb-jtag-serial]: index.md#usb-jtag-serial-peripheral 26 | 27 | ## Flashing with `probe-rs` 28 | 29 | `probe-rs` can be used to flash applications to your target since it supports the [ESP-IDF image format][idf-image]. 30 | - Example command for flashing an ESP32-C3: `probe-rs run --chip esp32c3` 31 | 32 | The flashing command can be set as a custom Cargo runner by adding the following to your project's `.cargo/config.toml` file: 33 | 34 | ```toml 35 | [target.'cfg(any(target_arch = "riscv32", target_arch = "xtensa"))'] 36 | runner = "probe-rs run --chip esp32c3" 37 | ``` 38 | 39 | With this configuration, you can flash and monitor your application using `cargo run`. 40 | 41 | [idf-image]: https://docs.espressif.com/projects/esptool/en/latest/esp32c3/advanced-topics/firmware-image-format.html 42 | 43 | ## VS Code Extension 44 | 45 | There is a `probe-rs` extension in VS Code, see `probe-rs` [VS Code documentation][probe-rs-vscode] for details on how to install, configure and use it. 46 | 47 | ### Example `launch.json` 48 | 49 | ```json 50 | { 51 | "version": "0.2.0", 52 | "configurations": [ 53 | { 54 | "type": "probe-rs-debug", 55 | "request": "launch", 56 | "name": "Launch", 57 | "cwd": "${workspaceFolder}", 58 | "chip": "esp32c3", //!MODIFY 59 | // probe field only needed if multiple probes connected. is the MAC address of your esp in case of usb-jtag 60 | "probe": "VID:PID:", //!MODIFY (or remove) | optional field 61 | "flashingConfig": { 62 | "flashingEnabled": true, 63 | "haltAfterReset": true, 64 | "formatOptions": { 65 | "binaryFormat": "idf" 66 | } 67 | }, 68 | "coreConfigs": [ 69 | { 70 | "coreIndex": 0, 71 | "programBinary": "target/riscv32imc-unknown-none-elf/debug/${workspaceFolderBasename}", //!MODIFY 72 | // svdFiles describe the hardware register names off the esp peripherals, such as the LEDC peripheral. 73 | // They can be downloaded seperatly @ https://github.com/espressif/svd/tree/main/svd 74 | "svdFile": "${workspaceFolder}/esp32c3.svd" //!MODIFY (or remove) | optional field 75 | } 76 | ] 77 | }, 78 | { 79 | "type": "probe-rs-debug", 80 | "request": "attach", 81 | "name": "Attach", 82 | "cwd": "${workspaceFolder}", 83 | "chip": "esp32c3", //!MODIFY 84 | "probe": "VID:PID:", //!MODIFY (or remove) | optional field 85 | "coreConfigs": [ 86 | { 87 | "coreIndex": 0, 88 | "programBinary": "target/riscv32imc-unknown-none-elf/debug/${workspaceFolderBasename}", //!MODIFY 89 | "svdFile": "${workspaceFolder}/esp32c3.svd" //!MODIFY (or remove) | optional field 90 | } 91 | ] 92 | } 93 | ] 94 | } 95 | ``` 96 | 97 | The `Launch` configuration will flash the device and start debugging process while `Attach` will start the debugging in the already running application of the device. See VS Code documentation on [differences between launch and attach][vscode-configs] for more details. 98 | 99 | 100 | [probe-rs-vscode]: https://probe.rs/docs/tools/debugger/ 101 | [vscode-configs]: https://code.visualstudio.com/docs/editor/debugging#_launch-versus-attach-configurations 102 | 103 | ## `cargo-flash` and `cargo-embed` 104 | 105 | `probe-rs` comes along with these two tools: 106 | - [`cargo-flash`][cargo-flash]: A flash tool that downloads your binary to the target and runs it. 107 | - [`cargo-embed`][cargo-embed]: Superset of `cargo-flash` that also allows opening an RTT terminal or a GDB server. A [configuration file][cargo-embed-config] can used to define the behavior. 108 | 109 | [cargo-flash]: https://probe.rs/docs/tools/cargo-flash/ 110 | [cargo-embed]: https://probe.rs/docs/tools/cargo-embed/ 111 | [cargo-embed-config]: https://probe.rs/docs/tools/cargo-embed/#configuration 112 | 113 | ## GDB Integration 114 | 115 | `probe-rs` includes a GDB stub to integrate into your usual workflow with common tools. The `probe-rs gdb` command runs a GDB server, by default in port, `1337`. 116 | 117 | GDB with all the Espressif products supported can be obtained in [`espressif/binutils-gdb`][binutils-repo] 118 | 119 | [binutils-repo]: https://github.com/espressif/binutils-gdb 120 | -------------------------------------------------------------------------------- /src/writing-your-own-application/generate-project/esp-idf-template.md: -------------------------------------------------------------------------------- 1 | # Understanding `esp-idf-template` 2 | 3 | Now that we know how to [generate a `std` project][generate-std], let's inspect what the generated project contains and try to understand every part of it. 4 | 5 | [generate-std]: ./index.md 6 | 7 | ## Inspecting the Generated Project 8 | 9 | When creating a project from [`esp-idf-template`][esp-idf-template] with the following answers: 10 | - Which MCU to target? · `esp32c3` 11 | - Configure advanced template options? · `false` 12 | 13 | For this explanation, we will use the default values, if you want further modifications, see the [additional prompts][prompts] when not using default values. 14 | 15 | It should generate a file structure like this: 16 | 17 | ```text 18 | ├── .cargo 19 | │   └── config.toml 20 | ├── src 21 | │   └── main.rs 22 | ├── .gitignore 23 | ├── build.rs 24 | ├── Cargo.toml 25 | ├── rust-toolchain.toml 26 | └── sdkconfig.defaults 27 | ``` 28 | 29 | Before going further, let's see what these files are for. 30 | 31 | - [`.cargo/config.toml`][config-toml] 32 | - The Cargo configuration 33 | - Contains our target 34 | - Contains `runner = "espflash flash --monitor"` - this means you can just use `cargo run` to flash and monitor your code 35 | - Contains the linker to use, in our case, [`ldproxy`][ldproxy] 36 | - Contains the unstable `build-std` Cargo feature enabled 37 | - Contains the `ESP-IDF-VERSION` environment variable that tells [`esp-idf-sys`][esp-idf-sys] which ESP-IDF version the project will use 38 | - `src/main.rs` 39 | - The main source file of the newly created project 40 | - For details, see the [Understanding `main.rs`][main-rs] section below 41 | - [`.gitignore`][gitignore] 42 | - Tells `git` which folders and files to ignore 43 | - [`build.rs`][build-rs] 44 | - Propagates linker arguments for `ldproxy` 45 | - [`Cargo.toml`][cargo-toml] 46 | - The usual Cargo manifest declaring some meta-data and dependencies of the project 47 | - [`rust-toolchain.toml`][rust-toolchain-toml] 48 | - Defines which Rust toolchain to use 49 | - The toolchain will be `nightly` or `esp` depending on your target 50 | - [`sdkconfig.defaults`][sdkconfig-defaults] 51 | - Contains the overridden values from the ESP-IDF defaults 52 | 53 | [esp-idf-template]: https://github.com/esp-rs/esp-idf-template 54 | [prompts]: https://github.com/esp-rs/esp-idf-template#generate-the-project 55 | [main-rs]:#understanding-mainrs 56 | [config-toml]: https://doc.rust-lang.org/cargo/reference/config.html 57 | [ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy 58 | [esp-idf-sys]: https://github.com/esp-rs/esp-idf-sys 59 | [gitignore]: https://git-scm.com/docs/gitignore 60 | [build-rs]: https://doc.rust-lang.org/cargo/reference/build-scripts.html 61 | [cargo-toml]: https://doc.rust-lang.org/cargo/reference/manifest.html 62 | [rust-toolchain-toml]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file 63 | [sdkconfig-defaults]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html#custom-sdkconfig-defaults 64 | 65 | ### Understanding `main.rs` 66 | 67 | ```rust,ignore 68 | 1 use esp_idf_sys as _; // If using the `binstart` feature of `esp-idf-sys`, always keep this module imported 69 | 2 70 | 3 fn main() { 71 | 4 // It is necessary to call this function once. Otherwise some patches to the runtime 72 | 5 // implemented by esp-idf-sys might not link properly. See https://github.com/esp-rs/esp-idf-template/issues/71 73 | 6 esp_idf_sys::link_patches(); 74 | 7 println!("Hello, world!"); 75 | 8 } 76 | ``` 77 | 78 | The first line is an import that defines the ESP-IDF entry point when the root crate is a binary crate that defines a main function. 79 | 80 | Then, we have a usual main function with a few lines on it: 81 | - A call to `esp_idf_sys::link_patches` function that makes sure that a few patches to the ESP-IDF which are implemented in Rust are linked to the final executable 82 | - We print on our console the famous "Hello, world!" 83 | 84 | ## Running the Code 85 | 86 | Building and running the code is as easy as 87 | 88 | ```shell 89 | cargo run 90 | ``` 91 | 92 | This builds the code according to the configuration and executes [`espflash`][espflash] to flash the code to the board. 93 | 94 | Since our [`runner` configuration][runner-config] also passes the `--monitor` argument to [`espflash`][espflash], we can see what the code is printing. 95 | 96 | Make sure that you have [`espflash`][espflash] installed, otherwise this step will fail. To install [`espflash`][espflash]: 97 | `cargo install espflash` 98 | 99 | You should see something similar to this: 100 | 101 | ```text 102 | [2023-04-18T08:05:09Z INFO ] Connecting... 103 | [2023-04-18T08:05:10Z INFO ] Using flash stub 104 | [2023-04-18T08:05:10Z WARN ] Setting baud rate higher than 115,200 can cause issues 105 | Chip type: esp32c3 (revision v0.3) 106 | Crystal frequency: 40MHz 107 | Flash size: 4MB 108 | Features: WiFi, BLE 109 | MAC address: 60:55:f9:c0:39:7c 110 | App/part. size: 478,416/4,128,768 bytes, 11.59% 111 | [00:00:00] [========================================] 13/13 0x0 112 | [00:00:00] [========================================] 1/1 0x8000 113 | [00:00:04] [========================================] 227/227 0x10000 114 | [2023-04-18T08:05:15Z INFO ] Flashing has completed! 115 | Commands: 116 | CTRL+R Reset chip 117 | CTRL+C Exit 118 | 119 | ... 120 | I (344) cpu_start: Starting scheduler. 121 | Hello, world! 122 | ``` 123 | 124 | As you can see, there are messages from the first and second-stage bootloader and then, our "Hello, world!" is printed. 125 | 126 | You can reboot with `CTRL+R` or exit with `CTRL+C`. 127 | 128 | If you encounter any issues while building the project, please, see the [Troubleshooting][troubleshooting] chapter. 129 | 130 | [espflash]: https://github.com/esp-rs/espflash/tree/main/espflash 131 | [runner-config]: https://doc.rust-lang.org/cargo/reference/config.html#targettriplerunner 132 | [troubleshooting]: ../../troubleshooting/index.md 133 | -------------------------------------------------------------------------------- /src/assets/esp-logo-black.svg: -------------------------------------------------------------------------------- 1 | 2 | 18 | 38 | 40 | 42 | 43 | 导航栏-菜单-logo 45 | 48 | 51 | 55 | 59 | 64 | 68 | 72 | 79 | 83 | 87 | 91 | 95 | 99 | 103 | 107 | 111 | 112 | 113 | 115 | 116 | 118 | 导航栏-菜单-logo 119 | 120 | 121 | 122 | 123 | -------------------------------------------------------------------------------- /src/writing-your-own-application/generate-project/esp-generate.md: -------------------------------------------------------------------------------- 1 | # Understanding `esp-generate` 2 | 3 | Now that we know how to [generate a `no_std` project][generate-no-std], let's inspect what the generated 4 | project contains, try to understand every part of it, and run it. 5 | 6 | [generate-no-std]: ./index.md 7 | 8 | ## Inspecting the Generated Project 9 | 10 | When creating a project from [`esp-generate`][esp-generate] with no extra options: 11 | ``` 12 | esp-generate --chip esp32c3 your-project 13 | ``` 14 | 15 | It should generate a file structure like this: 16 | 17 | ```text 18 | ├── build.rs 19 | ├── .cargo 20 | │ └── config.toml 21 | ├── Cargo.toml 22 | ├── .gitignore 23 | ├── rust-toolchain.toml 24 | ├── src 25 | │ ├── bin 26 | │ │ └── main.rs 27 | │ └── lib.rs 28 | └── .vscode 29 | └── settings.json 30 | ``` 31 | 32 | Before going further, let's see what these files are for. 33 | - [`build.rs`][build.rs] 34 | - Sets the linker script arguments based on the template options. 35 | - [`.cargo/config.toml`][config-toml] 36 | - The Cargo configuration 37 | - This defines a few options to correctly build the project 38 | - Contains the custom runner command for `espflash` or `probe-rs`. For example, `runner = "espflash flash --monitor"` - this means you can just use `cargo run` to flash and monitor your code 39 | - [`Cargo.toml`][cargo-toml] 40 | - The usual Cargo manifest declares some meta-data and dependencies of the project 41 | - [`.gitignore`][gitignore] 42 | - Tells `git` which folders and files to ignore 43 | - [`rust-toolchain.toml`][rust-toolchain-toml] 44 | - Defines which Rust toolchain to use 45 | - The toolchain will be `nightly` or `esp` depending on your target 46 | - `src/bin/main.rs` 47 | - The main source file of the newly created project 48 | - For details, see the [Understanding `main.rs`][main-rs] section below 49 | - `src/lib.rs` 50 | - This tells the Rust compiler that this code doesn't use `libstd` 51 | - `.vscode/settings.json` 52 | - Defines a set of settings for Visual Studio Code to make Rust Analyzer work. 53 | 54 | [esp-generate]: https://github.com/esp-rs/esp-generate 55 | [build.rs]: https://doc.rust-lang.org/cargo/reference/build-scripts.html 56 | [main-rs]: #understanding-mainrs 57 | [cargo-toml]: https://doc.rust-lang.org/cargo/reference/manifest.html 58 | [gitignore]: https://git-scm.com/docs/gitignore 59 | [config-toml]: https://doc.rust-lang.org/cargo/reference/config.html 60 | [rust-toolchain-toml]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file 61 | 62 | ### Understanding `main.rs` 63 | 64 | ```rust,ignore 65 | 1 #![no_std] 66 | 2 #![no_main] 67 | ``` 68 | 69 | - `#![no_std]` 70 | - This tells the Rust compiler that this code doesn't use `libstd` 71 | - `#![no_main]` 72 | - The `no_main` attribute says that this program won't use the standard main interface, which is usually used when a full operating system is available. Instead of the standard main, we'll use the entry attribute from the `esp-riscv-rt` crate to define a custom entry point. In this program, we have named the entry point `main`, but any other name could have been used. The entry point function must be a [diverging function][diverging-function]. I.e. it has the signature `fn foo() -> !`; this type indicates that the function never returns – which means that the program never terminates. 73 | 74 | ```rust,ignore 75 | 4 use esp_backtrace as _; 76 | 5 use esp_hal::delay::Delay; 77 | 6 use esp_hal::prelude::*; 78 | 7 use log::info; 79 | ``` 80 | - `use esp_backtrace as _;` 81 | - Since we are in a bare-metal environment, we need a panic handler that runs if a panic occurs in code 82 | - There are a few different crates you can use (e.g `panic-halt`) but `esp-backtrace` provides an implementation that prints the address of a backtrace - together with `espflash` these addresses can get decoded into source code locations 83 | - `use esp_hal::delay::Delay;` 84 | - Provides `Delay` driver implementation. 85 | - `use esp_hal::prelude::*;` 86 | - Imports the `esp-hal` [prelude][prelude]. 87 | 88 | ```rust,ignore 89 | 8 #[entry] 90 | 9 fn main() -> ! { 91 | 10 esp_println::logger::init_logger_from_env(); 92 | 11 93 | 12 let delay = Delay::new(); 94 | 13 loop { 95 | 14 info!("Hello world!"); 96 | 15 delay.delay(500.millis()); 97 | 16 } 98 | 17 } 99 | ``` 100 | 101 | Inside the `main` function we can find: 102 | - `esp_println::logger::init_logger_from_env();` 103 | - Initializes the logger, if `ESP_LOG` environment variable is defined, it will use that log level. 104 | - `let delay = Delay::new();` 105 | - Creates a delay instance. 106 | - `loop {}` 107 | - Since our function is supposed to never return, we use a loop 108 | - `info!("Hello world!");` 109 | - Creates a log message with `info` level that prints "Hello world!". 110 | - `delay.delay(500.millis());` 111 | - Waits for 500 milliseconds. 112 | 113 | [diverging-function]: https://doc.rust-lang.org/beta/rust-by-example/fn/diverging.html 114 | 115 | ## Running the Code 116 | 117 | Building and running the code is as easy as 118 | 119 | ```shell 120 | cargo run --release 121 | ``` 122 | 123 | This builds the code according to the configuration and executes [`espflash`][espflash] to flash the code to the board. 124 | 125 | Since our [`runner` configuration][runner-config] also passes the `--monitor` argument to [`espflash`][espflash], we can see what the code is printing. 126 | 127 | Make sure that you have [`espflash`][espflash] installed, otherwise this step will fail. To install [`espflash`][espflash]: 128 | `cargo install espflash` 129 | 130 | You should see something similar to this: 131 | 132 | ```text 133 | ... 134 | [2024-11-14T09:29:32Z INFO ] Serial port: '/dev/ttyUSB0' 135 | [2024-11-14T09:29:32Z INFO ] Connecting... 136 | [2024-11-14T09:29:32Z INFO ] Using flash stub 137 | [2024-11-14T09:29:33Z WARN ] Setting baud rate higher than 115,200 can cause issues 138 | Chip type: esp32c3 (revision v0.3) 139 | Crystal frequency: 40 MHz 140 | Flash size: 4MB 141 | Features: WiFi, BLE 142 | MAC address: a0:76:4e:5a:d2:c8 143 | App/part. size: 76,064/4,128,768 bytes, 1.84% 144 | [00:00:00] [========================================] 13/13 0x0 145 | [00:00:00] [========================================] 1/1 0x8000 146 | [00:00:00] [========================================] 11/11 0x10000 147 | [2024-11-14T09:29:35Z INFO ] Flashing has completed! 148 | Commands: 149 | CTRL+R Reset chip 150 | CTRL+C Exit 151 | ... 152 | INFO - Hello world! 153 | ``` 154 | 155 | What you see here are messages from the first and second stage bootloader, and then, our "Hello world" message! 156 | 157 | And that is exactly what the code is doing. 158 | 159 | You can reboot with `CTRL+R` or exit with `CTRL+C`. 160 | 161 | If you encounter any issues while building the project, please, see the [Troubleshooting][troubleshooting] chapter. 162 | 163 | 164 | [prelude]: https://doc.rust-lang.org/reference/names/preludes.html 165 | [espflash]: https://github.com/esp-rs/espflash/tree/main/espflash 166 | [runner-config]: https://doc.rust-lang.org/cargo/reference/config.html#targettriplerunner 167 | [troubleshooting]: ../../troubleshooting/index.md 168 | -------------------------------------------------------------------------------- /LICENSE-APACHE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /rust-doc-style-guide.md: -------------------------------------------------------------------------------- 1 | 2 | # Rust Documentation Style Guide 3 | 4 | As [The Rust RFC Book](https://rust-lang.github.io/rfcs/2436-style-guide.html#drawbacks) states: 5 | 6 | > One can level some criticisms at having a style guide: 7 | > 8 | > - It is bureaucratic, gives developers more to worry about, and crushes creativity. 9 | > - There are edge cases where the style rules make code look worse (e.g., around FFI). 10 | > 11 | > However, these are heavily out-weighed by the benefits. 12 | 13 | The style guide is based on the best practices collected from the following books: 14 | 15 | - [The Rust Programming Language](https://doc.rust-lang.org/book/foreword.html) 16 | - [The Embedded Rust Book](https://docs.rust-embedded.org/book/intro/index.html) 17 | - [The rustup book](https://rust-lang.github.io/rustup/installation/windows.html) 18 | - [The Cargo Book](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html) 19 | - [The rustc book](https://doc.rust-lang.org/nightly/rustc/targets/index.html) 20 | - [The Rust on ESP Book](https://esp-rs.github.io/book/) 21 | 22 | 23 | ## Contents of This Style Guide 24 | 25 | - [Heading Titles](#heading-titles) 26 | - [Capitalization](#capitalization) 27 | - [Linking](#linking) 28 | - [Adding Links](#adding-links) 29 | - [Formatting](#formatting) 30 | - [Lists](#lists) 31 | - [Types](#types) 32 | - [Formatting](#formatting-1) 33 | - [Using `monospace`](#using-monospace) 34 | - [Monospace and Other Types of Formatting](#monospace-and-other-types-of-formatting) 35 | - [Using _Italics_](#using-italics) 36 | - [Mode of Narration](#mode-of-narration) 37 | - [Terminology](#terminology) 38 | - [Recommended Terms](#recommended-terms) 39 | - [Admonitions](#admonitions) 40 | - [Appendix A Existing Style Guides](#appendix-a-existing-style-guides) 41 | - [Documentation](#documentation) 42 | - [Code](#code) 43 | 44 | ## Heading Titles 45 | 46 | The books on Rust usually have heading titles based on nouns or gerunds: 47 | 48 | > **Design Patterns**
49 | > **Using Structs to Structure Related Data** 50 | 51 | ### Capitalization 52 | 53 | In heading titles, capitalize the first letter of every word **except for**: 54 | 55 | - Articles (a, an, the); unless an article is the first word. 56 | 57 | > **Defining an Enum**
58 | > **A First Attempt at Rust** 59 | 60 | - Coordinating conjunctions (and, but, for, or, nor). 61 | 62 | > **Packages and Crates** 63 | 64 | - Prepositions of four letters or less; unless these prepositions are the first or last words. 65 | - Prepositions of _five_ letters and above should be capitalized (Before, Through, Versus, Among, Under, Between, Without, etc.). 66 | 67 | > **Peripherals as State Machines** 68 | 69 | Do not capitalize names of functions, commands, packages, websites, etc. 70 | 71 | > **What is `rustc`**
72 | > **Publishing on crates.io** 73 | 74 | See also, the [Using `monospace`](#using-monospace) section. 75 | 76 | In hyphenated words, do not capitalize the parts following the hyphens. 77 | 78 | > **Built-in Targets**
79 | > **Allowed-by-default Lints** 80 | 81 | ## Linking 82 | 83 | ### Adding Links 84 | 85 | To simplify link maintenance, follow the rules below: 86 | 87 | - Use [link variables][stackoverflow-link-var] with variable names that give a clue on where the link leads. 88 | - Define link variables right before the end of the section/subsection where they are used. 89 | 90 | [stackoverflow-link-var]: https://stackoverflow.com/a/27784490/10308406 91 | 92 | Example: 93 | 94 | ```md 95 | [`espup`][espup-github] is a tool that simplifies installing and maintaining the components required to develop Rust applications. 96 | 97 | [espup-github]: https://github.com/esp-rs/espup 98 | ``` 99 | 100 | ### Formatting 101 | 102 | The books on Rust usually use the following link formatting: 103 | 104 | > As mentioned in the [Environment Variables](https://rust-lang.github.io/rustup/installation/index.html) section, ... 105 | 106 | > For more details, see the [Windows](rustup-book-windows) chapter in The rustup book. 107 | 108 | [The Rust Programming Language](https://github.com/rust-lang/book/blob/main/style-guide.md) book also suggests: 109 | 110 | - Make intra-book links relative, so they work both online and locally 111 | 112 | Do NOT turn long phrases into links 113 | 114 | > ❌ See the [Rust Reference’s section on constant evaluation](https://doc.rust-lang.org/book/ch03-01-variables-and-mutability.html) for more information on what operations can be used when declaring constants. 115 | 116 | Also, consider the following: 117 | 118 | - Do not provide a link to the same location repeatedly in the same or adjacent paragraphs without a good reason, especially using different link text. 119 | - Do not use the same link text to refer to different locations. 120 | 121 | > `espup` might have a section in a book and a github repo. In this case, see the [`espup`](https://esp-rs.github.io/book/installation/index.html#risc-v-and-xtensa-targets) section and [`espup` repo](https://github.com/esp-rs/espup). 122 | 123 | See also, the [Using `monospace`](#using-monospace) section. 124 | 125 | ## Lists 126 | 127 | ### Types 128 | 129 | The following types of lists are usually used in documentation: 130 | 131 | - **Bullet list** -- use it if the order or items is not important 132 | - **Numbered list** -- use it if the order of items is important, such as when describing a process 133 | - **Procedure** -- special type of numbered list that gives steps to achieve some goal (to achieve this, do this); for an example of a procedure, see the [Usage](https://doc.rust-lang.org/nightly/rustc/profile-guided-optimization.html#usage) section in The rustc book. 134 | 135 | ### Formatting 136 | 137 | The books on Rust usually use the following list formatting: 138 | 139 | - Finish an introductory sentence with a colon. 140 | - Capitalize the first letter of each bullet point. 141 | 142 | > Using C or C++ inside of a Rust project consists of two major parts: 143 | > 144 | > - Wrapping the exposed C API for use with Rust 145 | > - Building your C or C++ code to be integrated with the Rust code 146 | 147 | - If a bullet point is a full sentence, you can end it with a full stop. 148 | - If a list has at least one full stop, end all other list items with a full stop. 149 | 150 | > To reliably interact with these peripherals: 151 | > 152 | > - Always use `volatile` methods to read or write to peripheral memory, as it can change at any time. 153 | > - In software, we should be able to share any number of read-only accesses to these peripherals. 154 | > - If some software should have read-write access to a peripheral, it should hold the only reference to that peripheral. 155 | 156 | - For longer list items, consider using a summary word of phrase to make content [scannable](https://learn.microsoft.com/en-us/style-guide/scannable-content/). 157 | 158 | > If you run Windows on your host machine, make sure ... 159 | > 160 | > - **MSVC**: Recommended ABI, included in ... 161 | > - **GNU**: ABI used by the GCC toolchain ... 162 | 163 | - For an example using bold font, see the list in the [Modules Cheat Sheet](https://doc.rust-lang.org/book/ch07-02-defining-modules-to-control-scope-and-privacy.html#modules-cheat-sheet) section in The Rust Programming Language book. 164 | - For an example using monospace font, see the [Panicking](https://docs.rust-embedded.org/book/start/panicking.html#panicking) section in The Embedded Rust Book. 165 | 166 | ## Using `monospace` 167 | 168 | Use monospace font for the following items: 169 | 170 | - Code snippets 171 | 172 | The [Installation](https://doc.rust-lang.org/book/ch01-01-installation.html) chapter in the Rust Programming Language book suggests: 173 | 174 | - Start the terminal commands with `$` 175 | - Output of previous commands should not start with `$` 176 | - For PowerShell-specific examples, use `>` instead of `$` 177 | 178 | [The Rust Programming Language](https://github.com/rust-lang-ja/book-ja/blob/master-ja/style-guide.md) book also suggests: 179 | 180 | - Use `bash` syntax highlighting 181 | 182 | - Rust declarations: commands, functions, arguments, parameters, flags, variables 183 | - In-line command line output 184 | 185 | > Writing a program that prints `Hello, world!` 186 | 187 | - Data types: `i8`, `u128` 188 | - Names of crates, traits, libraries, 189 | - Command line tools, plugins, packages 190 | - Files: `config.toml` 191 | - Images and containers: `idf-rust` 192 | - Architectures and targets 193 | 194 | > The `RISC-V` and `Xtensa` architectures. 195 | 196 | ### Monospace and Other Types of Formatting 197 | 198 | Monospace font can also be used in: 199 | 200 | - links 201 | 202 | > [`String`](https://doc.rust-lang.org/std/string/struct.String.html) is a string type provided by ... 203 | 204 | - headings 205 | 206 | > **A `no_std` Rust Environment** 207 | 208 | ## Using _Italics_ 209 | 210 | - Introduce new terms 211 | 212 | > Each value in Rust has an _owner_. 213 | > A _hash map_ allows you to associate a value with a particular key. 214 | 215 | - Emphasize important concepts or words 216 | 217 | > When `s` comes _into_ scope, it is valid. It remains valid until it goes _out of_ scope. 218 | 219 | - Do NOT use italics with Espressif product names, such as ESP32. 220 | 221 | ## Mode of Narration 222 | 223 | - Use _the first person_ (we) when introducing a tutorial or explaining how things will be done. The reader will feel like being on the same team with the authors working side by side. 224 | 225 | > We'll start writing a program for the LM3S6965, a Cortex-M3 microcontroller. We have chosen this as our initial target because it can be emulated using QEMU so you don't need to fiddle with hardware in this section, and we can focus on the tooling and the development process. 226 | 227 | - Use _the second person_ (you) when describing what the reader should do while installing software, following a tutorial or a procedure. However, in most cases you can use imperative mood as if giving orders to the readers. It makes instructions much shorter and clearer. 228 | 229 | > 1\. Install `cargo-generate` 230 | > 231 | > `cargo install cargo-generate` 232 | > 233 | > 2\. Generate a new project 234 | > 235 | > `cargo generate --git https://github.com/rust-embedded/cortex-m-quickstart` 236 | 237 | - Use _the third person_ (the user, it) when describing how things work from the perspective of hardware or software 238 | 239 | > A driver has to be initialized with an instance of type that implements a certain `trait` of the embedded-hal which is ensured via trait bound and provides its own type instance with a custom set of methods allowing to interact with the driven device. 240 | 241 | ## Terminology 242 | 243 | This chapter lists the terms that have inconsistencies in spelling, usage, etc. 244 | 245 | If you spot other issues with terminology, please add the terms here in alphabetical order using the formatting as follows: 246 | 247 | - _Recommended term_ 248 | - Avoid: Add typical phrases in which this term is found 249 | - Use: Add recommended phrases 250 | - Note: Add more information if needed 251 | 252 | ### Recommended Terms 253 | 254 | - _Cargo_ 255 | - Note: always use uppercase _C_ 256 | - ESP-IDF or esp-idf 257 | - Use: esp-idf when writing about the esp-idf repo 258 | - Use: ESP-IDF when writing about the ESP-IDF framework or ESP-IDF programming guide 259 | - `no_std` 260 | - Note: see `std` 261 | - _Product_ 262 | - Avoid: Espressif SoCs 263 | - Use: Espressif products 264 | - Note: In the content of running applications, suggested as an umbrella term for Espressif chips, modules, development boards, etc. Otherwise, it might be potentially ambiguous that running an app on an SoC is the same as running it on a module. 265 | - _SoC_ 266 | - Avoid: _chip_ 267 | - Note: see also _product_ 268 | - `std` / `no_std` 269 | - Use only if necessary: bare metal development, hosted environment, Standard library, Core library 270 | - Use `std` / `no_std` by default in patterns, such as: 271 | - write, build, or choose between `std` / `no_std` applications 272 | - requires `std` for ... 273 | - use `std` for ... 274 | - compile in an `std` environment 275 | - support for `no_std` requires ... (`std` support) 276 | - using the `std` / `no_std` approach 277 | - `std` projects / templates / features 278 | - `std` / `no_std` development 279 | - _VS Code_ 280 | - Use VS Code by default 281 | - Use only if necessary: Visual Studio Code 282 | 283 | ## Admonitions 284 | 285 | Use the following formatting for notes and warnings: 286 | 287 | - Note 288 | 289 | > ⚠️ **Note**: A note covering an important point or idea. Use sparingly or the readers will start ignoring them. 290 | 291 | - Warning 292 | 293 | > 🚨 **Warning**: Use in critical circumstances only, e.g., for irreversible actions or actions potentially harmful to hardware, software, etc. 294 | 295 | In markdown: 296 | 297 | ```md 298 | > ⚠️ **Note**: Write your note. 299 | ``` 300 | 301 | ## Appendix A Existing Style Guides 302 | 303 | ### Documentation 304 | 305 | - [The Rust Programming Language Style Guide](https://github.com/rust-lang-ja/book-ja/blob/master-ja/style-guide.md) 306 | 307 | ### Code 308 | 309 | - [Style Guidelines](https://doc.rust-lang.org/1.0.0/style/README.html) 310 | - [The Rust RFC Book](https://rust-lang.github.io/rfcs/2436-style-guide.html), chapter _Style Guide_ 311 | - [Rust API Guidelines](https://rust-lang.github.io/api-guidelines/) 312 | - [Rust Style Guide](https://riptutorial.com/rust/topic/4620/rust-style-guide) (riptutorial.com) 313 | - [Rust Style Guide](https://github.com/rust-lang/style-team/blob/master/guide/guide.md) (github.com/rust-lang) 314 | 315 | -------------------------------------------------------------------------------- /LICENSE-CC-BY-SA: -------------------------------------------------------------------------------- 1 | Attribution-ShareAlike 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution-ShareAlike 4.0 International Public 58 | License 59 | 60 | By exercising the Licensed Rights (defined below), You accept and agree 61 | to be bound by the terms and conditions of this Creative Commons 62 | Attribution-ShareAlike 4.0 International Public License ("Public 63 | License"). To the extent this Public License may be interpreted as a 64 | contract, You are granted the Licensed Rights in consideration of Your 65 | acceptance of these terms and conditions, and the Licensor grants You 66 | such rights in consideration of benefits the Licensor receives from 67 | making the Licensed Material available under these terms and 68 | conditions. 69 | 70 | 71 | Section 1 -- Definitions. 72 | 73 | a. Adapted Material means material subject to Copyright and Similar 74 | Rights that is derived from or based upon the Licensed Material 75 | and in which the Licensed Material is translated, altered, 76 | arranged, transformed, or otherwise modified in a manner requiring 77 | permission under the Copyright and Similar Rights held by the 78 | Licensor. For purposes of this Public License, where the Licensed 79 | Material is a musical work, performance, or sound recording, 80 | Adapted Material is always produced where the Licensed Material is 81 | synched in timed relation with a moving image. 82 | 83 | b. Adapter's License means the license You apply to Your Copyright 84 | and Similar Rights in Your contributions to Adapted Material in 85 | accordance with the terms and conditions of this Public License. 86 | 87 | c. BY-SA Compatible License means a license listed at 88 | creativecommons.org/compatiblelicenses, approved by Creative 89 | Commons as essentially the equivalent of this Public License. 90 | 91 | d. Copyright and Similar Rights means copyright and/or similar rights 92 | closely related to copyright including, without limitation, 93 | performance, broadcast, sound recording, and Sui Generis Database 94 | Rights, without regard to how the rights are labeled or 95 | categorized. For purposes of this Public License, the rights 96 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 97 | Rights. 98 | 99 | e. Effective Technological Measures means those measures that, in the 100 | absence of proper authority, may not be circumvented under laws 101 | fulfilling obligations under Article 11 of the WIPO Copyright 102 | Treaty adopted on December 20, 1996, and/or similar international 103 | agreements. 104 | 105 | f. Exceptions and Limitations means fair use, fair dealing, and/or 106 | any other exception or limitation to Copyright and Similar Rights 107 | that applies to Your use of the Licensed Material. 108 | 109 | g. License Elements means the license attributes listed in the name 110 | of a Creative Commons Public License. The License Elements of this 111 | Public License are Attribution and ShareAlike. 112 | 113 | h. Licensed Material means the artistic or literary work, database, 114 | or other material to which the Licensor applied this Public 115 | License. 116 | 117 | i. Licensed Rights means the rights granted to You subject to the 118 | terms and conditions of this Public License, which are limited to 119 | all Copyright and Similar Rights that apply to Your use of the 120 | Licensed Material and that the Licensor has authority to license. 121 | 122 | j. Licensor means the individual(s) or entity(ies) granting rights 123 | under this Public License. 124 | 125 | k. Share means to provide material to the public by any means or 126 | process that requires permission under the Licensed Rights, such 127 | as reproduction, public display, public performance, distribution, 128 | dissemination, communication, or importation, and to make material 129 | available to the public including in ways that members of the 130 | public may access the material from a place and at a time 131 | individually chosen by them. 132 | 133 | l. Sui Generis Database Rights means rights other than copyright 134 | resulting from Directive 96/9/EC of the European Parliament and of 135 | the Council of 11 March 1996 on the legal protection of databases, 136 | as amended and/or succeeded, as well as other essentially 137 | equivalent rights anywhere in the world. 138 | 139 | m. You means the individual or entity exercising the Licensed Rights 140 | under this Public License. Your has a corresponding meaning. 141 | 142 | 143 | Section 2 -- Scope. 144 | 145 | a. License grant. 146 | 147 | 1. Subject to the terms and conditions of this Public License, 148 | the Licensor hereby grants You a worldwide, royalty-free, 149 | non-sublicensable, non-exclusive, irrevocable license to 150 | exercise the Licensed Rights in the Licensed Material to: 151 | 152 | a. reproduce and Share the Licensed Material, in whole or 153 | in part; and 154 | 155 | b. produce, reproduce, and Share Adapted Material. 156 | 157 | 2. Exceptions and Limitations. For the avoidance of doubt, where 158 | Exceptions and Limitations apply to Your use, this Public 159 | License does not apply, and You do not need to comply with 160 | its terms and conditions. 161 | 162 | 3. Term. The term of this Public License is specified in Section 163 | 6(a). 164 | 165 | 4. Media and formats; technical modifications allowed. The 166 | Licensor authorizes You to exercise the Licensed Rights in 167 | all media and formats whether now known or hereafter created, 168 | and to make technical modifications necessary to do so. The 169 | Licensor waives and/or agrees not to assert any right or 170 | authority to forbid You from making technical modifications 171 | necessary to exercise the Licensed Rights, including 172 | technical modifications necessary to circumvent Effective 173 | Technological Measures. For purposes of this Public License, 174 | simply making modifications authorized by this Section 2(a) 175 | (4) never produces Adapted Material. 176 | 177 | 5. Downstream recipients. 178 | 179 | a. Offer from the Licensor -- Licensed Material. Every 180 | recipient of the Licensed Material automatically 181 | receives an offer from the Licensor to exercise the 182 | Licensed Rights under the terms and conditions of this 183 | Public License. 184 | 185 | b. Additional offer from the Licensor -- Adapted Material. 186 | Every recipient of Adapted Material from You 187 | automatically receives an offer from the Licensor to 188 | exercise the Licensed Rights in the Adapted Material 189 | under the conditions of the Adapter's License You apply. 190 | 191 | c. No downstream restrictions. You may not offer or impose 192 | any additional or different terms or conditions on, or 193 | apply any Effective Technological Measures to, the 194 | Licensed Material if doing so restricts exercise of the 195 | Licensed Rights by any recipient of the Licensed 196 | Material. 197 | 198 | 6. No endorsement. Nothing in this Public License constitutes or 199 | may be construed as permission to assert or imply that You 200 | are, or that Your use of the Licensed Material is, connected 201 | with, or sponsored, endorsed, or granted official status by, 202 | the Licensor or others designated to receive attribution as 203 | provided in Section 3(a)(1)(A)(i). 204 | 205 | b. Other rights. 206 | 207 | 1. Moral rights, such as the right of integrity, are not 208 | licensed under this Public License, nor are publicity, 209 | privacy, and/or other similar personality rights; however, to 210 | the extent possible, the Licensor waives and/or agrees not to 211 | assert any such rights held by the Licensor to the limited 212 | extent necessary to allow You to exercise the Licensed 213 | Rights, but not otherwise. 214 | 215 | 2. Patent and trademark rights are not licensed under this 216 | Public License. 217 | 218 | 3. To the extent possible, the Licensor waives any right to 219 | collect royalties from You for the exercise of the Licensed 220 | Rights, whether directly or through a collecting society 221 | under any voluntary or waivable statutory or compulsory 222 | licensing scheme. In all other cases the Licensor expressly 223 | reserves any right to collect such royalties. 224 | 225 | 226 | Section 3 -- License Conditions. 227 | 228 | Your exercise of the Licensed Rights is expressly made subject to the 229 | following conditions. 230 | 231 | a. Attribution. 232 | 233 | 1. If You Share the Licensed Material (including in modified 234 | form), You must: 235 | 236 | a. retain the following if it is supplied by the Licensor 237 | with the Licensed Material: 238 | 239 | i. identification of the creator(s) of the Licensed 240 | Material and any others designated to receive 241 | attribution, in any reasonable manner requested by 242 | the Licensor (including by pseudonym if 243 | designated); 244 | 245 | ii. a copyright notice; 246 | 247 | iii. a notice that refers to this Public License; 248 | 249 | iv. a notice that refers to the disclaimer of 250 | warranties; 251 | 252 | v. a URI or hyperlink to the Licensed Material to the 253 | extent reasonably practicable; 254 | 255 | b. indicate if You modified the Licensed Material and 256 | retain an indication of any previous modifications; and 257 | 258 | c. indicate the Licensed Material is licensed under this 259 | Public License, and include the text of, or the URI or 260 | hyperlink to, this Public License. 261 | 262 | 2. You may satisfy the conditions in Section 3(a)(1) in any 263 | reasonable manner based on the medium, means, and context in 264 | which You Share the Licensed Material. For example, it may be 265 | reasonable to satisfy the conditions by providing a URI or 266 | hyperlink to a resource that includes the required 267 | information. 268 | 269 | 3. If requested by the Licensor, You must remove any of the 270 | information required by Section 3(a)(1)(A) to the extent 271 | reasonably practicable. 272 | 273 | b. ShareAlike. 274 | 275 | In addition to the conditions in Section 3(a), if You Share 276 | Adapted Material You produce, the following conditions also apply. 277 | 278 | 1. The Adapter's License You apply must be a Creative Commons 279 | license with the same License Elements, this version or 280 | later, or a BY-SA Compatible License. 281 | 282 | 2. You must include the text of, or the URI or hyperlink to, the 283 | Adapter's License You apply. You may satisfy this condition 284 | in any reasonable manner based on the medium, means, and 285 | context in which You Share Adapted Material. 286 | 287 | 3. You may not offer or impose any additional or different terms 288 | or conditions on, or apply any Effective Technological 289 | Measures to, Adapted Material that restrict exercise of the 290 | rights granted under the Adapter's License You apply. 291 | 292 | 293 | Section 4 -- Sui Generis Database Rights. 294 | 295 | Where the Licensed Rights include Sui Generis Database Rights that 296 | apply to Your use of the Licensed Material: 297 | 298 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 299 | to extract, reuse, reproduce, and Share all or a substantial 300 | portion of the contents of the database; 301 | 302 | b. if You include all or a substantial portion of the database 303 | contents in a database in which You have Sui Generis Database 304 | Rights, then the database in which You have Sui Generis Database 305 | Rights (but not its individual contents) is Adapted Material, 306 | 307 | including for purposes of Section 3(b); and 308 | c. You must comply with the conditions in Section 3(a) if You Share 309 | all or a substantial portion of the contents of the database. 310 | 311 | For the avoidance of doubt, this Section 4 supplements and does not 312 | replace Your obligations under this Public License where the Licensed 313 | Rights include other Copyright and Similar Rights. 314 | 315 | 316 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 317 | 318 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 319 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 320 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 321 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 322 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 323 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 324 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 325 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 326 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 327 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 328 | 329 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 330 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 331 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 332 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 333 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 334 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 335 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 336 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 337 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 338 | 339 | c. The disclaimer of warranties and limitation of liability provided 340 | above shall be interpreted in a manner that, to the extent 341 | possible, most closely approximates an absolute disclaimer and 342 | waiver of all liability. 343 | 344 | 345 | Section 6 -- Term and Termination. 346 | 347 | a. This Public License applies for the term of the Copyright and 348 | Similar Rights licensed here. However, if You fail to comply with 349 | this Public License, then Your rights under this Public License 350 | terminate automatically. 351 | 352 | b. Where Your right to use the Licensed Material has terminated under 353 | Section 6(a), it reinstates: 354 | 355 | 1. automatically as of the date the violation is cured, provided 356 | it is cured within 30 days of Your discovery of the 357 | violation; or 358 | 359 | 2. upon express reinstatement by the Licensor. 360 | 361 | For the avoidance of doubt, this Section 6(b) does not affect any 362 | right the Licensor may have to seek remedies for Your violations 363 | of this Public License. 364 | 365 | c. For the avoidance of doubt, the Licensor may also offer the 366 | Licensed Material under separate terms or conditions or stop 367 | distributing the Licensed Material at any time; however, doing so 368 | will not terminate this Public License. 369 | 370 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 371 | License. 372 | 373 | 374 | Section 7 -- Other Terms and Conditions. 375 | 376 | a. The Licensor shall not be bound by any additional or different 377 | terms or conditions communicated by You unless expressly agreed. 378 | 379 | b. Any arrangements, understandings, or agreements regarding the 380 | Licensed Material not stated herein are separate from and 381 | independent of the terms and conditions of this Public License. 382 | 383 | 384 | Section 8 -- Interpretation. 385 | 386 | a. For the avoidance of doubt, this Public License does not, and 387 | shall not be interpreted to, reduce, limit, restrict, or impose 388 | conditions on any use of the Licensed Material that could lawfully 389 | be made without permission under this Public License. 390 | 391 | b. To the extent possible, if any provision of this Public License is 392 | deemed unenforceable, it shall be automatically reformed to the 393 | minimum extent necessary to make it enforceable. If the provision 394 | cannot be reformed, it shall be severed from this Public License 395 | without affecting the enforceability of the remaining terms and 396 | conditions. 397 | 398 | c. No term or condition of this Public License will be waived and no 399 | failure to comply consented to unless expressly agreed to by the 400 | Licensor. 401 | 402 | d. Nothing in this Public License constitutes or may be interpreted 403 | as a limitation upon, or waiver of, any privileges and immunities 404 | that apply to the Licensor or You, including from the legal 405 | processes of any jurisdiction or authority. 406 | 407 | 408 | ======================================================================= 409 | 410 | Creative Commons is not a party to its public 411 | licenses. Notwithstanding, Creative Commons may elect to apply one of 412 | its public licenses to material it publishes and in those instances 413 | will be considered the “Licensor.” The text of the Creative Commons 414 | public licenses is dedicated to the public domain under the CC0 Public 415 | Domain Dedication. Except for the limited purpose of indicating that 416 | material is shared under a Creative Commons public license or as 417 | otherwise permitted by the Creative Commons policies published at 418 | creativecommons.org/policies, Creative Commons does not authorize the 419 | use of the trademark "Creative Commons" or any other trademark or logo 420 | of Creative Commons without its prior written consent including, 421 | without limitation, in connection with any unauthorized modifications 422 | to any of its public licenses or any other arrangements, 423 | understandings, or agreements concerning use of licensed material. For 424 | the avoidance of doubt, this paragraph does not form part of the 425 | public licenses. 426 | 427 | Creative Commons may be contacted at creativecommons.org. 428 | --------------------------------------------------------------------------------