diff --git a/book.toml b/book.toml index ef2d8261..911d3cc2 100644 --- a/book.toml +++ b/book.toml @@ -11,5 +11,12 @@ edition = "2018" git-repository-url = "https://github.com/esp-rs/book" additional-js = ["assets/mermaid.min.js", "assets/mermaid-init.js"] +[output.html.redirect] +"/overview/bare-metal.html" = "https://esp-rs.github.io/book/overview/using-the-core-library.html" +"/tooling/text-editors-and-ides.html" = "https://esp-rs.github.io/book/tooling/visual-studio-code.html" +"/debugging/vscode-debugging.html" = "https://esp-rs.github.io/book/debugging/vscode.html" +"/writing-your-own-application/no-std-applications/understanding-esp-template.html" = "https://esp-rs.github.io/book/writing-your-own-application/generate-project/esp-template.html" +"installation/installation.html" = "https://esp-rs.github.io/book/installation/index.html" + [preprocessor.mermaid] command = "mdbook-mermaid" diff --git a/rust-doc-style-guide.md b/rust-doc-style-guide.md index 3e41ede8..e93046de 100644 --- a/rust-doc-style-guide.md +++ b/rust-doc-style-guide.md @@ -41,7 +41,6 @@ The style guide is based on the best practices collected from the following book - [Documentation](#documentation) - [Code](#code) - ## Heading Titles The books on Rust usually have the heading titles based on nouns or gerunds: @@ -79,7 +78,6 @@ In hyphenated words, do not capitalize the parts following the hyphens. > **Built-in Targets**
> **Allowed-by-default Lints** - ## Linking ### Adding Links @@ -87,13 +85,13 @@ In hyphenated words, do not capitalize the parts following the hyphens. To simplify link maintenance, follow the rules below: - Use [link variables][stackoverflow-link-var] with variable names that give a clue on where the link leads. -- Define link variables right after the paragraphs where they are used. +- Define link variables right before the end of the section/subsection where they are used. [stackoverflow-link-var]: https://stackoverflow.com/a/27784490/10308406 Example: -``` +```md [`espup`][espup-github] is a tool that simplifies installing and maintaining the components required to develop Rust applications. [espup-github]: https://github.com/esp-rs/espup @@ -120,7 +118,7 @@ Also take into account the following - 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. - Do not use the same link text to refer to different locations. - > `espup` might have a section in a book and a github repo. In this case, see the [`espup`](#espup) section and [`espup` repo](https://hackmd.io/-cf0jVTqRqm9O7GM5JgLiA?both). + > `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). See also, the [Using `monospace`](#using-monospace) section. @@ -165,7 +163,6 @@ The books on Rust usually use the following list formatting: - 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. - 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. - ## Using `monospace` Use monospace font for the following items: @@ -208,7 +205,6 @@ Monospace font can also be used in: > **A `no_std` Rust Environment** - ## Using _Italics_ - Introduce new terms @@ -222,7 +218,6 @@ Monospace font can also be used in: - Do NOT use italics with Espressif product names, such as ESP32. - ## Mode of Narration - 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. @@ -243,7 +238,6 @@ Monospace font can also be used in: > 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. - ## Terminology This chapter lists the terms that have inconsistencies in spelling, usage, etc. diff --git a/src/SUMMARY.md b/src/SUMMARY.md index d8e7afa4..6db926b2 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,10 +1,15 @@ # Summary - [Introduction](./introduction.md) -- [Ecosystem Overview](./overview/index.md) +- [Overview of Development Approaches](./overview/index.md) - [Using the Standard Library (`std`)](./overview/using-the-standard-library.md) - - [Bare Metal (`no_std`)](./overview/bare-metal.md) + - [Using the Core Library (`no_std`)](./overview/using-the-core-library.md) - [Setting Up a Development Environment](./installation/index.md) + - [Rust installation](./installation/rust.md) + - [RISC-V targets only](./installation/riscv.md) + - [RISC-V and Xtensa targets](./installation/riscv-and-xtensa.md) + - [`std` Development Requirements](./installation/std-requirements.md) + - [Using Containers](./installation/using-containers.md) - [Writing Your Own Application](./writing-your-own-application/index.md) - [Generating Projects from Templates](./writing-your-own-application/generate-project/index.md) - [Understanding esp-template](./writing-your-own-application/generate-project/esp-template.md) @@ -12,12 +17,12 @@ - [Writing `no_std` Applications](./writing-your-own-application/nostd.md) - [Writing `std` Applications](./writing-your-own-application/std.md) - [Tooling](./tooling/index.md) - - [Visual Studio Code](./tooling/text-editors-and-ides.md) + - [Visual Studio Code](./tooling/visual-studio-code.md) - [espflash](./tooling/espflash.md) - [Debugging](./tooling/debugging/index.md) - [probe-rs](./tooling/debugging/probe-rs.md) - [OpenOCD](./tooling/debugging/openocd.md) - - [Debugging in Visual Studio Code](./tooling/debugging/vscode-debugging.md) + - [Debugging in Visual Studio Code](./tooling/debugging/vscode.md) - [Simulating](./tooling/simulating/index.md) - [Wokwi](./tooling/simulating/wokwi.md) - [QEMU](tooling/simulating/qemu.md) diff --git a/src/installation/index.md b/src/installation/index.md index 3a697209..435bcc13 100644 --- a/src/installation/index.md +++ b/src/installation/index.md @@ -9,207 +9,12 @@ To set up the development environment, do the following: - [`RISC-V` targets only][risc-v-targets] - [`RISC-V` and `Xtensa` targets][rics-v-xtensa-targets] -As mentioned in the installation procedures below, for `std` development also don't forget to install [`std` Development Requirements][rust-esp-book-std-requirements]. +Regardless of the target architecture, for `std` development also don't forget to install [`std` Development Requirements][rust-esp-book-std-requirements]. Please note that you can host the development environment in a [container][use-containers]. -[install-rust]: #install-rust -[risc-v-targets]: #risc-v-targets-only -[rics-v-xtensa-targets]: #risc-v-and-xtensa-targets -[use-containers]: #using-containers - -## Install Rust - -Make sure you have [Rust][rust-lang-org] installed. If not, see the instructions on the [rustup][rustup.rs-website] website. - -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. -- **MSVC**: Recommended ABI, included in the list of `rustup` default requirements. Use it for interoperability with the software produced by Visual Studio. -- **GNU**: ABI used by the GCC toolchain. Install it yourself for interoperability with the software built with the MinGW/MSYS2 toolchain. - -> **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. - -See also [alternative installation methods][rust-alt-installation]. - -[rustup.rs-website]: https://rustup.rs/ -[rust-alt-installation]: https://rust-lang.github.io/rustup/installation/other.html -[rustup-book-windows]: https://rust-lang.github.io/rustup/installation/windows.html -[rust-lang-org]: https://www.rust-lang.org/ - -## RISC-V targets only - -To build Rust applications for the Espressif chips based on `RISC-V` architecture, do the following: - -1. Install the [`nightly`][rustup-book-channel-nightly] toolchain with the `rust-src` [component][rustup-book-components]: - - ```bash - rustup toolchain install nightly --component rust-src - ``` - -[rustup-book-channel-nightly]: https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust -[rustup-book-components]: https://rust-lang.github.io/rustup/concepts/components.html - - -2. Set the target: - - For `no_std` (bare-metal) applications, run: - - ```bash - rustup target add riscv32imc-unknown-none-elf # For ESP32-C2 and ESP32-C3 - rustup target add riscv32imac-unknown-none-elf # For ESP32-C6 and ESP32-H2 - ``` - - 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]. - - - For `std` applications: - - Since this target is currently [Tier 3][rust-lang-book--platform-support-tier3], it does not 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. - - - `riscv32imc-esp-espidf` for MCUs which do not support atomics, like ESP32-C2 and ESP32-C3 - - `riscv32imac-esp-espidf` for MCUs which support atomics, like ESP32-C6, ESP32-H2, and ESP32-P4 - -[rust-lang-book--platform-support-tier2]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-2 -[wiki-riscv-standard-extensions]: https://en.wikichip.org/wiki/risc-v/standard_extensions -[rust-lang-book--platform-support-tier3]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-3 -[rust-lang-book--platform-support--esp-idf]: https://doc.rust-lang.org/nightly/rustc/platform-support/esp-idf.html - - -3. To build `std` projects, you also need to install: - - [`LLVM`][llvm-website] compiler infrastructure - - Other [`std` development requirements][rust-esp-book-std-requirements] - - 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. - - -[llvm-website]: https://llvm.org/ -[rust-esp-book-std-requirements]: #std-development-requirements -[cargo-book-unstable-features]: https://doc.rust-lang.org/cargo/reference/unstable.html -[rust-esp-book-write-app-generate-project]: ../writing-your-own-application/generate-project/index.md - - -Now you should be able to build and run projects on the Espressif's `RISC-V` chips. - - -## RISC-V and Xtensa targets - -[`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. - -[espup-github]: https://github.com/esp-rs/espup - -### 1. Install `espup` - -To install `espup`, run: -```sh -cargo install espup -``` - -You can also directly download pre-compiled [release binaries] or use [cargo-binstall]. - -[release binaries]: https://github.com/esp-rs/espup/releases -[cargo-binstall]: https://github.com/cargo-bins/cargo-binstall - -### 2. Install neccesary toolchains - -Install all the necessary tools to develop Rust applications for all supported Espressif targets by running: -```sh -espup install -``` - -> **Note**: `std` applications require installing additional software covered in [`std` Development Requirements][rust-esp-book-std-requirements] - -### 3. Set up the environment variables -`espup` will create an export file that contains some environment variables required to build projects. - -On Windows (`%USERPROFILE%\export-esp.ps1`) - - There is **no need** to execute the file for Windows users. It is only created to show the modified environment variables. - -On Unix based systems (`$HOME/export-esp.sh`). There are different ways of sourcing the file: -- Source this file in every terminal: - 1. Source the export file: `. $HOME/export-esp.sh` - - This approach requires running the command in every new shell. -- Create an alias for executing the `export-esp.sh`: - 1. Copy and paste the following command to your shell’s profile (`.profile`, `.bashrc`, `.zprofile`, etc.): `alias get_esprs='. $HOME/export-esp.sh'` - 2. Refresh the configuration by restarting the terminal session or by running `source [path to profile]`, for example, `source ~/.bashrc`. - - This approach requires running the alias in every new shell. -- Add the environment variables to your shell's profile directly: - 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`. - 2. Refresh the configuration by restarting the terminal session or by running `source [path to profile]`, for example, `source ~/.bashrc`. - - This approach **does not** require any sourcing. The `export-esp.sh` script will be sourced automatically in every shell. - - -### What espup Installs - -To enable support for Espressif targets, `espup` installs the following tools: - -- Espressif Rust fork with support for Espressif targets -- `nightly` toolchain with support for `RISC-V` targets -- `LLVM` [fork][llvm-github-fork] with support for `Xtensa` targets -- [GCC toolchain][gcc-toolchain-github-fork] that links the final binary - -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]. - -> **Note**: We are making efforts to upstream our forks -> 1. Changes in `LLVM` fork. Already in progress, see the status in this [tracking issue][llvm-github-fork-upstream issue]. -> 2. Rust compiler forks. If `LLVM` changes are accepted, we will proceed with the Rust compiler changes. - - -[llvm-github-fork]: https://github.com/espressif/llvm-project -[gcc-toolchain-github-fork]: https://github.com/espressif/crosstool-NG/ -[rustup-overrides]: https://rust-lang.github.io/rustup/overrides.html -[llvm-github-fork-upstream issue]: https://github.com/espressif/llvm-project/issues/4 - - -### Other installation methods for Xtensa targets - -- Using [esp-rs/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. -- 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 is not 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-build]: https://github.com/esp-rs/rust-build#download-installer-in-bash -[esp-rs/rust repository]: https://github.com/esp-rs/rust - - -## `std` Development Requirements - -Regardless of the target architecture, make sure you have the following required tools installed to build [`std`][rust-esp-book-overview-std] applications: - -- [`python`][python-website-download]: Required by ESP-IDF -- [`git`][git-website-download]: Required by ESP-IDF -- [`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: - ```sh - cargo install ldproxy - ``` - -The std runtime uses [ESP-IDF][esp-idf-github] (Espressif IoT Development Framework) as hosted environment but, users do not 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. - - -[rust-esp-book-overview-std]: ../overview/using-the-standard-library.md -[python-website-download]: https://www.python.org/downloads/ -[git-website-download]: https://git-scm.com/downloads -[embuild-github-ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy -[esp-idf-sys-github]: https://github.com/esp-rs/esp-idf-sys -[esp-idf-github]: https://github.com/espressif/esp-idf - - -## Using Containers - -Instead of installing directly on your local system, you can host the development environment inside a container. Espressif provides the [idf-rust] image that supports both `RISC-V` and `Xtensa` target architectures and enables both `std` and `no_std` development. - -You can find numerous tags for `linux/arm64`, and `linux/amd64` platforms. - -For each Rust release, we generate the tag with the following naming convention: - -- `_` - - 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. - -There are special cases - -- `` can be `all` which indicates compatibility with all Espressif targets -- `` can be `latest` which indicates the latest release of the `Xtensa` Rust toolchain - -Depending on your operating system, you can choose any container runtime, such as [Docker], [Podman], or [Lima]. - - -[Docker]: https://www.docker.com/ -[Podman]: https://podman.io/ -[Lima]: https://github.com/lima-vm/lima -[idf-rust]: https://hub.docker.com/r/espressif/idf-rust/tags +[install-rust]: ./rust.md +[risc-v-targets]: ./riscv.md +[rics-v-xtensa-targets]: ./riscv-and-xtensa.md +[rust-esp-book-std-requirements]: ./std-requirements.md +[use-containers]: ./using-containers.md diff --git a/src/installation/riscv-and-xtensa.md b/src/installation/riscv-and-xtensa.md new file mode 100644 index 00000000..5c4d9a85 --- /dev/null +++ b/src/installation/riscv-and-xtensa.md @@ -0,0 +1,80 @@ +# RISC-V and Xtensa targets + +[`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. + +### 1. Install `espup` + +To install `espup`, run: +```shell +cargo install espup +``` + +You can also directly download pre-compiled [release binaries] or use [cargo-binstall]. + +[espup-github]: https://github.com/esp-rs/espup +[release binaries]: https://github.com/esp-rs/espup/releases +[cargo-binstall]: https://github.com/cargo-bins/cargo-binstall + +### 2. Install neccesary toolchains + +Install all the necessary tools to develop Rust applications for all supported Espressif targets by running: +```shell +espup install +``` + +> ⚠️ **Note**: `std` applications require installing additional software covered in [`std` Development Requirements][rust-esp-book-std-requirements] + +[rust-esp-book-std-requirements]: ./std-requirements.md + +### 3. Set up the environment variables +`espup` will create an export file that contains some environment variables required to build projects. + +On Windows (`%USERPROFILE%\export-esp.ps1`) + - There is **no need** to execute the file for Windows users. It is only created to show the modified environment variables. + +On Unix based systems (`$HOME/export-esp.sh`). There are different ways of sourcing the file: +- Source this file in every terminal: + 1. Source the export file: `. $HOME/export-esp.sh` + + This approach requires running the command in every new shell. +- Create an alias for executing the `export-esp.sh`: + 1. Copy and paste the following command to your shell’s profile (`.profile`, `.bashrc`, `.zprofile`, etc.): `alias get_esprs='. $HOME/export-esp.sh'` + 2. Refresh the configuration by restarting the terminal session or by running `source [path to profile]`, for example, `source ~/.bashrc`. + + This approach requires running the alias in every new shell. +- Add the environment variables to your shell's profile directly: + 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`. + 2. Refresh the configuration by restarting the terminal session or by running `source [path to profile]`, for example, `source ~/.bashrc`. + + This approach **does not** require any sourcing. The `export-esp.sh` script will be sourced automatically in every shell. + +### What espup Installs + +To enable support for Espressif targets, `espup` installs the following tools: + +- Espressif Rust fork with support for Espressif targets +- `nightly` toolchain with support for `RISC-V` targets +- `LLVM` [fork][llvm-github-fork] with support for `Xtensa` targets +- [GCC toolchain][gcc-toolchain-github-fork] that links the final binary + +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]. + +> ⚠️ **Note**: We are making efforts to upstream our forks +> 1. Changes in `LLVM` fork. Already in progress, see the status in this [tracking issue][llvm-github-fork-upstream issue]. +> 2. Rust compiler forks. If `LLVM` changes are accepted, we will proceed with the Rust compiler changes. + +If you run into an error, please, check the [Troubleshooting][troubleshooting] chapter. + +[llvm-github-fork]: https://github.com/espressif/llvm-project +[gcc-toolchain-github-fork]: https://github.com/espressif/crosstool-NG/ +[rustup-overrides]: https://rust-lang.github.io/rustup/overrides.html +[llvm-github-fork-upstream issue]: https://github.com/espressif/llvm-project/issues/4 +[troubleshooting]: ../misc/troubleshooting.md + +### Other installation methods for Xtensa targets + +- Using [esp-rs/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. +- 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 is not 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-build]: https://github.com/esp-rs/rust-build#download-installer-in-bash +[esp-rs/rust repository]: https://github.com/esp-rs/rust diff --git a/src/installation/riscv.md b/src/installation/riscv.md new file mode 100644 index 00000000..ec5a4e70 --- /dev/null +++ b/src/installation/riscv.md @@ -0,0 +1,42 @@ +# RISC-V targets only + +To build Rust applications for the Espressif chips based on `RISC-V` architecture, do the following: + +1. Install the [`nightly`][rustup-book-channel-nightly] toolchain with the `rust-src` [component][rustup-book-components]: + + ```shell + rustup toolchain install nightly --component rust-src + ``` +2. Set the target: + - For `no_std` (bare-metal) applications, run: + + ```shell + rustup target add riscv32imc-unknown-none-elf # For ESP32-C2 and ESP32-C3 + rustup target add riscv32imac-unknown-none-elf # For ESP32-C6 and ESP32-H2 + ``` + + 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]. + + - For `std` applications: + + Since this target is currently [Tier 3][rust-lang-book--platform-support-tier3], it does not 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. + + - `riscv32imc-esp-espidf` for SoCs which do not support atomics, like ESP32-C2 and ESP32-C3 + - `riscv32imac-esp-espidf` for SoCs which support atomics, like ESP32-C6, ESP32-H2, and ESP32-P4 +3. To build `std` projects, you also need to install: + - [`LLVM`][llvm-website] compiler infrastructure + - Other [`std` development requirements][rust-esp-book-std-requirements] + - 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. + +Now you should be able to build and run projects on the Espressif's `RISC-V` chips. + +[rustup-book-channel-nightly]: https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust +[rustup-book-components]: https://rust-lang.github.io/rustup/concepts/components.html +[rust-lang-book--platform-support-tier2]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-2 +[wiki-riscv-standard-extensions]: https://en.wikichip.org/wiki/risc-v/standard_extensions +[rust-lang-book--platform-support-tier3]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-3 +[rust-lang-book--platform-support--esp-idf]: https://doc.rust-lang.org/nightly/rustc/platform-support/esp-idf.html +[llvm-website]: https://llvm.org/ +[cargo-book-unstable-features]: https://doc.rust-lang.org/cargo/reference/unstable.html +[rust-esp-book-write-app-generate-project]: ../writing-your-own-application/generate-project/index.md +[rust-esp-book-std-requirements]: ./std-requirements.md diff --git a/src/installation/rust.md b/src/installation/rust.md new file mode 100644 index 00000000..a04dc60f --- /dev/null +++ b/src/installation/rust.md @@ -0,0 +1,16 @@ +# Rust instalaltion + +Make sure you have [Rust][rust-lang-org] installed. If not, see the instructions on the [rustup][rustup.rs-website] website. + +> 🚨 **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. + +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. +- **MSVC**: Recommended ABI, included in the list of `rustup` default requirements. Use it for interoperability with the software produced by Visual Studio. +- **GNU**: ABI used by the GCC toolchain. Install it yourself for interoperability with the software built with the MinGW/MSYS2 toolchain. + +See also [alternative installation methods][rust-alt-installation]. + +[rustup.rs-website]: https://rustup.rs/ +[rust-alt-installation]: https://rust-lang.github.io/rustup/installation/other.html +[rustup-book-windows]: https://rust-lang.github.io/rustup/installation/windows.html +[rust-lang-org]: https://www.rust-lang.org/ diff --git a/src/installation/std-requirements.md b/src/installation/std-requirements.md new file mode 100644 index 00000000..3f84e6af --- /dev/null +++ b/src/installation/std-requirements.md @@ -0,0 +1,19 @@ +# `std` Development Requirements + +Regardless of the target architecture, make sure you have the following required tools installed to build [`std`][rust-esp-book-overview-std] applications: + +- [`python`][python-website-download]: Required by ESP-IDF +- [`git`][git-website-download]: Required by ESP-IDF +- [`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: + ```shell + cargo install ldproxy + ``` + +The std runtime uses [ESP-IDF][esp-idf-github] (Espressif IoT Development Framework) as hosted environment but, users do not 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. + +[rust-esp-book-overview-std]: ../overview/using-the-standard-library.md +[python-website-download]: https://www.python.org/downloads/ +[git-website-download]: https://git-scm.com/downloads +[embuild-github-ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy +[esp-idf-sys-github]: https://github.com/esp-rs/esp-idf-sys +[esp-idf-github]: https://github.com/espressif/esp-idf diff --git a/src/installation/using-containers.md b/src/installation/using-containers.md new file mode 100644 index 00000000..c4bc87dd --- /dev/null +++ b/src/installation/using-containers.md @@ -0,0 +1,22 @@ +# Using Containers + +Instead of installing directly on your local system, you can host the development environment inside a container. Espressif provides the [idf-rust] image that supports both `RISC-V` and `Xtensa` target architectures and enables both `std` and `no_std` development. + +You can find numerous tags for `linux/arm64`, and `linux/amd64` platforms. + +For each Rust release, we generate the tag with the following naming convention: + +- `_` + - 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. + +There are special cases: + +- `` can be `all` which indicates compatibility with all Espressif targets +- `` can be `latest` which indicates the latest release of the `Xtensa` Rust toolchain + +Depending on your operating system, you can choose any container runtime, such as [Docker], [Podman], or [Lima]. + +[Docker]: https://www.docker.com/ +[Podman]: https://podman.io/ +[Lima]: https://github.com/lima-vm/lima +[idf-rust]: https://hub.docker.com/r/espressif/idf-rust/tags diff --git a/src/introduction.md b/src/introduction.md index 914db55a..4a1f904f 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -1,65 +1,52 @@ # Introduction -The goal of this book is to provide a comprehensive guide on using the [Rust Programming Language] with [Espressif] devices. +The goal of this book is to provide a comprehensive guide on using the [Rust Programming Language][rust] with [Espressif][espressif] devices. Rust support for these devices is still a work in progress, and progress is being made rapidly. Because of this, parts of this documentation may be out of date or change dramatically between readings. -For tools and libraries relating to Rust on ESP, please see the [esp-rs organization] on GitHub. This organization is managed by employees of Espressif as well as members of the community. - -[rust programming language]: https://www.rust-lang.org/ -[Espressif]: https://espressif.com/ -[esp-rs organization]: https://github.com/esp-rs/ - -> **A Note on Device Support** -> -> The contents of this book apply to the ESP32 series of devices only; this -> includes: -> -> - ESP32 Series -> - ESP32 C-Series -> - ESP32 S-Series -> - ESP32 H-Series -> -> The ESP8266 series is outside the scope of this book. Rust support for the -> ESP8266 series is limited and is not being officially supported by Espressif. +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. + +[rust]: https://www.rust-lang.org/ +[espressif]: https://espressif.com/ +[esp-rs]: https://github.com/esp-rs/ ## Who This Book is For -This book is intended for people with some experience with Rust, and also assumes rudimentary knowledge of embedded development and electronics. For those without prior experience, we recommend first reading the [Assumptions and Prerequisites] and [Other Resources] sections to get up to speed. +This book is intended for people with some experience with Rust, and also assumes rudimentary knowledge of embedded development and electronics. For those without prior experience, we recommend first reading the [Assumptions and Prerequisites][prerequisites] and [Resources][resources] sections to get up to speed. -[assumptions and prerequisites]: #assumptions-and-prerequisites -[other resources]: #other-resources +[prerequisites]: #assumptions-and-prerequisites +[resources]: #resources ### Assumptions and Prerequisites - You are comfortable using the Rust Programming Language, and have written and run applications in a desktop environment. -- You should be familiar with the idioms of the [2021 edition], as this book targets Rust 2021. +- You should be familiar with the idioms of the [2021 edition][rust-2021], as this book targets Rust 2021. - You are comfortable developing embedded systems in another language such as C or C++, and are familiar with concepts such as: - Cross-compilation - - Common digital interfaces like `UART`, `SPI`, `I²C`, etc. + - Common digital interfaces like `UART`, `SPI`, `I2C`, etc. - Memory-mapped peripherals - Interrupts -[2021 edition]: https://doc.rust-lang.org/edition-guide/rust-2021/index.html +[rust-2021]: https://doc.rust-lang.org/edition-guide/rust-2021/index.html -### Other Resources +### Resources If you are unfamiliar or less experienced with anything mentioned above, or if you would just like more information about a particular topic mentioned in this book, you may find these resources helpful. -| Resource | Description | -| ------------------------------- | ------------------------------------------------------------------------------------ | -| [The Rust Programming Language] | If you are not familiar with Rust we recommend reading this book first. | -| [The Embedded Rust Book] | Here you can find several other resources provided by Rust's Embedded Working Group. | -| [The Embedonomicon] | The nitty-gritty details when doing embedded programming in Rust. | -| [Embedded Rust on Espressif] | Training material created in cooperation with [Ferrous Systems]. | +| Resource | Description | +| -------------------------------------------- | ------------------------------------------------------------------------------------ | +| [The Rust Programming Language][rust-book] | If you are not familiar with Rust we recommend reading this book first. | +| [The Embedded Rust Book][embedded-rust-book] | Here you can find several other resources provided by Rust's Embedded Working Group. | +| [The Embedonomicon][embedonomicon] | The nitty-gritty details when doing embedded programming in Rust. | +| [Embedded Rust on Espressif][std-training] | Training material created in cooperation with [Ferrous Systems][ferrous-systems]. | -[the rust programming language]: https://doc.rust-lang.org/book/ -[the embedded rust book]: https://docs.rust-embedded.org/book/index.html -[the embedonomicon]: https://docs.rust-embedded.org/embedonomicon/ -[embedded rust on espressif]: https://esp-rs.github.io/std-training/ -[ferrous systems]: https://ferrous-systems.com/ +[rust-book]: https://doc.rust-lang.org/book/ +[embedded-rust-book]: https://docs.rust-embedded.org/book/index.html +[embedonomicon]: https://docs.rust-embedded.org/embedonomicon/ +[std-training]: https://esp-rs.github.io/std-training/ +[ferrous-systems]: https://ferrous-systems.com/ -### Translations +## Translations This book is currently available in English only. Once the contents of the book stabilize somewhat, we plan on translating the book into additional languages. As translations become available, this section will be updated to include them. @@ -69,31 +56,30 @@ This book generally assumes that you are reading it front-to-back; content cover ## Contributing to This Book -The work on this book is coordinated in [this repository]. - -[this repository]: https://github.com/esp-rs/book - -If you have trouble following the instructions in this book or find that some section of the book is not clear enough or hard to follow, then that's a bug, and it should be reported in [the issue tracker] of this book. +The work on this book is coordinated in [this repository][book-repository]. -[the issue tracker]: https://github.com/esp-rs/book/issues/ +If you have trouble following the instructions in this book or find that some section of the book is not clear enough or hard to follow, then that's a bug, and it should be reported in [the issue tracker][book-issues] of this book. Pull requests fixing typos and adding new content are very welcome! +[book-issues]: https://github.com/esp-rs/book/issues/ +[book-repository]: https://github.com/esp-rs/book + ## Re-using This Material This book is distributed under the following licenses: -- The code samples and freestanding Cargo projects contained within this book are licensed under the terms of both the [MIT License] and the [Apache License v2.0]. -- The written prose, pictures, and diagrams contained within this book are licensed under the terms of the Creative Commons [CC-BY-SA v4.0] license. - -[mit license]: https://opensource.org/licenses/MIT -[apache license v2.0]: http://www.apache.org/licenses/LICENSE-2.0 -[cc-by-sa v4.0]: https://creativecommons.org/licenses/by-sa/4.0/legalcode +- 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]. +- 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. TL;DR: If you want to use our text or images in your work, you need to: - Give the appropriate credit (i.e. mention this book on your slide, and provide a link to the relevant page) -- Provide a link to the [CC-BY-SA v4.0] licence +- Provide a link to the [CC-BY-SA v4.0][cc-license] licence - Indicate if you have changed the material in any way, and make any changes to our material available under the same licence Please do let us know if you find this book useful! + +[mit-license]: https://opensource.org/licenses/MIT +[apache-license]: http://www.apache.org/licenses/LICENSE-2.0 +[cc-license]: https://creativecommons.org/licenses/by-sa/4.0/legalcode diff --git a/src/misc/troubleshooting.md b/src/misc/troubleshooting.md index d6410af5..8011fac5 100644 --- a/src/misc/troubleshooting.md +++ b/src/misc/troubleshooting.md @@ -12,10 +12,11 @@ We need `libclang` for [`bindgen`] to generate the Rust bindings to the ESP-IDF Make sure you have sourced the export file generated by `espup`, see [Set up the environment variables][set-up-the-environment-variables]. [`bindgen`]: https://github.com/rust-lang/rust-bindgen -[set-up-the-environment-variables]: ./../installation/index.md#3-set-up-the-environment-variables +[set-up-the-environment-variables]: ./../installation/riscv-and-xtensa.md#3-set-up-the-environment-variables + ## Missing `ldproxy` -```sh +```shell error: linker `ldproxy` not found | = note: No such file or directory (os error 2) @@ -23,12 +24,12 @@ error: linker `ldproxy` not found If you are trying to build a `std` application [`ldproxy`] must be installed. See [`std` Development Requirements][rust-esp-book-std-requirements] -```sh +```shell cargo install ldproxy ``` [`ldproxy`]: https://github.com/esp-rs/embuild/tree/master/ldproxy -[rust-esp-book-std-requirements]: ./../installation/index.md#std-development-requirements +[rust-esp-book-std-requirements]: ./../installation/std-requirements.md ## Using a wrong Rust toolchain @@ -95,14 +96,13 @@ If using GNU ABI, install [MinGW/MSYS2 toolchain]. [Visual Studio 2013 (or later) or the Visual C++ Build Tools 2019]: https://rust-lang.github.io/rustup/installation/windows.html [MinGW/MSYS2 toolchain]: https://www.msys2.org/ - ## FAQ ### I updated my `sdkconfig.defaults` file but it doesn't appear to have had any effect You must clean your project and rebuild for changes in the `sdkconfig.defaults` to take effect: -```shell,ignore +```shell cargo clean cargo build ``` @@ -127,7 +127,7 @@ Instead, we are building the documentation and hosting it ourselves on GitHub Pa 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: -```ignore +```text CONFIG_ESP_MAIN_TASK_STACK_SIZE=7000 ``` @@ -137,7 +137,7 @@ In this example, we are allocating 7kB for the main task's stack. Add to your `sdkconfig.defaults` file: -```ignore +```text CONFIG_INT_WDT=n CONFIG_ESP_TASK_WDT=n ``` diff --git a/src/overview/index.md b/src/overview/index.md index 664f04ed..bf764f7b 100644 --- a/src/overview/index.md +++ b/src/overview/index.md @@ -1,4 +1,4 @@ -# Ecosystem Overview +# Overview of Development Approaches There are the following approaches to using Rust on Espressif chips: @@ -8,34 +8,30 @@ There are the following approaches to using Rust on Espressif chips: 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: - [Using the Standard Library (`std`)][rust-esp-book-std] -- [Developing on Bare Metal (`no_std`)][rust-esp-book-no-std] - -[rust-esp-book-std]: ./using-the-standard-library.md -[rust-esp-book-no-std]: ./bare-metal.md +- [Using the Core Library (`no_std`)][rust-esp-book-no-std] See also the comparison of the different runtimes in [The Embedded Rust Book][embedded-rust-book-intro-std]. +The [esp-rs organization] on GitHub is home to a number of repositories related to running Rust on Espressif chips. Most of the required crates have their source code hosted here. + +[rust-esp-book-std]: ./using-the-standard-library.md +[rust-esp-book-no-std]: ./using-the-core-library.md [embedded-rust-book-intro-std]: https://docs.rust-embedded.org/book/intro/no-std.html#a-no_std-rust-environment +[esp-rs organization]: https://github.com/esp-rs/ -The [esp-rs organization] on GitHub is home to a number of repositories related to running Rust on Espressif chips. Most of the required crates have their source code hosted here. +## Repository naming convention -> A note on the repository naming convention -> -> In the [esp-rs organization] we use the following wording: -> -> - Repositories starting with `esp-idf-` are focused on `std` approach. E.g. `esp-idf-hal` -> - Repositories starting with `esp-` are focused on `no_std` approach. E.g. `esp-hal` -> -> It is easy to remember as follows: -> -> - `no_std` works on top of bare metal, so `esp-` is an Espressif chip ->- `std`, apart from bare metal, also needs an [additional layer](https://github.com/espressif/esp-idf), which is `esp-idf-` +In the [esp-rs organization] we use the following wording: +- Repositories starting with `esp-` are focused on `no_std` approach. For example, `esp-hal` + - `no_std` works on top of bare metal, so `esp-` is an Espressif chip +- Repositories starting with `esp-idf-` are focused on `std` approach. For example, `esp-idf-hal` + - `std`, apart from bare metal, also needs an [additional layer], which is `esp-idf-` -[esp-rs organization]: https://github.com/esp-rs/ +[additional layer]: https://github.com/espressif/esp-idf ## Support for Espressif Products -> **Notes**: +> ⚠️ **Notes**: > > - ✅ - The feature is implemented or supported > - ⏳ - The feature is under development @@ -52,8 +48,7 @@ The [esp-rs organization] on GitHub is home to a number of repositories related | ESP32-H2 | ✅ | ✅ | | ESP8266 | ❌ | ✅ | -The products supported in certain circumstances will be called _supported Espressif products_ throughout the book. - -As of now, the Espressif products supported by the esp-idf framework are the ones supported for Rust `std` development. For details on different versions of esp-idf and support of Espressif chips, see [this table][esp-idf-release-compatibility]. +> ⚠️ **Note**: The ESP8266 series is outside the scope of this book. Rust support for the +> ESP8266 series is limited and is not being officially supported by Espressif. -[esp-idf-release-compatibility]: https://github.com/espressif/esp-idf#esp-idf-release-and-soc-compatibility +The products supported in certain circumstances will be called _supported Espressif products_ throughout the book. diff --git a/src/overview/bare-metal.md b/src/overview/using-the-core-library.md similarity index 92% rename from src/overview/bare-metal.md rename to src/overview/using-the-core-library.md index 30e83377..57edab9f 100644 --- a/src/overview/bare-metal.md +++ b/src/overview/using-the-core-library.md @@ -1,21 +1,18 @@ -# Developing on Bare Metal (`no_std`) +# Using the Core Library (`no_std`) Using `no_std` may be more familiar to embedded Rust developers; it does not 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. -It's important to note that since `no_std` uses the Rust `core` library, a subset of the Rust `standard` library, a `no_std` crate can compile in `std` environment but the opposite is not true. Therefore, when creating crates it's worth keeping in mind if it needs the `standard` library to function. - +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 is not true: an `std` crate cannot compile in `no_std` environment. This information is worth remembering when deciding which library to choose. [embedded-rust-book]: https://docs.rust-embedded.org/ [embedded-rust-book-no-std]: https://docs.rust-embedded.org/book/intro/no-std.html [rust-lib-core]: https://doc.rust-lang.org/core/index.html [rust-lib-std]: https://doc.rust-lang.org/std/index.html - ## Current support The table below covers the current support for `no_std` at this moment for different Espressif products. - | | [HAL][esp-rs/esp-hal] | [Wi-Fi/BLE/ESP-NOW][esp-rs/esp-wifi] | [Backtrace][esp-rs/esp-backtrace] | [Storage][esp-rs/esp-storage] | | -------- | :-------------------: | :----------------------------------: | :-------------------------------: | :---------------------------: | | ESP32 | ✅ | ✅ | ✅ | ✅ | @@ -26,12 +23,13 @@ The table below covers the current support for `no_std` at this moment for diffe | ESP32-S3 | ✅ | ✅ | ✅ | ✅ | | ESP32-H2 | ✅ | ⏳ | ✅ | ✅ | -> **Note**: +> ⚠️ **Note**: > > - ✅ 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. > - [ESP8266 HAL][esp-rs/esp8266-hal] is in maintenance mode and no further development will be done for this chip. [esp-wifi-current-support]: https://github.com/esp-rs/esp-wifi#current-support + ### Relevant `esp-rs` crates | Repository | Description | @@ -51,7 +49,6 @@ The table below covers the current support for `no_std` at this moment for diffe - 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. - 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. - [esp-rs/esp-hal]: https://github.com/esp-rs/esp-hal "Hardware abstraction layer" [esp-rs/esp8266-hal]: https://github.com/esp-rs/esp8266-hal "ESP8266 Hardware abstraction layer" [esp-rs/esp-pacs]: https://github.com/esp-rs/esp-pacs "Peripheral access crates" @@ -60,5 +57,3 @@ The table below covers the current support for `no_std` at this moment for diffe [esp-rs/esp-println]: https://github.com/esp-rs/esp-println "print!, println!" [esp-rs/esp-backtrace]: https://github.com/esp-rs/esp-backtrace "Exception and panic handlers" [esp-rs/esp-storage]: https://github.com/esp-rs/esp-storage "Embedded-storage traits to access unencrypted flash memory" - - diff --git a/src/overview/using-the-standard-library.md b/src/overview/using-the-standard-library.md index e1c36ba6..dabb941d 100644 --- a/src/overview/using-the-standard-library.md +++ b/src/overview/using-the-standard-library.md @@ -1,8 +1,6 @@ # Using the Standard Library (`std`) -Espressif provides a C-based development framework called [esp-idf][esp-idf-github] which has, or will have, support for all Espressif chips starting with the ESP32; note that this framework does _not_ support the ESP8266. See also [Support for Espressif Products][rust-esp-book-overview-index]. - -[rust-esp-book-overview-index]: index.md#support-for-espressif-products +Espressif provides a C-based development framework called [esp-idf][esp-idf-github] which has, or will have, support for all Espressif chips starting with the ESP32; note that this framework does _not_ support the ESP8266. `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 ESP devices. @@ -11,7 +9,7 @@ Espressif provides a C-based development framework called [esp-idf][esp-idf-gith ## Current Support -As of now, the Espressif products supported by the [esp-idf framework][esp-idf-release-compatibility] are the ones supported for Rust `std` development. +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]. [esp-idf-release-compatibility]: https://github.com/espressif/esp-idf#esp-idf-release-and-soc-compatibility/ @@ -34,16 +32,17 @@ graph TD; esp-idf-svc --> esp-idf-sys & esp-idf-hal & embedded-svc ``` +[embedded-svc]: https://github.com/esp-rs/embedded-svc +[esp-rs/embedded-svc]: https://github.com/esp-rs/embedded-svc +[esp-rs/esp-idf-svc]: https://github.com/esp-rs/esp-idf-svc +[esp-rs/esp-idf-sys]: https://github.com/esp-rs/esp-idf-sys +[esp-rs/esp-idf-hal]: https://github.com/esp-rs/esp-idf-hal + ### When you might want to use the Standard Library (`std`) - 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 relatively quickly and efficiently - 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. - 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. -[embedded-svc]: https://github.com/esp-rs/embedded-svc -[esp-rs/embedded-svc]: https://github.com/esp-rs/embedded-svc -[esp-rs/esp-idf-svc]: https://github.com/esp-rs/esp-idf-svc -[esp-rs/esp-idf-sys]: https://github.com/esp-rs/esp-idf-sys -[esp-rs/esp-idf-hal]: https://github.com/esp-rs/esp-idf-hal diff --git a/src/tooling/debugging/openocd.md b/src/tooling/debugging/openocd.md index 23aeedd6..860820be 100644 --- a/src/tooling/debugging/openocd.md +++ b/src/tooling/debugging/openocd.md @@ -1,9 +1,13 @@ # OpenOCD -Similar to [probe-rs](./probe-rs.md), OpenOCD does not have support for the Xtensa architecture. However, Espressif does maintain a fork of OpenOCD under [espressif/openocd-esp32](https://github.com/espressif/openocd-esp32) which has support for Espressif's chips. +Similar to [probe-rs][probe-rs], OpenOCD does not 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. -Instructions on how to install `openocd-esp32` for your platform can be found in [the Espressif documentation](https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/index.html#setup-of-openocd). +Instructions on how to install `openocd-esp32` for your platform can be found in [the Espressif documentation][espressif-documentation]. + +[probe-rs]: ./probe-rs.md +[espressif-openocd-esp32]: https://github.com/espressif/openocd-esp32 +[espressif-documentation]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/index.html#setup-of-openocd ## Setup for Espressif chips @@ -11,12 +15,12 @@ Instructions on how to install `openocd-esp32` for your platform can be found in Once installed, it's as simple as running `openocd` with the correct scripts. For chips with the built-in USB JTAG, there is normally a config that will work out of the box, for example on the ESP32-C3: -```ignore +```shell openocd -f board/esp32c3-builtin.cfg ``` For other configurations it may require specifying the chip and the interface separately, for example, ESP32 with a J-Link: -```ignore +```shell openocd -f interface/jlink.cfg -f target/esp32.cfg ``` diff --git a/src/tooling/debugging/probe-rs.md b/src/tooling/debugging/probe-rs.md index 4b29a1d3..f88b69b8 100644 --- a/src/tooling/debugging/probe-rs.md +++ b/src/tooling/debugging/probe-rs.md @@ -1,6 +1,6 @@ # probe-rs -The [probe-rs] project is a set of tools to interact with embedded MCU's using various debug probes. It is similar to [openOCD], [PyOCD], [Segger tools], etc. There is support for `ARM` & `RISC-V` architectures along with a collection of tools, including but not limited to: +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 `ARM` & `RISC-V` architectures along with a collection of tools, including but not limited to: - Debugger - GDB support. @@ -12,15 +12,16 @@ The [probe-rs] project is a set of tools to interact with embedded MCU's using v More info about probe-rs & how to set up a project can be found on the [probe-rs] website. - [probe-rs]: https://probe.rs/ [openocd]: https://openocd.org/ -[PyOCD]: https://pyocd.io/ -[Segger tools]: https://www.segger.com/ +[pyocd]: https://pyocd.io/ +[segger-tools]: https://www.segger.com/ ## `USB-JTAG-SERIAL` peripheral for ESP32-C3 -Starting from `probe-rs` v0.12, it is possible to flash and debug the ESP32-C3 with the built-in `USB-JTAG-SERIAL` peripheral, no need for any external hardware debugger. More info on configuring the interface can be found in the [official documentation]. +Starting from `probe-rs` v0.12, it is possible to flash and debug the ESP32-C3 with the built-in `USB-JTAG-SERIAL` peripheral, no need for any external hardware debugger. More info on configuring the interface can be found in the [official documentation][official-documentation]. + +[official-documentation]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html ## Support for Espressif chips @@ -30,15 +31,13 @@ Starting from `probe-rs` v0.12, it is possible to flash and debug the ESP32-C3 w | :------: | :------: | :-------: | | ESP32-C3 | ✅ | ⚠️ | -**Note**: _Items marked with ⚠️ are currently work in progress, usable but expect bugs._ - -[official documentation]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c3/api-guides/jtag-debugging/configure-builtin-jtag.html +> ⚠️ **Note**: _Items marked with ⚠️ are currently work in progress, usable but expect bugs._ ## Permissions - Linux On Linux, you may run into permission issues trying to interact with Espressif probes. Installing the following `udev` rules and reloading should fix that issue. -```udev +```text # Espressif dev kit FTDI ATTRS{idVendor}=="0403", ATTRS{idProduct}=="6010", MODE="660", GROUP="plugdev", TAG+="uaccess" diff --git a/src/tooling/debugging/vscode-debugging.md b/src/tooling/debugging/vscode.md similarity index 59% rename from src/tooling/debugging/vscode-debugging.md rename to src/tooling/debugging/vscode.md index 82a84d7f..b0e9cfa4 100644 --- a/src/tooling/debugging/vscode-debugging.md +++ b/src/tooling/debugging/vscode.md @@ -4,9 +4,9 @@ There is also a possibility to debug with graphical output directly in Visual St ## ESP32 -### Hardware Setup +### Configuration -ESP32 doesn't have a built-in JTAG interface, so you have to connect an external JTAG adapter to the ESP32 board, for example, [ESP-Prog](https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html) can be used. +1. Connect an external JTAG adapter: [ESP-Prog][esp-prog] can be used. | ESP32 Pin | JTAG Signal | | :---------: | :---------: | @@ -17,15 +17,14 @@ ESP32 doesn't have a built-in JTAG interface, so you have to connect an external | 3V3 | VJTAG | | GND | GND | -**Note**: On Windows `USB Serial Converter A 0403 6010 00` driver should be WinUSB. +> ⚠️ **Note**: On Windows `USB Serial Converter A 0403 6010 00` driver should be WinUSB. -## Set up VSCode +2. Set up VSCode + 1. Install [Cortex-Debug][cortex-debug] extension for VScode. + 2. Create the `.vscode/launch.json` file in the project tree you want to debug. + 3. Update `executable`, `svdFile`, `serverpath` paths, and `toolchainPrefix` field. -1. Install [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) extension for VScode. -2. Create the `.vscode/launch.json` file in the project tree you want to debug. [This](https://github.com/esp-rs/esp32-hal/blob/master/.vscode/launch.json) can be used as a template file. -3. Update **executable**, **svdFile**, **serverpath** paths, and **toolchainPrefix** field. - -```jsonc +```json { // Use IntelliSense to learn about possible attributes. // Hover to view descriptions of existing attributes. @@ -57,17 +56,27 @@ ESP32 doesn't have a built-in JTAG interface, so you have to connect an external } ``` +[esp-prog]: https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html +[cortex-debug]: https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug + ## ESP32-C3 -Older versions with **revision < 3** **don't** have built-in JTAG interface. +The availability of built-in JTAG interface depends on the ESP32-C3 revision: + +- Revisions older than 3 **don't** a have built-in JTAG interface. +- Revitions 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. -ESP32-C3 with **revision 3** **does** have a built-in JTAG interface, and you don't have to connect an external device to be able to debug. To get the chip revision, run the `cargo espflash board-info` command. +To find your ESP32-C3 revision, run: -### Hardware Setup +```shell +cargo espflash board-info +# or +espflash board-info +``` -If your ESP32-C3's revision is lesser than 3, follow these instructions, if you have revision 3 you can jump to the [**Set up VSCode**](#set-up-vscode-1) step. +### Configuration -ESP32-C3 **revision 1** and **revision 2** don't have a built-in JTAG interface, so you have to connect an external JTAG adapter to the ESP32-C3 board, for example, [ESP-Prog](https://docs.espressif.com/projects/espressif-esp-iot-solution/en/latest/hw-reference/ESP-Prog_guide.html) can be used. +1. (**Only for revisions older than 3**) Connect an external JTAG adapter, [ESP-Prog][esp-prog] can be used. | ESP32-C3 Pin | JTAG Signal | | :----------: | :---------: | @@ -78,15 +87,13 @@ ESP32-C3 **revision 1** and **revision 2** don't have a built-in JTAG interface, | 3V3 | VJTAG | | GND | GND | -**Note**: On Windows `USB Serial Converter A 0403 6010 00` driver should be WinUSB. - -### Set up VSCode - -1. Install [Cortex-Debug](https://marketplace.visualstudio.com/items?itemName=marus25.cortex-debug) extension for VScode. -2. Create the `.vscode/launch.json` file in the project tree you want to debug. [This](https://github.com/esp-rs/esp32-hal/blob/master/.vscode/launch.json) can be used as a template file. -3. Update **executable**, **svdFile**, **serverpath** paths, and **toolchainPrefix** field. +> ⚠️**Note**: On Windows `USB Serial Converter A 0403 6010 00` driver should be WinUSB. -```jsonc +2. Set up VSCode + 1. Install [Cortex-Debug][cortex-debug] extension for VScode. + 2. Create the `.vscode/launch.json` file in the project tree you want to debug. + 3. Update `executable`, `svdFile`, `serverpath` paths, and `toolchainPrefix` field. +```json { // Use IntelliSense to learn about possible attributes. // Hover to view descriptions of existing attributes. diff --git a/src/tooling/espflash.md b/src/tooling/espflash.md index 0164ed1c..e8be6963 100644 --- a/src/tooling/espflash.md +++ b/src/tooling/espflash.md @@ -1,54 +1,52 @@ # espflash -`espflash` provides a serial flasher utility for Espressif SoCs and modules based on [esptool.py]. +`espflash` is a serial flasher utility, based on [esptool.py][esptool], for Espressif SoCs and modules. -The [esp-rs/espflash] repository contains two crates, `cargo-espflash` and `espflash`. You can find more information on both of these in their respective sections below and in their corresponding README. +The [esp-rs/espflash][espflash] repository contains two crates, `cargo-espflash` and `espflash`. For more information on these crates, see the respective sections below. -> #### A note on `espflash` and `cargo-espflash`. -> -> The `espflash` and `cargo-espflash` commands shown below, assume that version `2.0` or greater. +[esptool]: https://github.com/espressif/esptool +[espflash]: https://github.com/esp-rs/espflash + +> ⚠️ **Note**: The `espflash` and `cargo-espflash` commands shown below, assume that version `2.0` or greater is used. -[esp-rs/espflash]: https://github.com/esp-rs/espflash -[esptool.py]: https://github.com/espressif/esptool ## cargo-espflash Provides a subcommand for `cargo` that handles cross-compilation and flashing. -To install: +To install, run: -```bash +```shell cargo install cargo-espflash ``` 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: -```bash +```shell cargo espflash flash --example=blinky --monitor ``` -For more information, please see the [cargo-espflash README]. +For more information, please see the [cargo-espflash][cargo-espflash] README. -[cargo-espflash readme]: https://github.com/esp-rs/espflash/blob/master/cargo-espflash/README.md +[cargo-espflash]: https://github.com/esp-rs/espflash/blob/master/cargo-espflash/README.md ## espflash Provides a standalone command-line application that flashes an ELF file to a device. -To install: +To install, run: -```bash +```shell cargo install espflash ``` -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] using `idf.py` you might run something like: +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] using `idf.py`, you might run something like: -```bash +```shell espflash flash build/blinky --monitor ``` For more information, please see the [espflash README]. - `espflash` can be used as a Cargo runner by adding the following to your project's `.cargo/config.toml` file: ```toml [target.'cfg(any(target_arch = "riscv32", target_arch = "xtensa"))'] diff --git a/src/tooling/index.md b/src/tooling/index.md index 065470d8..83439ead 100644 --- a/src/tooling/index.md +++ b/src/tooling/index.md @@ -3,3 +3,6 @@ Now that we have our required dependencies installed, and we know how to generate a template project, we will cover, in more detail, some of the tools that will make developing Rust applications for ESP targets a lot easier. + +In this chapter, we will present `espflash`/`cargo-espflash`, suggest Visual Studio Code as IDE and dig into the +current available simulation and debbuging methods. diff --git a/src/tooling/simulating/index.md b/src/tooling/simulating/index.md index 0a5b2dbe..bbd3573b 100644 --- a/src/tooling/simulating/index.md +++ b/src/tooling/simulating/index.md @@ -4,18 +4,18 @@ Simulating projects can be very handy. It allows users to test projects using CI At the moment, there are a few ways of simulating Rust projects on Espressif chips, all of them have some limitations, but it's quickly evolving and getting better every day. -In this chapter, we will discuss the different ways of simulation that are available. +In this chapter, we will discuss the different simulation tools that are available. Refer to the table below to see which chip is supported in every simulating method: -| | **[Wokwi]** | **QEMU** | -| :----------: | :---------: | :------: | -| **ESP32** | ✅ | ✅ | -| **ESP32-C2** | ❌ | ❌ | -| **ESP32-C3** | ✅ | ❌ | -| **ESP32-C6** | ✅ | ❌ | -| **ESP32-H2** | ❌ | ❌ | -| **ESP32-S2** | ✅ | ❌ | -| **ESP32-S3** | ✅ | ❌ | +| | **[Wokwi][wokwi]** | **QEMU** | +| :----------: | :----------------: | :------: | +| **ESP32** | ✅ | ✅ | +| **ESP32-C2** | ❌ | ❌ | +| **ESP32-C3** | ✅ | ❌ | +| **ESP32-C6** | ✅ | ❌ | +| **ESP32-H2** | ✅ | ❌ | +| **ESP32-S2** | ✅ | ❌ | +| **ESP32-S3** | ✅ | ❌ | -[Wokwi]: https://docs.wokwi.com/guides/esp32#simulation-features +[wokwi]: https://docs.wokwi.com/guides/esp32#simulation-features diff --git a/src/tooling/simulating/qemu.md b/src/tooling/simulating/qemu.md index bf7a329e..52f7bdc8 100644 --- a/src/tooling/simulating/qemu.md +++ b/src/tooling/simulating/qemu.md @@ -1,36 +1,34 @@ # QEMU -Espressif maintains a fork of QEMU in [espressif/QEMU] with the necessary patches to make it work on Espressif chips. -See the [QEMU wiki] for instructions on how to build QEMU and emulate projects with it. +Espressif maintains a fork of QEMU in [espressif/QEMU][espressif-qemu] with the necessary patches to make it work on Espressif chips. +See the [QEMU wiki][qemu-wiki] for instructions on how to build QEMU and emulate projects with it. -Once you have built QEMU, you should have `qemu-system-xtensa`. +Once you have built QEMU, you should have the `qemu-system-xtensa` file. -[espressif/QEMU]: https://github.com/espressif/qemu -[QEMU wiki]: https://github.com/espressif/qemu/wiki +[espressif-qemu]: https://github.com/espressif/qemu +[qemu-wiki]: https://github.com/espressif/qemu/wiki -## Running our project using QEMU +## Running your project using QEMU -> *NOTE*: Only ESP32 is currently supported, so make sure you are compiling for `xtensa-esp32-espidf` target. +> ⚠️ **Note**: Only ESP32 is currently supported, so make sure you are compiling for `xtensa-esp32-espidf` target. For running our project in QEMU, we need a firmware/image with bootloader and partition table merged in it. -We can use [`cargo-espflash`] to generate it: +We can use [`cargo-espflash`][cargo-espflash] to generate it: -[`cargo-espflash`]: https://github.com/esp-rs/espflash/tree/main/cargo-espflash - -```bash +```shell cargo espflash save-image --chip esp32 --merge --release ``` -> If you prefer to use [`espflash`], you can achieve the same result by building the project first and then generating image: ->```bash -> cargo build --release -> espflash save-image --merge ESP32 target/xtensa-esp32-espidf/release/ ->``` - -[`espflash`]: https://github.com/esp-rs/espflash/tree/main/espflash +If you prefer to use [`espflash`][espflash], you can achieve the same result by building the project first and then generating image: +```shell +cargo build --release +espflash save-image --merge ESP32 target/xtensa-esp32-espidf/release/ +``` Now, run the image in QEMU: -```sh +```shell /path/to/qemu-system-xtensa -nographic -machine esp32 -drive file=,if=mtd,format=raw ``` +[cargo-espflash]: https://github.com/esp-rs/espflash/tree/main/cargo-espflash +[espflash]: https://github.com/esp-rs/espflash/tree/main/espflash diff --git a/src/tooling/simulating/wokwi.md b/src/tooling/simulating/wokwi.md index c3168170..d2d3e0e6 100644 --- a/src/tooling/simulating/wokwi.md +++ b/src/tooling/simulating/wokwi.md @@ -1,42 +1,45 @@ # Wokwi -[Wokwi] is an online simulator that supports simulating Rust projects (both `std` and `no_std`) in ESP Chips, -see [wokwi.com/rust] for a list of examples and a way to start new projects. +[Wokwi][wokwi] is an online simulator that supports simulating Rust projects (both `std` and `no_std`) in ESP Chips, +see [wokwi.com/rust][wokwi-rust] for a list of examples and a way to start new projects. -Wokwi offers Wi-Fi simulation, Virtual Logic Analyzer, and [GDB debugging] among many other features, see -[Wokwi documentation] for more details. For ESP chips, there is a [table of simulation features that are currently supported]. +Wokwi offers Wi-Fi simulation, Virtual Logic Analyzer, and [GDB debugging][gdb-debugging] among many other features, see +[Wokwi documentation][wokwi-documentation] for more details. For ESP chips, there is a table of [simulation features][wokwi-simulation-features] that are currently supported. + +[wokwi]: https://wokwi.com/ +[wokwi-rust]: https://wokwi.com/rust +[gdb-debugging]: https://docs.wokwi.com/gdb-debugging +[wokwi-documentation]: https://docs.wokwi.com/ +[wokwi-simulation-features]: https://docs.wokwi.com/guides/esp32#simulation-features ## Using Wokwi for VS Code extension -Wokwi offers a VS Code extension that allows users to simulate their project directly from your code editor by only adding a few files. For more information, see [Wokwi documentation][wokwi-vscode]. -You can also debug your code using the VS Code debugger, see [Debugging your code]. +Wokwi offers a VS Code extension that allows you to simulate a project directly in the code editor by only adding a few files. +For more information, see [Wokwi documentation][wokwi-vscode]. +You can also debug your code using the VS Code debugger, see [Debugging your code][wokwi-debugging]. -When using any of the [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. +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. ![Wokwi VS Code example](../../assets/wokwi-vscode.png) +[wokwi-vscode]: https://docs.wokwi.com/vscode/getting-started +[wokwi-debugging]: https://docs.wokwi.com/vscode/debugging +[templates]: ./../../writing-your-own-application/generate-project/index.md + ## Using wokwi-server -[wokwi-server] is a CLI tool for launching a Wokwi simulation of your project. I.e., it allows you +[wokwi-server][wokwi-server] is a CLI tool for launching a Wokwi simulation of your project. I.e., it allows you to build a project on your machine, or in a container, and simulate the resulting binary. -[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 README] for detailed instructions. +[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. + +[wokwi-server]: https://github.com/MabezDev/wokwi-server +[wokwi-server-custom]: https://github.com/MabezDev/wokwi-server#simulating-your-binary-on-a-custom-wokwi-project ## Custom chips 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]. Custom chips can also be written in Rust! See [Wokwi Custom Chip API][rust-chip-api] for more information. E.g: custom [inverter chip][custom-chip-example] written in Rust. - -[Wokwi]: https://wokwi.com/ -[wokwi.com/rust]: https://wokwi.com/rust -[GDB debugging]: https://docs.wokwi.com/gdb-debugging -[Wokwi documentation]: https://docs.wokwi.com/ -[table of simulation features that are currently supported]: https://docs.wokwi.com/guides/esp32#simulation-features -[wokwi-server]: https://github.com/MabezDev/wokwi-server -[corresponding section of the wokwi-server Readme]: https://github.com/MabezDev/wokwi-server#simulating-your-binary-on-a-custom-wokwi-project -[wokwi-vscode]: https://docs.wokwi.com/vscode/getting-started -[Debugging your code]: https://docs.wokwi.com/vscode/debugging -[templates]: ./../../writing-your-own-application/generate-project/index.md [wokwi-custom-chip]: https://docs.wokwi.com/chips-api/getting-started -[custom-chip-example]: https://github.com/wokwi/rust_chip_inverter [rust-chip-api]: https://github.com/wokwi/wokwi_chip_ll +[custom-chip-example]: https://github.com/wokwi/rust_chip_inverter diff --git a/src/tooling/text-editors-and-ides.md b/src/tooling/text-editors-and-ides.md deleted file mode 100644 index 04786454..00000000 --- a/src/tooling/text-editors-and-ides.md +++ /dev/null @@ -1,46 +0,0 @@ -# Visual Studio Code - -One of the more common development environments is Microsoft's [Visual Studio Code] text editor along with the [Rust Analyzer] extension. - -Visual Studio Code is an open-source and cross-platform graphical text editor with a rich ecosystem of extensions. The [Rust Analyzer extension] provides an implementation of the [Language Server Protocol] for Rust and additionally includes features like autocompletion, go-to definition, and more. - -Visual Studio Code can be installed via most popular package managers, and installers are available on the official website. The [Rust Analyzer extension] can be installed in Visual Studio Code via the built-in extension manager. - -Alongside Rust Analyzer (RA), there are other extensions that might be very helpful: - -- [Even Better TOML] for editing TOML-based configuration files -- [crates] to help manage Rust dependencies - -[visual studio code]: https://code.visualstudio.com/ -[rust analyzer]: https://rust-analyzer.github.io/ -[Rust Analyzer extension]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer -[language server protocol]: https://microsoft.github.io/language-server-protocol/ -[Even Better TOML]: https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml -[crates]: https://marketplace.visualstudio.com/items?itemName=serayuzgur.crates - -## Tips and Tricks - -If you are developing for a target that does not 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: - -```json -{ - "rust-analyzer.checkOnSave.allTargets": false -} -``` - -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: - -```toml -[toolchain] -channel = "esp" -components = ["rustfmt", "rustc-dev"] -targets = ["xtensa-esp32-none-elf"] -``` - -## Other IDEs - -There are other IDEs like [CLion] or [vim] that also have pretty good support for Rust, -but we won't be covering them here. - -[CLion]: https://www.jetbrains.com/clion/ -[vim]: https://www.vim.org/ diff --git a/src/tooling/visual-studio-code.md b/src/tooling/visual-studio-code.md new file mode 100644 index 00000000..88787c31 --- /dev/null +++ b/src/tooling/visual-studio-code.md @@ -0,0 +1,49 @@ +# Visual Studio Code + +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. + +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. + +Visual Studio Code can be installed via 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. + +Alongside Rust Analyzer there are other extensions that might be very helpful: + +- [Even Better TOML][even-better-toml] for editing TOML-based configuration files +- [crates][crates] to help manage Rust dependencies + +[vscode]: https://code.visualstudio.com/ +[rust-analyzer]: https://rust-analyzer.github.io/ +[rust-analyzer-extension]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer +[language-server-protocol]: https://microsoft.github.io/language-server-protocol/ +[even-better-toml]: https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml +[crates]: https://marketplace.visualstudio.com/items?itemName=serayuzgur.crates + +## Tips and Tricks + +### Using Rust Analyzer with `no_std` + +If you are developing for a target that does not 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: + +```json +{ + "rust-analyzer.checkOnSave.allTargets": false +} +``` + +### Cargo hints when using custom toolchains + +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: + +```toml +[toolchain] +channel = "esp" +components = ["rustfmt", "rustc-dev"] +targets = ["xtensa-esp32-none-elf"] +``` + +## Other IDEs + +Eventhough we have only covered VS Code because it has good support for Rust and is very popular, there are other IDEs like [CLion][clion] or [vim][vim] that also have pretty good support for Rust, but we won't be covering them here. + +[cLion]: https://www.jetbrains.com/clion/ +[vim]: https://www.vim.org/ diff --git a/src/writing-your-own-application/generate-project/esp-idf-template.md b/src/writing-your-own-application/generate-project/esp-idf-template.md index 80f89748..78cff5f8 100644 --- a/src/writing-your-own-application/generate-project/esp-idf-template.md +++ b/src/writing-your-own-application/generate-project/esp-idf-template.md @@ -1,14 +1,16 @@ # Understanding esp-idf-template -Now that we know how to [generate a std project], let's inspect what the generated project contains and try to understand every part of it. +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. + +[generate-std]: ./index.md ## Inspecting the generated Project -When creating a project from [esp-idf-template] with the following answers: +When creating a project from [esp-idf-template][esp-idf-template] with the following answers: - Which MCU to target? · `esp32c3` - Configure advanced template options? · `false` -For this explanation we will use the default values, if you want further modifications, see the [additional prompts] when not using default values. +For this explanation we will use the default values, if you want further modifications, see the [additional prompts][prompts] when not using default values. It should generate a file structure like this: @@ -26,40 +28,53 @@ It should generate a file structure like this: Before going further, let's see what these files are for. -- [.cargo/config.toml] +- [.cargo/config.toml][config-toml] - The Cargo configuration - Contains our target - Contains `runner = "espflash flash --monitor"` - this means you can just use `cargo run` to flash and monitor your code - - Contains the linker to use, in our case, [`ldproxy`] + - Contains the linker to use, in our case, [`ldproxy`][ldproxy] - Contains the unstable `build-std` cargo feature enabled. - - Contains the `ESP-IDF-VERSION` environment variable that tells [`esp-idf-sys`] which ESP-IDF version the project will use. + - Contains the `ESP-IDF-VERSION` environment variable that tells [`esp-idf-sys`][esp-idf-sys] which ESP-IDF version the project will use. - src/main.rs - The main source file of the newly created project - - For details, see the [`main.rs`] section below. -- [.gitignore] + - For details, see the [Understanding `main.rs`][main-rs] section below. +- [.gitignore][gitignore] - Tells `git` which folders and files to ignore -- [build.rs] +- [build.rs][build-rs] - Propagates linker arguments for `ldproxy`. -- [Cargo.toml] +- [Cargo.toml][cargo-toml] - The usual Cargo manifest declaring some meta-data and dependencies of the project -- [rust-toolchain.toml] +- [rust-toolchain.toml][rust-toolchain-toml] - Defines which Rust toolchain to use - The toolchain will be `nightly` or `esp` depending on your target. -- [sdkconfig.defaults] +- [sdkconfig.defaults][sdkconfig-defaults] - Contains the overridden values from the ESP-IDF defaults. -## `main.rs` +[esp-idf-template]: https://github.com/esp-rs/esp-idf-template +[prompts]: https://github.com/esp-rs/esp-idf-template#generate-the-project +[main-rs]:#understanding-mainrs +[config-toml]: https://doc.rust-lang.org/cargo/reference/config.html +[ldproxy]: https://github.com/esp-rs/embuild/tree/master/ldproxy +[esp-idf-sys]: https://github.com/esp-rs/esp-idf-sys +[gitignore]: https://git-scm.com/docs/gitignore +[build-rs]: https://doc.rust-lang.org/cargo/reference/build-scripts.html +[cargo-toml]: https://doc.rust-lang.org/cargo/reference/manifest.html +[rust-toolchain-toml]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file +[sdkconfig-defaults]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html#custom-sdkconfig-defaults + +### Understanding `main.rs` ```rust,ignore -use esp_idf_sys as _; // If using the `binstart` feature of `esp-idf-sys`, always keep this module imported - -fn main() { - // It is necessary to call this function once. Otherwise some patches to the runtime - // implemented by esp-idf-sys might not link properly. See https://github.com/esp-rs/esp-idf-template/issues/71 - esp_idf_sys::link_patches(); - println!("Hello, world!"); -} +1 use esp_idf_sys as _; // If using the `binstart` feature of `esp-idf-sys`, always keep this module imported +2 +3 fn main() { +4 // It is necessary to call this function once. Otherwise some patches to the runtime +5 // implemented by esp-idf-sys might not link properly. See https://github.com/esp-rs/esp-idf-template/issues/71 +6 esp_idf_sys::link_patches(); +7 println!("Hello, world!"); +8 } ``` + 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. Then, we have a usual main function with a few lines on it: @@ -74,14 +89,15 @@ Building and running the code is as easy as cargo run ``` -This builds the code according to the configuration and executes [`espflash`] to flash the code to the board. +This builds the code according to the configuration and executes [`espflash`][espflash] to flash the code to the board. -Since our [`runner` configuration] also passes the `--monitor` argument to [`espflash`] we can see what the code is printing. +Since our [`runner` configuration][runner-config] also passes the `--monitor` argument to [`espflash`][espflash] we can see what the code is printing. -> Make sure that you have [`espflash`] installed, otherwise this step will fail. To install [`espflash`]: +> Make sure that you have [`espflash`][espflash] installed, otherwise this step will fail. To install [`espflash`][espflash] : > `cargo install espflash` You should see something similar to this: + ```text [2023-04-18T08:05:09Z INFO ] Connecting... [2023-04-18T08:05:10Z INFO ] Using flash stub @@ -94,93 +110,23 @@ MAC address: 60:55:f9:c0:39:7c App/part. size: 478,416/4,128,768 bytes, 11.59% [00:00:00] [========================================] 13/13 0x0 [00:00:00] [========================================] 1/1 0x8000 -[00:00:04] [========================================] 227/227 0x10000 [2023-04-18T08:05:15Z INFO ] Flashing has completed! +[00:00:04] [========================================] 227/227 0x10000 +[2023-04-18T08:05:15Z INFO ] Flashing has completed! Commands: CTRL+R Reset chip CTRL+C Exit -ESP-ROM:esp32c3-api1-20210207 -Build:Feb 7 2021 -rst:0x15 (USB_UART_CHIP_RESET),boot:0xc (SPI_FAST_FLASH_BOOT) -Saved PC:0x40380816 -0x40380816 - esp_restart_noos - at /home/sergio/Documents/Espressif/tests/esp-rust-app/.embuild/espressif/esp-idf/release-v4.4/components/esp_system/port/soc/esp32c3/system_internal.c:106 -SPIWP:0xee -mode:DIO, clock div:2 -load:0x3fcd5820,len:0x16ec -0x3fcd5820 - _bss_end - at ??:?? -load:0x403cc710,len:0x95c -0x403cc710 - _iram_data_start - at ??:?? -load:0x403ce710,len:0x2dc0 -0x403ce710 - _iram_data_start - at ??:?? -SHA-256 comparison failed: -Calculated: 692c10f3e7d531666ff34d02d3da161b3daa41ea629010d031fe3706fbada122 -Expected: 9fafed52ab0387e903bde368d0d6bfffe0dcc3d2f90dca069a4db891108c387c -Attempting to boot anyway... -entry 0x403cc710 -0x403cc710 - _iram_data_start - at ??:?? -I (43) boot: ESP-IDF v5.0-beta1-764-gdbcf640261 2nd stage bootloader -I (43) boot: compile time 11:30:26 -I (43) boot: chip revision: V003 -I (46) boot.esp32c3: SPI Speed : 40MHz -I (51) boot.esp32c3: SPI Mode : DIO -I (56) boot.esp32c3: SPI Flash Size : 4MB -I (61) boot: Enabling RNG early entropy source... -I (66) boot: Partition Table: -I (70) boot: ## Label Usage Type ST Offset Length -I (77) boot: 0 nvs WiFi data 01 02 00009000 00006000 -I (84) boot: 1 phy_init RF data 01 01 0000f000 00001000 -I (92) boot: 2 factory factory app 00 00 00010000 003f0000 -I (99) boot: End of partition table -I (103) esp_image: segment 0: paddr=00010020 vaddr=3c050020 size=23b88h (146312) map -I (144) esp_image: segment 1: paddr=00033bb0 vaddr=3fc8a000 size=00cd8h ( 3288) load -I (145) esp_image: segment 2: paddr=00034890 vaddr=40380000 size=09ea0h ( 40608) load -I (160) esp_image: segment 3: paddr=0003e738 vaddr=00000000 size=018e0h ( 6368) -I (161) esp_image: segment 4: paddr=00040020 vaddr=42000020 size=44c88h (281736) map -I (231) boot: Loaded app from partition at offset 0x10000 -I (231) boot: Disabling RNG early entropy source... -I (242) cpu_start: Pro cpu up. -I (251) cpu_start: Pro cpu start user code -I (251) cpu_start: cpu freq: 160000000 -I (251) cpu_start: Application information: -I (254) cpu_start: Project name: libespidf -I (259) cpu_start: App version: 1 -I (264) cpu_start: Compile time: Apr 18 2023 10:04:01 -I (270) cpu_start: ELF file SHA256: 0000000000000000... -I (276) cpu_start: ESP-IDF: 424ddb3-dirty -I (281) cpu_start: Min chip rev: v0.3 -I (286) cpu_start: Max chip rev: v0.99 -I (291) cpu_start: Chip rev: v0.3 -I (295) heap_init: Initializing. RAM available for dynamic allocation: -I (303) heap_init: At 3FC8BC00 len 00050B10 (322 KiB): DRAM -I (309) heap_init: At 3FCDC710 len 00002950 (10 KiB): STACK/DRAM -I (315) heap_init: At 50000020 len 00001FE0 (7 KiB): RTCRAM -I (323) spi_flash: detected chip: generic -I (327) spi_flash: flash io: dio -I (331) sleep: Configure to isolate all GPIO pins in sleep state -I (337) sleep: Enable automatic switching of GPIO sleep configuration +... I (344) cpu_start: Starting scheduler. Hello, world! ``` + As you can see, there are messages from the first and second stage bootloader and then, our "Hello, world!" is printed. You can reboot with `CTRL+R` or exit with `CTRL+C`. -[additional prompts]: https://github.com/esp-rs/esp-idf-template#generate-the-project -[.gitignore]: https://git-scm.com/docs/gitignore -[Cargo.toml]: https://doc.rust-lang.org/cargo/reference/manifest.html -[rust-toolchain.toml]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file -[.cargo/config.toml]: https://doc.rust-lang.org/cargo/reference/config.html -[generate a std project]: ./index.md -[esp-idf-template]: https://github.com/esp-rs/esp-idf-template -[`esp-idf-sys`]: https://github.com/esp-rs/esp-idf-sys -[`main.rs`]: #mainrs -[`ldproxy`]: https://github.com/esp-rs/embuild/tree/master/ldproxy -[build.rs]: https://doc.rust-lang.org/cargo/reference/build-scripts.html -[sdkconfig.defaults]: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/build-system.html#custom-sdkconfig-defaults -[`espflash`]: https://github.com/esp-rs/espflash/tree/main/espflash -[`runner` configuration]: https://doc.rust-lang.org/cargo/reference/config.html#targettriplerunner +If you encoutner any issues while building the project, please, see the [Troubleshooting][troubleshooting] chapter. + +[espflash]: https://github.com/esp-rs/espflash/tree/main/espflash +[runner-config]: https://doc.rust-lang.org/cargo/reference/config.html#targettriplerunner +[troubleshooting]: ../../misc/troubleshooting.md diff --git a/src/writing-your-own-application/generate-project/esp-template.md b/src/writing-your-own-application/generate-project/esp-template.md index 12f576e3..826e338e 100644 --- a/src/writing-your-own-application/generate-project/esp-template.md +++ b/src/writing-your-own-application/generate-project/esp-template.md @@ -1,16 +1,17 @@ # Understanding esp-template -Now that we know how to [generate a no_std project], let's inspect what the generated -project contains and try to understand every part of it. +Now that we know how to [generate a no_std project][generate-no-std], let's inspect what the generated +project contains, try to understand every part and run it. + +[generate-no-std]: ./index.md ## Inspecting the generated Project -When creating a project from [esp-template] with the following answers: +When creating a project from [esp-template][esp-template] with the following answers: - Which MCU to target? · `esp32c3` - Configure advanced template options? · `false` -For this explanation we will use the default values, if you want further modifications, see the [additional prompts] when not using default values. - +For this explanation we will use the default values, if you want further modifications, see the [additional prompts][prompts] when not using default values. It should generate a file structure like this: @@ -28,70 +29,49 @@ It should generate a file structure like this: Before going further, let's see what these files are for. -- [.cargo/config.toml] +- [.cargo/config.toml][config-toml] - The Cargo configuration - This defines a few options to correctly build the project - Contains `runner = "espflash flash --monitor"` - this means you can just use `cargo run` to flash and monitor your code - src/main.rs - The main source file of the newly created project - - For details, see the [`main.rs`] section below. -- [.gitignore] + - For details, see the [Understanding `main.rs`][main-rs] section below. +- [.gitignore][gitignore] - Tells `git` which folders and files to ignore -- [Cargo.toml] +- [Cargo.toml][cargo-toml] - The usual Cargo manifest declaring some meta-data and dependencies of the project - LICENSE-APACHE, LICENSE_MIT - Those are the most common licenses used in the Rust ecosystem - If you want to apply a different license, you can delete these files and change the license in `Cargo.toml` -- [rust-toolchain.toml] +- [rust-toolchain.toml][rust-toolchain-toml] - Defines which Rust toolchain to use - The toolchain will be `nightly` or `esp` depending on your target. -## `main.rs` +[esp-template]: https://github.com/esp-rs/esp-template +[prompts]: https://github.com/esp-rs/esp-template#esp-template +[main-rs]: #understanding-mainrs +[cargo-toml]: https://doc.rust-lang.org/cargo/reference/manifest.html +[gitignore]: https://git-scm.com/docs/gitignore +[config-toml]: https://doc.rust-lang.org/cargo/reference/config.html +[rust-toolchain-toml]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file -```rust,ignore -#![no_std] -#![no_main] - -use esp_backtrace as _; -use esp_println::println; -use hal::{clock::ClockControl, peripherals::Peripherals, prelude::*, timer::TimerGroup, Rtc}; - -#[entry] -fn main() -> ! { - let peripherals = Peripherals::take(); - let mut system = peripherals.SYSTEM.split(); - let clocks = ClockControl::boot_defaults(system.clock_control).freeze(); - - // Disable the RTC and TIMG watchdog timers - let mut rtc = Rtc::new(peripherals.RTC_CNTL); - let timer_group0 = TimerGroup::new( - peripherals.TIMG0, - &clocks, - &mut system.peripheral_clock_control, - ); - let mut wdt0 = timer_group0.wdt; - let timer_group1 = TimerGroup::new( - peripherals.TIMG1, - &clocks, - &mut system.peripheral_clock_control, - ); - rtc.swd.disable(); - rtc.rwdt.disable(); - wdt0.disable(); - wdt1.disable(); - - println!("Hello world!"); - - loop {} -} -``` +### Understanding `main.rs` -That is quite a lot of code. Let's see what it is good for. +```rust,ignore + 1 #![no_std] + 2 #![no_main] + ``` - `#![no_std]` - This tells the Rust compiler that this code doesn't use `libstd` - `#![no_main]` - - The `no_main` attribute says that this program won't use the standard main interface, which is tailored for command-line applications that receive arguments. Instead of the standard main, we'll use the entry attribute from the `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]. I.e. it has the signature `fn foo() -> !`; this type indicates that the function never returns – which means that the program never terminates. + - The `no_main` attribute says that this program won't use the standard main interface, which is tailored for command-line applications that receive arguments. Instead of the standard main, we'll use the entry attribute from the `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. + +```rust,ignore + 4 use esp_backtrace as _; + 5 use esp_println::println; + 6 use hal::{clock::ClockControl, peripherals::Peripherals, prelude::*, timer::TimerGroup, Rtc}; +``` - `use esp_backtrace as _;` - Since we are in a bare-metal environment, we need a panic-handler that runs if a panic occurs in code - 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`/`espmonitor` these addresses can get decoded into source code locations @@ -100,6 +80,38 @@ That is quite a lot of code. Let's see what it is good for. - `use hal:{...}` - We need to bring in some types we are going to use - These are from `esp-hal` + +```rust,ignore + 8 #[entry] + 9 fn main() -> ! { +10 let peripherals = Peripherals::take(); +11 let mut system = peripherals.SYSTEM.split(); +12 let clocks = ClockControl::boot_defaults(system.clock_control).freeze(); +13 +14 // Disable the RTC and TIMG watchdog timers +15 let mut rtc = Rtc::new(peripherals.RTC_CNTL); +16 let timer_group0 = TimerGroup::new( +17 peripherals.TIMG0, +18 &clocks, +19 &mut system.peripheral_clock_control, +20 ); +21 let mut wdt0 = timer_group0.wdt; +22 let timer_group1 = TimerGroup::new( +23 peripherals.TIMG1, +24 &clocks, +25 &mut system.peripheral_clock_control, +26 ); +27 rtc.swd.disable(); +28 rtc.rwdt.disable(); +29 wdt0.disable(); +30 wdt1.disable(); +31 +32 println!("Hello world!"); +33 +34 loop {} +35 } +``` +Inside the `main` function we can find: - `let peripherals = Peripherals::take().unwrap();` - HAL drivers usually take ownership of peripherals accessed via the PAC - Here we take all the peripherals from the PAC to pass them to the HAL drivers later @@ -111,12 +123,15 @@ That is quite a lot of code. Let's see what it is good for. - Some drivers need a reference to the clocks to know how to calculate rates and durations - The next block of code instantiates some peripherals (namely RTC and the two timer groups) to disable the watchdog, which is armed after boot - Without that code, the SoC would reboot after some time - - There is another way to prevent the reboot: [feeding](https://docs.rs/esp32c3-hal/0.10.0/esp32c3_hal/prelude/trait._embedded_hal_watchdog_Watchdog.html#tymethod.feed) the watchdog + - There is another way to prevent the reboot: [feeding][wtd-feeding] the watchdog - `println!("Hello world!");` - Prints "Hello Wolrd!" - `loop {}` - Since our function is supposed to never return, we just "do nothing" in a loop +[diverging-function]: https://doc.rust-lang.org/beta/rust-by-example/fn/diverging.html +[wtd-feeding]: https://docs.rs/esp32c3-hal/0.10.0/esp32c3_hal/prelude/trait._embedded_hal_watchdog_Watchdog.html#tymethod.feed + ## Running the Code Building and running the code is as easy as @@ -125,14 +140,15 @@ Building and running the code is as easy as cargo run ``` -This builds the code according to the configuration and executes [`espflash`] to flash the code to the board. +This builds the code according to the configuration and executes [`espflash`][espflash] to flash the code to the board. -Since our [`runner` configuration] also passes the `--monitor` argument to [`espflash`] we can see what the code is printing. +Since our [`runner` configuration][runner-config] also passes the `--monitor` argument to [`espflash`][espflash] we can see what the code is printing. -> Make sure that you have [`espflash`] installed, otherwise this step will fail. To install [`espflash`]: +> Make sure that you have [`espflash`][espflash] installed, otherwise this step will fail. To install [`espflash`][espflash]: > `cargo install espflash` You should see something similar to this: + ```text [2023-04-17T14:17:08Z INFO ] Serial port: '/dev/ttyACM0' [2023-04-17T14:17:08Z INFO ] Connecting... @@ -146,54 +162,13 @@ MAC address: 60:55:f9:c0:39:7c App/part. size: 203,920/4,128,768 bytes, 4.94% [00:00:00] [========================================] 13/13 0x0 [00:00:00] [========================================] 1/1 0x8000 -[00:00:01] [========================================] 64/64 0x10000 [2023-04-17T14:17:11Z INFO ] Flashing has completed! +[00:00:01] [========================================] 64/64 0x10000 +[2023-04-17T14:17:11Z INFO ] Flashing has completed! Commands: CTRL+R Reset chip CTRL+C Exit -ESP-ROM:esp32c3-api1-20210207 -Build:Feb 7 2021 -rst:0x15 (USB_UART_CHIP_RESET),boot:0xc (SPI_FAST_FLASH_BOOT) -Saved PC:0x40380816 -0x40380816 - - at ??:?? -SPIWP:0xee -mode:DIO, clock div:2 -load:0x3fcd5820,len:0x16ec -0x3fcd5820 - _stack_start - at ??:?? -load:0x403cc710,len:0x95c -0x403cc710 - - at ??:?? -load:0x403ce710,len:0x2dc0 -0x403ce710 - - at ??:?? -SHA-256 comparison failed: -Calculated: 692c10f3e7d531666ff34d02d3da161b3daa41ea629010d031fe3706fbada122 -Expected: 9fafed52ab0387e903bde368d0d6bfffe0dcc3d2f90dca069a4db891108c387c -Attempting to boot anyway... -entry 0x403cc710 -0x403cc710 - - at ??:?? -I (43) boot: ESP-IDF v5.0-beta1-764-gdbcf640261 2nd stage bootloader -I (43) boot: compile time 11:30:26 -I (43) boot: chip revision: V003 -I (46) boot.esp32c3: SPI Speed : 40MHz -I (51) boot.esp32c3: SPI Mode : DIO -I (56) boot.esp32c3: SPI Flash Size : 4MB -I (61) boot: Enabling RNG early entropy source... -I (66) boot: Partition Table: -I (70) boot: ## Label Usage Type ST Offset Length -I (77) boot: 0 nvs WiFi data 01 02 00009000 00006000 -I (84) boot: 1 phy_init RF data 01 01 0000f000 00001000 -I (92) boot: 2 factory factory app 00 00 00010000 003f0000 -I (99) boot: End of partition table -I (103) esp_image: segment 0: paddr=00010020 vaddr=3c030020 size=05f74h ( 24436) map -I (117) esp_image: segment 1: paddr=00015f9c vaddr=40380000 size=007f8h ( 2040) load -I (121) esp_image: segment 2: paddr=0001679c vaddr=00000000 size=0987ch ( 39036) -I (137) esp_image: segment 3: paddr=00020020 vaddr=42000020 size=21c40h (138304) map -I (168) boot: Loaded app from partition at offset 0x10000 -I (168) boot: Disabling RNG early entropy source... +... Hello world! ``` @@ -203,14 +178,8 @@ And that is exactly what the code is doing. You can reboot with `CTRL+R` or exit with `CTRL+C`. -[additional prompts]: https://github.com/esp-rs/esp-template#esp-template -[`main.rs`]: #mainrs -[generate a no_std project]: ./index.md -[esp-template]: https://github.com/esp-rs/esp-template -[.gitignore]: https://git-scm.com/docs/gitignore -[Cargo.toml]: https://doc.rust-lang.org/cargo/reference/manifest.html -[rust-toolchain.toml]: https://rust-lang.github.io/rustup/overrides.html#the-toolchain-file -[.cargo/config.toml]: https://doc.rust-lang.org/cargo/reference/config.html -[`espflash`]: https://github.com/esp-rs/espflash/tree/main/espflash -[`runner` configuration]: https://doc.rust-lang.org/cargo/reference/config.html#targettriplerunner -[diverging function]: https://doc.rust-lang.org/beta/rust-by-example/fn/diverging.html +If you encoutner any issues while building the project, please, see the [Troubleshooting][troubleshooting] chapter. + +[espflash]: https://github.com/esp-rs/espflash/tree/main/espflash +[runner-config]: https://doc.rust-lang.org/cargo/reference/config.html#targettriplerunner +[troubleshooting]: ../../misc/troubleshooting.md diff --git a/src/writing-your-own-application/generate-project/index.md b/src/writing-your-own-application/generate-project/index.md index 34f2933e..57d8917d 100644 --- a/src/writing-your-own-application/generate-project/index.md +++ b/src/writing-your-own-application/generate-project/index.md @@ -1,10 +1,10 @@ # Generating Projects from Templates We currently maintain two template repositories: -- [esp-template] - `no_std` template. -- [esp-idf-template] - `std` template. +- [esp-template][esp-template] - `no_std` template. +- [esp-idf-template][esp-idf-template] - `std` template. -Both templates are based on [cargo-generate], a tool that allows you to create a new project based on some existing template. In our case [esp-idf-template] or [esp-template] can be used to generate an application with all the required configuration and dependencies. +Both templates are 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] or [esp-template][esp-template] can be used to generate an application with all the required configuration and dependencies. 1. Install `cargo generate`: ```shell @@ -15,38 +15,34 @@ Both templates are based on [cargo-generate], a tool that allows you to create a ```shell cargo generate esp-rs/esp-template ``` - See [Understanding esp-template] for more details on the template project. + See [Understanding esp-template][understanding-esp-template] for more details on the template project. - esp-idf-template: ```shell cargo generate esp-rs/esp-idf-template cargo ``` - See [Understanding esp-idf-template] for more details on the template project. + See [Understanding esp-idf-template][understanding-esp-idf-template] for more details on the template project. When the `cargo generate` subcommand is invoked, you will be prompted to answer a number of questions regarding the target of your application. Upon completion of this process, you will have a buildable project with all the correct configuration. 3. Build/Run the generated project: - - Using `cargo build` will compile the project using the appropriate toolchain and target. - - Using `cargo run` will compile the project, flash it, and open a serial monitor with our chip. + - Use `cargo build` to compile the project using the appropriate toolchain and target. + - Use `cargo run` to compile the project, flash it, and open a serial monitor with our target device. -## Using Dev Containers in the templates +[cargo-generate]: https://github.com/cargo-generate/cargo-generate +[esp-idf-template]: https://github.com/esp-rs/esp-idf-template +[esp-template]: https://github.com/esp-rs/esp-template +[understanding-esp-template]: ./esp-template.md +[understanding-esp-idf-template]: ./esp-idf-template.md -Both template repositories have a prompt for Dev Containers support, when using Dev Containers in the templates it will add support for: -- [VS Code Dev Containers] -- [GitHub Codespaces] +## Using Dev Containers in the templates -Dev Containers use the [`idf-rust` container image], that was explained in the [Using Container section] of the installation chapter, and provide an environment ready to develop Rust applications for Espressif chips with no installation required. Dev Containers also have integration with [Wokwi simulator], to simulate the project, and allow flashing from the container using [web flash]. +Both template repositories have a prompt for Dev Containers support, see details in [Dev Container][dev-container] section of the template README. -For more details on Dev Containers, see [Dev Container] section of the template README. +Dev Containers use the [`idf-rust`][idf-rust] container image, that 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]. -[cargo-generate]: https://github.com/cargo-generate/cargo-generate -[esp-idf-template]: https://github.com/esp-rs/esp-idf-template -[esp-template]: https://github.com/esp-rs/esp-template -[VS Code Dev Containers]: https://code.visualstudio.com/docs/remote/containers#_quick-start-open-an-existing-folder-in-a-container -[GitHub Codespaces]: https://docs.github.com/en/codespaces/developing-in-codespaces/creating-a-codespace -[Using Container section]: ../../installation/index.md#using-containers -[Wokwi simulator]: https://wokwi.com/ -[web flash]: https://github.com/bjoernQ/esp-web-flash-server -[Dev Container]: https://github.com/esp-rs/esp-template/tree/main/docs#dev-containers -[Understanding esp-template]: ./esp-template.md -[Understanding esp-idf-template]: ./esp-idf-template.md -[`idf-rust` container image]: https://hub.docker.com/r/espressif/idf-rust/tags +[dev-container]: https://github.com/esp-rs/esp-template/tree/main/docs#dev-containers +[idf-rust]: https://hub.docker.com/r/espressif/idf-rust/tags +[using-container]: ../../installation/using-containers.md +[wokwi]: https://wokwi.com/ +[web-flash]: https://github.com/bjoernQ/esp-web-flash-server +[setting-env]: ../../installation/index.md diff --git a/src/writing-your-own-application/index.md b/src/writing-your-own-application/index.md index d0dd46f6..cf02ca13 100644 --- a/src/writing-your-own-application/index.md +++ b/src/writing-your-own-application/index.md @@ -4,13 +4,12 @@ With the appropriate Rust compiler and toolchain installed, you're now ready to You can write an application in the following ways: -- Generate from a template: (**Strongly recommended**). Gives you a configured project, saves time and prevents possible errors. +- (**Strongly recommended**) Generate from a template: Gives you a configured project, saves time and prevents possible errors. - Start from scratch using Cargo: Requires more expertise since you need to configure several parts of the project. - > Note: Starting a project with Cargo does not provide any advantage, only mentioned here since it's the usual way of generating a project in Rust. + > ⚠️ **Note**: Starting a project with Cargo does not provide any advantage, only mentioned here since it's the usual way of generating a project in Rust. +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. -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 template project. - -During this chapter, we will use some tools that will be covered in more details in the next chapter, [Tooling][tooling], feel free to peek into it when required. +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. [tooling]: ../tooling/index.md diff --git a/src/writing-your-own-application/nostd.md b/src/writing-your-own-application/nostd.md index 7308119f..6d83c0c3 100644 --- a/src/writing-your-own-application/nostd.md +++ b/src/writing-your-own-application/nostd.md @@ -1,22 +1,27 @@ # Writing no_std applications -If you want to learn how to develop `no_std` application, there is training developed for this: -- [Book of training] -- [Repository of the training] +If you want to learn how to develop `no_std` application, see the following training materials: +- The book [Embedded Rust (no_std) on Espressif][no-std-book] +- The repository [esp-rs/no_std-training][no-std-repository] -The training is based on [ESP32-C3-DevKit-RUST-1]. You can use any other Espressif development board but code changes and configuration changes might be needed. +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. The training contains: * Introductory level examples: - * A basic hello-world ([Source](https://github.com/esp-rs/no_std-training/tree/main/intro/hello-world)) - * A panic example ([Source](https://github.com/esp-rs/no_std-training/tree/main/intro/panic)) - * A blinky example ([Source](https://github.com/esp-rs/no_std-training/tree/main/intro/blinky)) - * A button example ([Source](https://github.com/esp-rs/no_std-training/tree/main/intro/button)) - * A button with interrupt example ([Source](https://github.com/esp-rs/no_std-training/tree/main/intro/button-interrupt)) + * A basic hello-world ([Source][hello-world]) + * A panic example ([Source][panic]) + * A blinky example ([Source][blinky]) + * A button example ([Source][button]) + * A button with interrupt example ([Source][button-interrupt]) -> Note that there are several examples covering the use of specific peripherals under the examples' folder of every SoC [`esp-hal`]. E.g. [`esp32c3-hal/examples`] +> ⚠️ **Note**: There are several examples covering the use of specific peripherals under the examples' folder of every SoC [`esp-hal`][esp-hal]. E.g. [`esp32c3-hal/examples`][esp32c3-hal-examples] -[Book of training]: https://esp-rs.github.io/no_std-training/ -[Repository of the training]: https://github.com/esp-rs/no_std-training -[ESP32-C3-DevKit-RUST-1]: https://github.com/esp-rs/esp-rust-board -[`esp-hal`]: https://github.com/esp-rs/esp-hal -[`esp32c3-hal/examples`]: https://github.com/esp-rs/esp-hal/tree/main/esp32c3-hal/examples +[no-std-book]: https://esp-rs.github.io/no_std-training/ +[no-std-repository]: https://github.com/esp-rs/no_std-training +[esp-rust-board]: https://github.com/esp-rs/esp-rust-board +[hello-world]: https://github.com/esp-rs/no_std-training/tree/main/intro/hello-world +[panic]: https://github.com/esp-rs/no_std-training/tree/main/intro/panic +[blinky]: https://github.com/esp-rs/no_std-training/tree/main/intro/blinky +[button]: https://github.com/esp-rs/no_std-training/tree/main/intro/button +[button-interrupt]: https://github.com/esp-rs/no_std-training/tree/main/intro/button-interrupt +[esp-hal]: https://github.com/esp-rs/esp-hal +[esp32c3-hal-examples]: https://github.com/esp-rs/esp-hal/tree/main/esp32c3-hal/examples diff --git a/src/writing-your-own-application/std.md b/src/writing-your-own-application/std.md index d7afba88..cd70d2dd 100644 --- a/src/writing-your-own-application/std.md +++ b/src/writing-your-own-application/std.md @@ -1,36 +1,40 @@ # Writing std applications -If you want to learn how to develop `std` application, there is a training developed -alongside [Ferrous Systems]: +If you want to learn how to develop `std` application, see the following training materials developed alongside [Ferrous Systems][ferrous-systems]: +- The book [Embedded Rust on Espressif][std-book] +- The repository [esp-rs/std-training][std-repository] -- [Book of training] -- [Repository of the training] - -The training is based on [ESP32-C3-DevKit-RUST-1]. You can use any other Espressif development board, but code changes and configuration changes might be needed. +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. The training is split into two parts: -* [Introductory level examples]: - * A basic hardware-check ([Source](https://github.com/esp-rs/std-training/tree/main/intro/hardware-check)) - * An HTTP Client ([Source](https://github.com/esp-rs/std-training/tree/main/intro/http-client)) - * An HTTP Server ([Source](https://github.com/esp-rs/std-training/tree/main/intro/http-server)) - * An MQTT Client ([Source](https://github.com/esp-rs/std-training/tree/main/intro/mqtt)) -* [Advanced level examples]: +* [Introductory level examples][intro]: + * A basic hardware-check ([Source][hardware-check]s) + * An HTTP Client ([Source][http-client]) + * An HTTP Server ([Source][http-server]) + * An MQTT Client ([Source][mqtt]) +* [Advanced level examples][advanced]: * Low-level GPIO * Interrupts in General - * I2C Driver ([Source](https://github.com/esp-rs/std-training/tree/main/advanced/i2c-driver)) - * I2C Sensor Reading ([Source](https://github.com/esp-rs/std-training/tree/main/advanced/i2c-sensor-reading)) - * GPIO/Button Interrupts ([Source](https://github.com/esp-rs/std-training/tree/main/advanced/button-interrupt)) + * I2C Driver ([Source][i2c-driver]) + * I2C Sensor Reading ([Source][i2c-sensor-reading]) + * GPIO/Button Interrupts ([Source][button-interrupt]) * Driving an RGB LED - -> Note that there are several examples covering the use of specific peripherals under the examples' folder of [`esp-idf-hal`]. I.e. [`esp-idf-hal/examples`]. - -[Ferrous Systems]: https://ferrous-systems.com/ -[Book of training]: https://esp-rs.github.io/std-training/ -[Repository of the training]: https://github.com/esp-rs/std-training -[ESP32-C3-DevKit-RUST-1]: https://github.com/esp-rs/esp-rust-board -[Introductory level examples]: https://github.com/esp-rs/std-training/tree/main/intro -[Advanced level examples]: https://github.com/esp-rs/std-training/tree/main/advanced -[`esp-idf-hal/examples`]: https://github.com/esp-rs/esp-idf-hal/tree/master/examples -[`esp-idf-hal`]: https://github.com/esp-rs/esp-idf-hal +> ⚠️ **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]. + +[ferrous-systems]: https://ferrous-systems.com/ +[std-book]: https://esp-rs.github.io/std-training/ +[std-repository]: https://github.com/esp-rs/std-training +[esp-rust-board]: https://github.com/esp-rs/esp-rust-board +[intro]: https://github.com/esp-rs/std-training/tree/main/intro +[hardware-check]: https://github.com/esp-rs/std-training/tree/main/intro/hardware-check +[http-client]: https://github.com/esp-rs/std-training/tree/main/intro/http-client +[http-server]: https://github.com/esp-rs/std-training/tree/main/intro/http-server +[mqtt]: https://github.com/esp-rs/std-training/tree/main/intro/mqtt +[advanced]: https://github.com/esp-rs/std-training/tree/main/advancedç +[i2c-driver]: https://github.com/esp-rs/std-training/tree/main/advanced/i2c-driver +[i2c-sensor-reading]: https://github.com/esp-rs/std-training/tree/main/advanced/i2c-sensor-reading +[button-interrupt]: https://github.com/esp-rs/std-training/tree/main/advanced/button-interrupt +[esp-idf-hal-examples]: https://github.com/esp-rs/esp-idf-hal/tree/master/examples +[esp-idf-hal]: https://github.com/esp-rs/esp-idf-hal