diff --git a/README.md b/README.md index 23f8759e..2fe9e532 100644 --- a/README.md +++ b/README.md @@ -7,15 +7,15 @@ This book is a work in progress. This book is generated using [mdbook], and additionally uses the [mdbook-mermaid] preprocessor to add support for diagrams. To install these tools: ```shell -$ cargo install mdbook mdbook-mermaid +cargo install mdbook mdbook-mermaid ``` With `mdbook` and `mdbook-mermaid` installed you can clone the respository and start a development server by running: ```shell -$ git clone https://github.com/esp-rs/book -$ cd book/ -$ mdbook serve +git clone https://github.com/esp-rs/book +cd book/ +mdbook serve ``` [mdbook]: https://github.com/rust-lang/mdBook diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 429e2a8a..19f1d95e 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -5,10 +5,10 @@ - [Using the Standard Library (`std`)](./overview/using-the-standard-library.md) - [Bare Metal (`no_std`)](./overview/bare-metal.md) - [Comparing `std` and `no_std`](./overview/comparing-std-and-no_std.md) -- [Required Dependencies](./dependencies/index.md) - - [Installing Rust](./dependencies/installing-rust.md) - - [Build Tools](./dependencies/build-tools.md) -- [Tooling]() +- [Installation](./installation/index.md) + - [Rust on Espressif SoCs](installation/rust-on-esp.md) + - [Installing Rust for Espressif SoCs](./installation/installing-rust-for-esp.md) +- [Tooling](./tooling/index.md) - [Text Editors and IDEs](./tooling/text-editors-and-ides.md) - [espflash](./tooling/espflash.md) - [espmonitor](./tooling/espmonitor.md) @@ -16,11 +16,14 @@ - [probe-rs](./tooling/debugging/probe-rs.md) - [OpenOCD](./tooling/debugging/openocd.md) - [Debugging in Visual Studio Code](./tooling/debugging/vscode-debugging.md) -- [Writing Your Application]() - - [Generate Project from Template](./writing-your-application/generate-project-from-template.md) - - [Writing `std` Applications](./writing-your-application/writing-std-applications.md) + - [Simulating](./tooling/simulating/index.md) + - [Wokwi](./tooling/simulating/wokwi.md) + - [QEMU](tooling/simulating/qemu.md) +- [Writing Your Own Application](./writing-your-own-application/index.md) + - [Generate Project from Template](./writing-your-own-application/generate-project-from-template.md) + - [Writing `std` Applications](./writing-your-own-application/writing-std-applications.md) - [Writing `no_std` Applications (TODO)]() - +- [Resources](./resources.md) --- [Appendix A: Glossary](./misc/glossary.md) diff --git a/src/dependencies/build-tools.md b/src/dependencies/build-tools.md deleted file mode 100644 index 82558008..00000000 --- a/src/dependencies/build-tools.md +++ /dev/null @@ -1,15 +0,0 @@ -# Build Tools - -## ldproxy - -When building applications using the Rust standard library, `std`, the build tool `ldproxy` is required and must be installed first; this tool can be found in the [embuild repository]. This tool is _not_ required for `no_std` applications. - -`ldproxy` is a simple tool to forward linker arguments given to `ldproxy` to the actual linker executable. - -To install: - -```bash -$ cargo install ldproxy -``` - -[embuild repository]: https://github.com/esp-rs/embuild diff --git a/src/dependencies/index.md b/src/dependencies/index.md deleted file mode 100644 index 567a265d..00000000 --- a/src/dependencies/index.md +++ /dev/null @@ -1,7 +0,0 @@ -# Required Dependencies - -With an understanding of the ecosystem surrounding Rust on Espressif chips, we're able to move on to actual development. If you are not aware of the two possible development approaches, or do not understand the differences between writing `std` and `no_std` applications, please first read the [Ecosystem Overview] chapter. - -In this chapter we will cover the installation of the correct Rust compiler and toolchain as well as creating applications. - -[ecosystem overview]: ../overview/index.md diff --git a/src/dependencies/installing-rust.md b/src/dependencies/installing-rust.md deleted file mode 100644 index 6f7aa53c..00000000 --- a/src/dependencies/installing-rust.md +++ /dev/null @@ -1,176 +0,0 @@ -# Installing Rust - -In order to develop for ESP devices using Rust you must first install the Rust compiler along with the appropriate toolchain and target(s). Depending on your device it may be one of two architectures, each requiring different setup. - -If you have not yet installed Rust on your system, you can do so easily using [rustup]. For _macOS_ and _Linux_ it can be installed by runing the following command: - -```bash -$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -``` - -For installation on Windows or alternative installation methods, please refer to the instructions on the [rustup] website. - -With Rust installed we next need to ensure that the `nightly` toolchain is installed and set as the default: - -```bash -$ rustup toolchain install nightly -$ rustup default nightly -``` - -You can read more about toolchains in the [rustup book]. - -[rustup]: https://rustup.rs/ -[rustup book]: https://rust-lang.github.io/rustup/concepts/toolchains.html - -## Prerequisites - -### git - -`git` must be installed on your system in order to clone repositories. This should be available via your system's package manager, or for Windows users [Git for Windows] can be used. - -[git for windows]: https://gitforwindows.org/ - -### Visual Studio Build Tools - -If you are running Windows as your host operating system, you must install the Visual Studio Build Tools, which can be downloaded from the [Microsoft website]. - -[microsoft website]: https://visualstudio.microsoft.com/downloads/ - -### Xtensa Toolchain - -If you are developing for an Xtensa chip (_ESP32_, _ESP32-S2_, _ESP32-S3_) you must also install the appropriate Xtensa toolchain. Pre-built toolchains can be downloaded from the [crosstool-NG] repository for the most common operating systems and architectures. - -Ensure that you have downloaded the required toolchain and added its directory to your `PATH` environment variable prior to building your application. - -[crosstool-ng]: https://github.com/espressif/crosstool-NG - -## RISC-V (ESP32-C3) - -The `RISC-V` architecture has support in the mainline Rust compiler so setup is relatively simple, all we must do is add the appropriate compilation target. - -There are two suitable targets for this chip: - -- For bare-metal (`no_std`) applications, use `riscv32imc-unknown-none-elf` -- For applications which require `std`, use `riscv32imc-esp-espidf` - -The bare-metal target can be installed by running: - -```bash -$ rustup target add riscv32imc-unknown-none-elf -``` - -The standard library target (`riscv32imc-esp-espidf`) is currently Tier 3, and does not have prebuilt objects distributed through `rustup`, therefore the `-Z build-std` unstable cargo feature is required within your project. See an example usage in [rust-esp32-std-mini](https://github.com/ivmarkov/rust-esp32-std-mini/blob/5fe3a5d75b16c6cee63e4c36b87f936744151494/.cargo/config.toml#L25-L26). - -At this point you are ready to build applications for the ESP32-C3. - -[rustup]: https://rustup.rs/ -[esp-idf]: https://github.com/espressif/esp-idf - -## Xtensa (ESP32, ESP32-S2, ESP32-S3) - -Because there is no `Xtensa` support in the mainline Rust compiler you must use the [esp-rs/rust] fork instead. There are a few options available for installing this compiler fork. - -The forked compiler can coexist with the standard Rust compiler, so it is possible to have both installed on your system. The forked compiler is invoked when using the `esp` channel instead of the defaults, `stable` or `nightly`. - -[esp-rs/rust]: https://github.com/esp-rs/rust - -### Using a Pre-Built Release - -Pre-built releases are available for a number of platforms on GitHub under the [esp-rs/rust-build] repository. The following operating systems and architectures are currently supported: - -- macOS (`x86_64`, `aarch64`) -- Windows (`x86_64`) -- Linux (`x86_64`) - -The aforementioned repository also contains Bash and PowerShell scripts to automate the installation process. - -#### macOS and Linux - -```bash -$ curl -LO https://raw.githubusercontent.com/esp-rs/rust-build/main/install-rust-toolchain.sh -$ chmod +x install-rust-toolchain.sh -$ ./install-rust-toolchain.sh -``` - -#### Windows - -With GUI installer: [https://github.com/espressif/idf-installer/releases] - -With PowerShell: - -```powershell -PS> Invoke-WebRequest https://raw.githubusercontent.com/esp-rs/rust-build/main/Install-RustToolchain.ps1 -OutFile Install-RustToolchain.ps1 -PS> Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force -PS> ./Install-RustToolchain.ps1 -``` - -To confirm the `esp` toolchain has been installed: - -```bash -$ rustup toolchain list -stable-x86_64-apple-darwin -nightly-x86_64-apple-darwin (default) -esp -``` - -[esp-rs/rust-build]: https://github.com/esp-rs/rust-build -[https://github.com/espressif/idf-installer/releases]: https://github.com/espressif/idf-installer/releases - -### Building From Source - -You can also build 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 recommended that you have _at least_ 6GB of RAM and 25GB+ of available storage space. - -To check out the repository and build the compiler: - -```bash -$ git clone https://github.com/esp-rs/rust -$ cd rust -$ ./configure --experimental-targets=Xtensa -$ ./x.py build --stage 2 -``` - -Note that you should _not_ rename the `rust` directory to avoid issues while building. - -Once the build has completed, you can link the toolchain using rustup (your architecture/operating system may be different): - -```bash -$ rustup toolchain link esp $PWD/build/x86_64-apple-darwin/stage2 -``` - -Once the compiler fork has been installed using one of the above methods, to confirm the `esp` toolchain has been installed: - -```bash -$ rustup toolchain list -stable-x86_64-apple-darwin -nightly-x86_64-apple-darwin (default) -esp -``` - -To view the installed `Xtensa` targets: - -```bash -$ rustc +esp --print target-list | grep xtensa -xtensa-esp32-espidf -xtensa-esp32-none-elf -xtensa-esp32s2-espidf -xtensa-esp32s2-none-elf -xtensa-esp8266-none-elf -xtensa-none-elf -``` - -### Using Containers - -As an alternative to installing the compiler fork to your local system directly, it's also possible to run it inside of a container. - -A number of container runtimes are available, and which should be used depends on your operating system. Some of the popular options are: - -- [Docker] (non-commerial use only without a license) -- [Podman] -- [Lima] - -Espressif provides the [idf-rust] container image which contains [esp-idf] and the pre-built Rust compiler fork. - -[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 diff --git a/src/installation/index.md b/src/installation/index.md new file mode 100644 index 00000000..aa39c3f7 --- /dev/null +++ b/src/installation/index.md @@ -0,0 +1,27 @@ +# Installation + +With an understanding of the ecosystem surrounding Rust on Espressif chips, we can move on to actual development. If you are not aware of the two possible development approaches or do not understand the differences between writing `std` and `no_std` applications, please first read the [Ecosystem Overview] chapter. + +The dependencies required to build Rust applications for ESP Chips depend on the approach that we take. + +## `no_std` Applications + +- GCC Toolchain: GCC linker is used in our Rust applications. +- Rust Toolchain: Used to compile our Rust code. + - `LLVM`: The Rust compiler uses `LLVM` as codegen backend. + +## `std` Applications + +- GCC Toolchain: GCC linker is used in our Rust applications. +- Rust Toolchain: Used to compile our Rust code. + - `LLVM`: The Rust compiler uses `LLVM` as codegen backend. +- [ESP-IDF]: Espressif IoT Development Framework. +- [`ldproxy`] crate: Simple tool to forward linker arguments given to [`ldproxy`] to the actual linker executable. The crate can be found in the [esp-rs/embuild] repository. + +This chapter, will cover how to properly install the correct Rust compiler and toolchain for our ESP chips. + +[Ecosystem Overview]: ../overview/index.md +[ESP-IDF]: https://github.com/espressif/esp-idf +[`std` overview]: src\overview\using-the-standard-library.md +[`ldproxy`]: https://github.com/esp-rs/embuild/tree/master/ldproxy +[esp-rs/embuild]: https://github.com/esp-rs/embuild diff --git a/src/installation/installing-rust-for-esp.md b/src/installation/installing-rust-for-esp.md new file mode 100644 index 00000000..b115d43a --- /dev/null +++ b/src/installation/installing-rust-for-esp.md @@ -0,0 +1,135 @@ +# Installing Rust for Espressif SoCs + +## Rust installation + +In order to develop applications for ESP devices using Rust you must first install the Rust compiler along with the appropriate toolchain and target(s). Depending on your device it may be one of two architectures, each requiring a different setup. + +If you have not yet installed Rust on your system, you can do so easily using [rustup]. For _macOS_ and _Linux_ it can be installed by running the following command: + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +For installation on Windows or alternative installation methods, please refer to the instructions on the [rustup] website. + +If you are [running Windows as your host operating system, you must also install one of the available ABIs]: +- MSVC: This is the recommended ABI. When installing `rustup`, it will check if all the requirements are installed, and, if they are not, it allows the user to install them. +- GNU: No checks are done in `rustup` and expect that the user takes care of properly installing it. + +[rustup]: https://rustup.rs/ +[running Windows as your host operating system, you must also install one of the available ABIs]: https://rust-lang.github.io/rustup/installation/windows.html + +## ldproxy + +`ldproxy` crate is required when building applications using the Rust standard library, `std`. To install: +```sh +cargo install ldproxy +``` + +This tool is required regardless of the target architecture. + +[`ldproxy` crate]: https://github.com/esp-rs/embuild/tree/master/ldproxy + +## RISC-V + +If you only want to target `RISC-V` chips, installation is simpler. In order to build +applications for `RISC-V` targets we need to use a [Rust nightly toolchain] with the `rust-src` [component], both things can be installed with: + +```bash +rustup toolchain install nightly --component rust-src +``` + +For bare-metal, target can be installed by running: + +```bash +rustup target add riscv32imc-unknown-none-elf +``` + +For `std` applications, the `riscv32imc-esp-espidf` target does not have prebuilt objects distributed through rustup, therefore the `-Z build-std` [unstable cargo feature] is required within your project. This [unstable cargo feature] can also be added to `.cargo/config.toml` of your project. Our [template projects], which we will later discuss, already take care of this. + +Also, when building `std` applications, make sure you have [`LLVM`] and [`ldproxy`] installed. + +At this point, you are ready to build applications for all the Espressif chips based on RISC-V architecture. + +The installation of Rust for ESP `RISC-V` targets can also be handled by `espup`, a tool that will be introduced +in the [`espup` section]. + +[Rust nightly toolchain]: https://rust-lang.github.io/rustup/concepts/channels.html#working-with-nightly-rust +[component]: https://rust-lang.github.io/rustup/concepts/components.html +[template projects]: ../writing-your-own-application/generate-project-from-template.md +[unstable cargo feature]: https://doc.rust-lang.org/cargo/reference/unstable.html +[`LLVM`]: https://llvm.org/ +[`ldproxy`]: #ldproxy +[`espup` section]: #espup + + +## Xtensa + +Because there is no `Xtensa` support in the mainline Rust compiler you must use the [esp-rs/rust] fork instead. There are a few options available for installing this compiler fork. + +- The recommended one is using `espup`. See [`espup` section] for more details. +- 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 the 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, for this reason, is not recommended unless there is a major reason to go for this approach. See instructions in the [Installing from Source section of the esp-rs/rust repository]. + +[esp-rs/rust]: https://github.com/esp-rs/rust +[esp-rs/rust-build]: https://github.com/esp-rs/rust-build +[Installing from Source section of the esp-rs/rust repository]: https://github.com/esp-rs/rust#installing-from-source + +## espup + +[esp-rs/espup] is a tool for installing and maintaining the required ecosystem to develop applications in Rust for Espressif SoC's (both `Xtensa` and `RISC-V` targets). + +`espup` takes care of installing the proper Rust compiler (our fork in case of Xtensa targets, and the `nightly` toolchain with the necessary target for RISC-V targets), the necessary GCC toolchains for ESP chips, LLVM toolchain, and many other things. For more details, [see Usage section of the `espup` Readme]. + +In order to install `espup`: +```sh +cargo install espup --git https://github.com/esp-rs/espup +``` + +It's also possible to directly download the pre-compiled [release binaries] or to use [cargo-binstall]. + +Once that `espup` is installed you can simply run: +```sh +espup install +``` + +And it will install all the necessary tools to develop Rust applications for all supported ESP targets. + +`espup` will create and export file, by default called `export-esp.sh` on Unix systems +and `export-esp.ps1` on Windows, this file contains the required environment variables. Please, make sure to source in every terminal before building any application. + +```sh +# Unix +. ./export-esp.sh +# Windows +.\export-esp.ps1 +``` + +[esp-rs/espup]: https://github.com/esp-rs/espup +[see Usage section of the `espup` Readme]: https://github.com/esp-rs/espup#usage +[release binaries]: https://github.com/esp-rs/espup/releases +[cargo-binstall]: https://github.com/cargo-bins/cargo-binstall + +## Using Containers + +As an alternative to installing the compiler fork to your local system directly, it's also possible to run it inside of a container. + +A number of container runtimes are available, and which should be used depends on your operating system. Some of the popular options are: + +- [Docker] (non-commercial use only without a license) +- [Podman] +- [Lima] + +Espressif provides the [idf-rust] container image which contains several tags (generated both for `linux/arm64` and `linux/amd64`) for every Rust release: +- For `std` applications, the following naming convention is applied: `__` . E.g., [`esp32s3_v4.4_1.64.0.0`] contains the ecosystem for developing `std` applications based on [ESP-IDF release/v4.4] for `ESP32-S3` with the `1.64.0.0` Rust toolchain. +- For `no_std` applications, the naming convention is: `_`. E.g., [`esp32_1.64.0.0`] contains the ecosystem for developing `non_std` applications for `ESP32` with the `1.64.0.0` Rust toolchain. + +There is an `all` `` for both `std` and `no_std` tags that contains the environment required for all the ESP targets. + +[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 +[`esp32s3_v4.4_1.64.0.0`]: https://hub.docker.com/layers/espressif/idf-rust/esp32s3_v4.4_1.64.0.0/images/sha256-6fa1e98d770e3edc67cbd565893aa04e5573024b1e3e373fae50907435e841e4?context=explore +[ESP-IDF release/v4.4]: https://github.com/espressif/esp-idf/tree/release/v4.4 +[`esp32_1.64.0.0`]: https://hub.docker.com/layers/espressif/idf-rust/esp32_1.64.0.0/images/sha256-cc026ff9278a876f171d48978988e131940c07659485937a37cf750c44b28dfd?context=explore diff --git a/src/installation/rust-on-esp.md b/src/installation/rust-on-esp.md new file mode 100644 index 00000000..56216613 --- /dev/null +++ b/src/installation/rust-on-esp.md @@ -0,0 +1,38 @@ +# Rust on Espressif SoCs + +Let's discuss more in detail the Rust support for the architectures of the Espressif chips. At this moment, Espressif SoCs are based on two different architectures: RISC-V and Xtensa. The support for those two architectures in the Rust programming language is very different. + +## Rust in RISC-V + +The `RISC-V` architecture has support in the mainline Rust compiler so setup is relatively simple, all we must do is add the appropriate compilation target. + + +There are two suitable targets for this chip: + +- For bare-metal (`no_std`) applications, use `riscv32imc-unknown-none-elf` +- For applications that require `std`, use `riscv32imc-esp-espidf` + +The standard library target (`riscv32imc-esp-espidf`) is currently [Tier 3] and does not have prebuilt objects distributed through `rustup`. + + +## Rust in Xtensa +To this day, there is no `Xtensa` support in the mainline Rust compiler, for this reason, we maintain the [esp-rs/rust] fork that adds support four our `Xtensa` targets. + +`Xtensa` not being supported on Rust mainline is mainly a consequence of `LLVM` not supporting `Xtensa` targets. For that reason, we also maintain an LLVM fork with support for Espressif `Xtensa` targets in [espressif/llvm-project] + +> #### A note in upstreaming our forks. +> +> We are trying to upstream the changes in both our `LLVM` and Rust fork. +> The first step is to upstream the `LLVM` project, this is already in progress +> and you can see the status at this [tracking issue]. +> If `LLVM` changes are accepted in `LLVM` mainline, we will proceed with trying +> to upstream the Rust compiler changes. + +The forked compiler can coexist with the standard Rust compiler, so it is possible to have both installed on your system. The forked compiler is invoked when using the `esp` [channel] instead of the defaults, `stable` or `nightly`. + +[Tier 3]: https://doc.rust-lang.org/nightly/rustc/platform-support.html#tier-3 +[esp-rs/rust]: https://github.com/esp-rs/rust +[espressif/llvm-project]: https://github.com/espressif/llvm-project +[tracking issue]: https://github.com/espressif/llvm-project/issues/4 +[channel]: https://rust-lang.github.io/rustup/concepts/channels.html + diff --git a/src/introduction.md b/src/introduction.md index e212a3c8..ebe49325 100644 --- a/src/introduction.md +++ b/src/introduction.md @@ -7,7 +7,7 @@ Rust support for these devices is still in the early stages, but progress is bei For tools and libraries relating to Rust on ESP, please see the [esp-rs organization] on GitHub. [rust programming language]: https://www.rust-lang.org/ -[espressif]: https://espressif.com/ +[Espressif]: https://espressif.com/ [esp-rs organization]: https://github.com/esp-rs/ ## Status of This Book diff --git a/src/misc/glossary.md b/src/misc/glossary.md index 6c9ba0e1..f3cabca6 100644 --- a/src/misc/glossary.md +++ b/src/misc/glossary.md @@ -10,7 +10,7 @@ The [CMSIS-SVD] specification formalizes the description of the system contained SVD files are XML and contain definitions for peripherals which can be consumed by tools such a [svd2rust] to generate Peripheral Access Crates. -[cmsis-svd]: https://arm-software.github.io/CMSIS_5/SVD/html/index.html +[CMSIS-SVD]: https://arm-software.github.io/CMSIS_5/SVD/html/index.html [svd2rust]: https://github.com/rust-embedded/svd2rust/ ## PAC diff --git a/src/overview/bare-metal.md b/src/overview/bare-metal.md index f7bdcad9..9a85783b 100644 --- a/src/overview/bare-metal.md +++ b/src/overview/bare-metal.md @@ -26,14 +26,14 @@ Refer to the table below to see if your chip is supported. Please note that the | Chip | PAC | HAL | | :------: | :-------: | :-------: | -| ESP32 | ✅ | ✅ | -| ESP32-C2 | ✅ | ✅ | -| ESP32-C3 | ✅ | ✅ | +| ESP32 | ✅ | ✅ | +| ESP32-C2 | ✅ | ✅ | +| ESP32-C3 | ✅ | ✅ | | ESP32-C6 | _planned_ | _planned_ | -| ESP32-S2 | ✅ | ✅ | -| ESP32-S3 | ✅ | ✅ | +| ESP32-S2 | ✅ | ✅ | +| ESP32-S3 | ✅ | ✅ | | ESP32-H2 | _planned_ | _planned_ | -| ESP8266 | ✅ | ✅ | +| ESP8266 | ✅ | ✅ | ## Relevant `esp-rs` Crates diff --git a/src/overview/comparing-std-and-no_std.md b/src/overview/comparing-std-and-no_std.md index 906d8211..37552805 100644 --- a/src/overview/comparing-std-and-no_std.md +++ b/src/overview/comparing-std-and-no_std.md @@ -1,13 +1,13 @@ # Comparing `std` and `no_std` -There are a number of factors which must be considered when choosing between `std` ([esp-idf-hal]) and `no_std` (eg. [esp-hal]). As stated previously, each approach has its own unique set of advantages and disadvantages. While we can't decide for you, this section will hopefully allow you to make an educated decision. +There are several factors that must be considered when choosing between `std` ([esp-idf-hal]) and `no_std` (eg. [esp-hal]). As stated previously, each approach has its own unique set of advantages and disadvantages. While we can't decide for you, this section will hopefully allow you to make an educated decision. [esp-idf-hal]: https://github.com/esp-rs/esp-idf-hal [esp-hal]: https://github.com/esp-rs/esp-hal ## Application Runtimes -In the case of applications (as opposed to libraries) the standard library provides a runtime which handles setting up stack overflow protection, spawning the main thread before an application's `main` function is invoked, and handling of command-line arguments. +In the case of applications (as opposed to libraries) the standard library provides a runtime that handles setting up stack overflow protection, spawning the main thread before an application's `main` function is invoked, and handling of command-line arguments. Applications targeting `no_std` will be responsible for initializing their own runtimes instead. Runtime initialization is generally handled by an external dependency, in our case the [riscv-rt] and [xtensa-lx-rt] libraries. You can refer to their READMEs and documentation for more information. @@ -18,9 +18,9 @@ One advantage of not including the default runtime is that you're able to write ## `#![no_main]` -Another interesting property of `no_std` applications is that we cannot use Rust's default `main` function as our entry point. It makes certain assumptions which are not neccessarily valid in an embedded context (for example, it expects that command-line arguments exist). +Another interesting property of `no_std` applications is that we cannot use Rust's default `main` function as our entry point. It makes certain assumptions that are not necessarily valid in an embedded context (for example, it expects that command-line arguments exist). -Because of this, you will often see the `#![no_main]` attribute used to instruct the Rust compiler not to use the default entry point. Runtime crates will provide an `#[entry]` attribute which can be used to mark a diverging function as the application's entry point instead. For example a minimal application might look something like this: +Because of this, you will often see the `#![no_main]` attribute used to instruct the Rust compiler not to use the default entry point. Runtime crates will provide an `#[entry]` attribute which can be used to mark a diverging function as the application's entry point instead. For example, a minimal application might look something like this: ```rust,ignore #![no_std] @@ -38,7 +38,7 @@ fn main() -> ! { In addition to specifying the application's entry point, for `no_std` we must also define a panic handler. The default panic behaviour relies on `std`, as it prints to standard output. -You are able to define a panic handler manually using the `#[panic_handler]` attribute. Note that this function's signature _must_ match the example below. +You can define a panic handler manually using the `#[panic_handler]` attribute. Note that this function's signature _must_ match the example below. ```rust,ignore #![no_std] diff --git a/src/overview/using-the-standard-library.md b/src/overview/using-the-standard-library.md index e2d63bd6..b498ff58 100644 --- a/src/overview/using-the-standard-library.md +++ b/src/overview/using-the-standard-library.md @@ -6,7 +6,7 @@ Espressif provides a C-based development framework called [esp-idf] which has su ## Chip Support -In order for applications targeting `std` to be built for ESP devices, two things are required: +For applications targeting `std` to be built for ESP devices, two things are required: 1. LLVM/Clang support 2. Support for the device in `esp-idf` @@ -15,13 +15,13 @@ Refer to the table below to see if your chip is supported. | Chip | Supported? | | :------: | :--------: | -| ESP32 | ✅ | +| ESP32 | ✅ | | ESP32-C2 | _planned_ | -| ESP32-C3 | ✅ | -| ESP32-S2 | ✅ | -| ESP32-S3 | ✅ | +| ESP32-C3 | ✅ | +| ESP32-S2 | ✅ | +| ESP32-S3 | ✅ | | ESP32-H2 | _planned_ | -| ESP8266 | ❌ | +| ESP8266 | ❌ | Since `esp-idf` does not have support for the ESP8266, we unfortunately are unable to use these libraries with it. See the [Bare Metal] page for information on the `no_std` HAL for this chip. @@ -37,7 +37,7 @@ The supported `std` features are as follows: - Random number generation - Sockets -In addition to the `std` features there is an [embedded-svc] implementation for `esp-idf`, [esp-idf-svc], which adds extra support for services/modules not available in the standard library, including: +In addition to the `std` features, there is an [embedded-svc] implementation for `esp-idf`, [esp-idf-svc], which adds extra support for services/modules not available in the standard library, including: - Wi-Fi management - NVS (non-volatile storage) @@ -76,11 +76,11 @@ graph TD; ### I updated my `sdkconfig.defaults` file but it doesn't appear to have had any effect -You must clean your project and rebuild in order for changes in the `sdkconfig.defaults` to take effect: +You must clean your project and rebuild for changes in the `sdkconfig.defaults` to take effect: ```shell,ignore -$ cargo clean -$ cargo build +cargo clean +cargo build ``` ### The documentation for the crates mentioned on this page is out of date or missing diff --git a/src/resources.md b/src/resources.md new file mode 100644 index 00000000..4b2f5f22 --- /dev/null +++ b/src/resources.md @@ -0,0 +1,18 @@ +# Resources + +- [esp-rs Matrix Channel](https://matrix.to/#/#esp-rs:matrix.org): The perfect place to ask questions and discuss any topic related with Rust on Espressif chips. +- [Embedded Rust on Espressif](https://espressif-trainings.ferrous-systems.com/) - Training for Rust development on ESP32-C3 by [Ferrous Systems](https://ferrous-systems.com/training/). +- [Awesome ESP Rust](https://github.com/esp-rs/awesome-esp-rust) - A curated list of resouces for development in the Rust programming language for Espressif chips. +- [esp-rs](https://github.com/esp-rs): Github organization with libraries, crates and examples for using Rust on Espressif SoC's. + +## Crates referenced in this book +- [cargo-binstall](https://github.com/cargo-bins/cargo-binstall) - Binary installation for rust projects +- [cargo-generate](https://github.com/cargo-generate/cargo-generate) - Tool to help you get up and running quickly with a new Rust project by leveraging a pre-existing git repository as a template. +- [esp-hal](https://github.com/esp-rs/esp-hal) - `no_std` HAL for Espressif microcontrollers. +- [esp-idf-hal](https://github.com/esp-rs/esp-idf-hal) - `std` HAL for Espressif microcontrollers. +- [esp-idf-template](https://github.com/esp-rs/esp-template) - A minimal `esp-idf-hal` application template to use with `cargo-generate`. +- [esp-template](https://github.com/esp-rs/esp-template) - A minimal `esp-hal` application template to use with `cargo-generate`. +- [espflash](https://github.com/esp-rs/espflash) - Serial flasher utility for Espressif SoCs and modules based on [esptool](https://github.com/espressif/esptool). +- [espup](https://github.com/esp-rs/espup): About Tool for installing and maintaining the required toolchains for developing applications in Rust for Espressif SoC's. +- [ldproxy](https://github.com/esp-rs/embuild/tree/master/ldproxy) - Tool to forward linker arguments to the actual linker executable. +- [wokwi-server](https://github.com/MabezDev/wokwi-server) - WebSocket server for running simulations in [Wokwi](https://wokwi.com/) from Visual Studio Code Remote Containers using a web browser. diff --git a/src/tooling/debugging/index.md b/src/tooling/debugging/index.md new file mode 100644 index 00000000..60b01dc3 --- /dev/null +++ b/src/tooling/debugging/index.md @@ -0,0 +1,3 @@ +# Debugging + +Debugging Rust applications is also possible using different tools that will be covered in this chapter. diff --git a/src/tooling/debugging/openocd.md b/src/tooling/debugging/openocd.md index bb7d7977..8db8e557 100644 --- a/src/tooling/debugging/openocd.md +++ b/src/tooling/debugging/openocd.md @@ -15,8 +15,8 @@ Once installed, it's as simple as running `openocd` with the correct scripts. Fo 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: +For other configurations it may require specifying the chip and the interface separately, for example, ESP32 with a J-Link: ```ignore openocd -f interface/jlink.cfg -f target/esp32.cfg -``` \ No newline at end of file +``` diff --git a/src/tooling/debugging/probe-rs.md b/src/tooling/debugging/probe-rs.md index b500226b..07f8ce80 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 & RISCV architectures along with a collection of tools, including but not limited to: +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 & RISCV architectures along with a collection of tools, including but not limited to: - Debugger - GDB support. @@ -10,9 +10,9 @@ The probe-rs project is a set of tools to interact with embedded MCU's using var - Similar to app_trace component of IDF. - Flashing algorithms -More info about probe-rs & how to set up a project, can be found on the [probe.rs](https://probe.rs/) website. +More info about probe-rs & how to set up a project can be found on the [probe.rs](https://probe.rs/) website. -## `USB-JTAG-SERIAL` peripheral for ESP32-C3 +## `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 builtin `USB-JTAG-SERIAL` peripheral, no need for any external hardware debugger. More info on configuring the interface can be found in the [official documentation]. @@ -20,17 +20,17 @@ Starting from `probe-rs` v0.12, it is possible to flash and debug the ESP32-C3 w `probe-rs` currently only supports ARM & RISCV, therefore this limits the number of Espressif chips that can be used at the moment. -| Chip | Flashing | Debugging | -| :------: | :----------: | :-----------: | -| ESP32-C3 | ✅ | ⚠️ | +| Chip | Flashing | Debugging | +| :------: | :------: | :-------: | +| ESP32-C3 | ✅ | ⚠️ | -**Note**: _items marked with ⚠️ are currently work in progress, usable but expect bugs._ +**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 ## 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. +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 # Espressif dev kit FTDI @@ -43,4 +43,4 @@ ATTRS{idVendor}=="303a", ATTRS{idProduct}=="1001", MODE="660", GROUP="plugdev", ATTRS{idVendor}=="303a", ATTRS{idProduct}=="1002", MODE="660", GROUP="plugdev", TAG+="uaccess" ``` - \ No newline at end of file + diff --git a/src/tooling/debugging/vscode-debugging.md b/src/tooling/debugging/vscode-debugging.md index 42898497..f504a178 100644 --- a/src/tooling/debugging/vscode-debugging.md +++ b/src/tooling/debugging/vscode-debugging.md @@ -7,16 +7,16 @@ There is also a possibility to debug with graphical output directly in Visual St ## Hardware Setup -ESP32 doesn't have a built-in JTAG interface so you have to connect an external JTAG adapter with 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. +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. -| ESP32 Pin | JTAG Signal | -| :-----------: | :-------------: | -| MTDO/GPIO15 | TDO | -| MTDI/GPIO12 | TDI | -| MTCK/GPIO13 | TCK | -| MTMS/GPIO14 | TMS | -| 3V3 | VJTAG | -| GND | GND | +| ESP32 Pin | JTAG Signal | +| :---------: | :---------: | +| MTDO/GPIO15 | TDO | +| MTDI/GPIO12 | TDI | +| MTCK/GPIO13 | TCK | +| MTMS/GPIO14 | TMS | +| 3V3 | VJTAG | +| GND | GND | **Note**: On Windows `USB Serial Converter A 0403 6010 00` driver should be WinUSB. @@ -25,7 +25,7 @@ ESP32 doesn't have a built-in JTAG interface so you have to connect an external 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. +3. Update **executable**, **svdFile**, **serverpath** paths, and **toolchainPrefix** field. ```jsonc { // Use IntelliSense to learn about possible attributes. @@ -76,16 +76,16 @@ ESP32-C3 with **revision 3** **does** have a built-in JTAG interface and you don 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** step. -ESP32-C3 **revision 1** and **revision 2** don't have a built-in JTAG interface so you have to connect an external JTAG adapter with 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. +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. -| ESP32-C3 Pin | JTAG Signal | -| :--------------: | :-------------: | -| MTDO/GPIO7 | TDO | -| MTDI/GPIO5 | TDI | -| MTCK/GPIO6 | TCK | -| MTMS/GPIO4 | TMS | -| 3V3 | VJTAG | -| GND | GND | +| ESP32-C3 Pin | JTAG Signal | +| :----------: | :---------: | +| MTDO/GPIO7 | TDO | +| MTDI/GPIO5 | TDI | +| MTCK/GPIO6 | TCK | +| MTMS/GPIO4 | TMS | +| 3V3 | VJTAG | +| GND | GND | **Note**: On Windows `USB Serial Converter A 0403 6010 00` driver should be WinUSB. @@ -94,7 +94,7 @@ ESP32-C3 **revision 1** and **revision 2** don't have a built-in JTAG interface 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. +3. Update **executable**, **svdFile**, **serverpath** paths, and **toolchainPrefix** field. ```jsonc { // Use IntelliSense to learn about possible attributes. diff --git a/src/tooling/espflash.md b/src/tooling/espflash.md index 5c05842d..f92e95ed 100644 --- a/src/tooling/espflash.md +++ b/src/tooling/espflash.md @@ -13,13 +13,13 @@ Provides a subcommand for `cargo` which handles cross-compilation and flashing. To install: ```bash -$ cargo install cargo-espflash +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' in `release` mode, flash the resulting binary to a device, and then subsequently start a serial monitor: ```bash -$ cargo espflash --example=blinky --release --monitor +cargo espflash --example=blinky --release --monitor ``` For more information please see to the [cargo-espflash README]. @@ -34,13 +34,13 @@ Provides a standalone command-line application which flashes an ELF file to a de To install: ```bash -$ cargo install espflash +cargo install espflash ``` Assuming you have built an ELF binary by other means already, `espflash` can be used to download it to your device. For example, if you have built the `getting-started/blinky` example from [esp-idf] using `idf.py` you might run something like: ```bash -$ espflash build/blinky +espflash build/blinky ``` For more information please see to the [espflash README]. diff --git a/src/tooling/espmonitor.md b/src/tooling/espmonitor.md index a3c81416..c3e3e4a2 100644 --- a/src/tooling/espmonitor.md +++ b/src/tooling/espmonitor.md @@ -5,13 +5,13 @@ The [esp-rs/espmonitor] repository contains two crates, `cargo-espmonitor` and ` ## cargo-espmonitor ```bash -$ cargo install cargo-espmonitor +cargo install cargo-espmonitor ``` ## espmonitor ```bash -$ cargo install espmonitor +cargo install espmonitor ``` [esp-rs/espmonitor]: https://github.com/esp-rs/espmonitor diff --git a/src/tooling/index.md b/src/tooling/index.md new file mode 100644 index 00000000..c7fcc80d --- /dev/null +++ b/src/tooling/index.md @@ -0,0 +1,4 @@ +# Tooling + +Now that we have our required dependencies installed, we will cover some of the +tools that will make our life developing Rust applications for ESP targets a lot easier. diff --git a/src/tooling/simulating/index.md b/src/tooling/simulating/index.md new file mode 100644 index 00000000..32d65bea --- /dev/null +++ b/src/tooling/simulating/index.md @@ -0,0 +1,7 @@ +# Simulating + +Simulating projects can be very handy. It allows users to test projects using CI, try projects without having hardware available, and many other scenarios. + +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. diff --git a/src/tooling/simulating/qemu.md b/src/tooling/simulating/qemu.md new file mode 100644 index 00000000..9d7350b5 --- /dev/null +++ b/src/tooling/simulating/qemu.md @@ -0,0 +1,8 @@ +# 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/QEMU]: https://github.com/espressif/qemu +[QEMU wiki]: https://github.com/espressif/qemu/wiki diff --git a/src/tooling/simulating/wokwi.md b/src/tooling/simulating/wokwi.md new file mode 100644 index 00000000..88f87721 --- /dev/null +++ b/src/tooling/simulating/wokwi.md @@ -0,0 +1,19 @@ +# 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 offers WiFi 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]. +## Using 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]: 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 diff --git a/src/tooling/text-editors-and-ides.md b/src/tooling/text-editors-and-ides.md index 07a56f46..810f95f1 100644 --- a/src/tooling/text-editors-and-ides.md +++ b/src/tooling/text-editors-and-ides.md @@ -4,19 +4,27 @@ While an often contentious subject, using the right development environment can ## Visual Studio Code -One of the more common development environents is Microsoft's [Visual Studio Code] text editor along with the [Rust Analyzer] extension. +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 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 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 Studo Code via the built-in extension manager. [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 which 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: +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 { @@ -37,16 +45,15 @@ targets = ["xtensa-esp32-none-elf"] [CLion] is a cross-platform IDE for C and C++ from [JetBrains]. -[clion]: https://www.jetbrains.com/clion/ -[clion rust plugin]: https://www.jetbrains.com/help/clion/rust-support.html -[jetbrains]: https://www.jetbrains.com/ +[CLion]: https://www.jetbrains.com/clion/ +[JetBrains]: https://www.jetbrains.com/ ## IntelliJ -[intellij]: https://www.jetbrains.com/idea/ -[intellij rust plugin]: https://intellij-rust.github.io/ ## vim +[vim] is a highly configurable text editor based on vi that also [supports Rust Analyzer]. + [vim]: https://www.vim.org/ -[rust.vim]: https://github.com/rust-lang/rust.vim/ +[supports Rust Analyzer]: https://rust-analyzer.github.io/manual.html#vimneovim diff --git a/src/writing-your-application/generate-project-from-template.md b/src/writing-your-application/generate-project-from-template.md deleted file mode 100644 index 01b48ee7..00000000 --- a/src/writing-your-application/generate-project-from-template.md +++ /dev/null @@ -1,85 +0,0 @@ -# Creating Applications - -With the appropriate Rust compiler and toolchain installed, you're now ready to create an application. As outlined below, there are essentially two ways to do this: generating from a template or starting from scratch using only `cargo`. - -## Using `cargo-generate` - -The [cargo-generate] subcommand 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. - -`cargo generate` can be installed by running: - -```shell -$ cargo install cargo-generate -``` - -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. - -The generated application can be built as normal using the appropriate toolchain and target simply by running `cargo build` when using either template. - -### esp-idf-template - -When using the Rust standard library (`std`) you can use the [esp-idf-template] template, which will look something like: - -```shell -$ cargo generate --git https://github.com/esp-rs/esp-idf-template cargo -🤷 Project Name : esp-rust-app -🔧 Generating template ... -✔ 🤷 Rust toolchain (beware: nightly works only for esp32c3!) · esp -✔ 🤷 STD support · true -✔ 🤷 ESP-IDF native build version (stable = 4.3.1, upcoming = 4.4, master = 5.0; applicable only with `cargo build --features native`) · stable -✔ 🤷 MCU · esp32 -[1/9] Done: .cargo/config.toml -[2/9] Done: .cargo -[3/9] Done: .gitignore -[4/9] Done: Cargo.toml -[5/9] Done: build.rs -[6/9] Done: rust-toolchain.toml -[7/9] Done: sdkconfig.defaults -[8/9] Done: src/main.rs -[9/9] Done: src -🔧 Moving generated files into: `/Users/alice/esp-rust-app`... -✨ Done! New project created /Users/alice/esp-rust-app -``` - -### esp-template - -For bare-metal applications (`no_std`) you can instead use the [esp-template] template: - -```shell -$ cargo generate --git https://github.com/esp-rs/esp-template -🤷 Project Name : esp-rust-app -🔧 Generating template ... -✔ 🤷 Which MCU to target? · esp32c3 -✔ 🤷 Configure project to use Dev Containers (VS Code, GitHub Codespaces and Gitpod)? · true -[ 1/25] Done: .cargo/config.toml -[ 2/25] Done: .cargo -[ 3/25] Done: .devcontainer/Dockerfile -[ 4/25] Done: .devcontainer/devcontainer.json -[ 5/25] Done: .devcontainer -[ 6/25] Done: .dockerignore -[ 7/25] Done: .gitdpod.Dockerfile -[ 8/25] Done: .gitdpod.yml -[ 9/25] Done: .gitignore -[10/25] Done: .vscode/launch.json -[11/25] Done: .vscode/settings.json -[12/25] Done: .vscode/tasks.json -[13/25] Done: .vscode -[14/25] Done: Cargo.toml -[15/25] Done: LICENSE-APACHE -[16/25] Done: LICENSE-MIT -[17/25] Done: docs/README.md -[18/25] Done: docs -[19/25] Done: rust-toolchain.toml -[20/25] Done: scripts/build.sh -[21/25] Done: scripts/flash.sh -[22/25] Done: scripts/run-wokwi.sh -[23/25] Done: scripts -[24/25] Done: src/main.rs -[25/25] Done: src -🔧 Moving generated files into: `/Users/alice/esp-rust-app`... -✨ Done! New project created /Users/alice/esp-rust-app -``` - -[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 diff --git a/src/writing-your-own-application/generate-project-from-template.md b/src/writing-your-own-application/generate-project-from-template.md new file mode 100644 index 00000000..54e72c5f --- /dev/null +++ b/src/writing-your-own-application/generate-project-from-template.md @@ -0,0 +1,98 @@ +# Generating Projects From Templates + +We currently maintin two template repositories: +- [esp-template] - `no_std` 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. + +`cargo generate` can be installed by running: + +```shell +cargo install cargo-generate +``` + +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. + +The generated application can be built as normal using the appropriate toolchain and target simply by running `cargo build` when using either templates. + +Using `cargo run` will compile the project, flash it, and open a serial monitor with our chip. + +## esp-idf-template + +When using the Rust standard library (`std`) you can use the [esp-idf-template] template, which will look something like: + +```shell +$ cargo generate --git https://github.com/esp-rs/esp-idf-template cargo +🤷 Project Name : esp-rust-app +🔧 Destination: /home/alice/esp-rust-app ... +🔧 Generating template ... +✔ 🤷 MCU · esp32 +✔ 🤷 Configure project to use Dev Containers (VS Code, GitHub Codespaces and Gitpod)? (beware: Dev Containers not available for esp-idf v4.3.2) · false +✔ 🤷 STD support · true +✔ 🤷 ESP-IDF native build version (v4.3.2 = previous stable, v4.4 = stable, mainline = UNSTABLE) · v4.4 +[ 1/10] Done: .cargo/config.toml +[ 2/10] Done: .cargo +[ 3/10] Done: .gitignore +[ 4/10] Done: .vscode +[ 5/10] Done: Cargo.toml +[ 6/10] Done: build.rs +[ 7/10] Done: rust-toolchain.toml +[ 8/10] Done: sdkconfig.defaults +[ 9/10] Done: src/main.rs +[10/10] Done: src +🔧 Moving generated files into: `/home/alice/esp-rust-app`... +💡 Initializing a fresh Git repository +✨ Done! New project created /home/alice/esp-rust-app +``` + +## esp-template + +For bare-metal applications (`no_std`) you can instead use the [esp-template] template: + +```shell +cargo generate --git https://github.com/esp-rs/esp-template +🤷 Project Name : esp-rust-app +🔧 Destination: /home/alice/esp-rust-app ... +🔧 Generating template ... +✔ 🤷 Which MCU to target? · esp32c3 +✔ 🤷 Configure project to use Dev Containers (VS Code, GitHub Codespaces and Gitpod)? · true +✔ 🤷 Enable allocations via the esp-alloc crate? · false +[ 1/11] Done: .cargo/config.toml +[ 2/11] Done: .cargo +[ 3/11] Done: .gitignore +[ 4/11] Done: .vscode/settings.json +[ 5/11] Done: .vscode +[ 6/11] Done: Cargo.toml +[ 7/11] Done: LICENSE-APACHE +[ 8/11] Done: LICENSE-MIT +[ 9/11] Done: rust-toolchain.toml +[10/11] Done: src/main.rs +[11/11] Done: src +🔧 Moving generated files into: `/home/alice/esp-rust-app`... +✨ Done! New project created /home/alice/esp-rust-app +``` + +### Using Dev Containers in the templates + +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] +- [Gitpod] + +Dev Containers use the `idf-rust` container image that was explained in the [Using Container section of the Installing Rust 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]. + +For more details about on Dev Containers, see [Dev Container section of the template Readme]. + + +[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 +[Gitpod]: https://www.gitpod.io +[Using Container section of the Installing Rust chapter]: ../installation/installing-rust-for-esp.md#using-containers +[Wokwi simulator]: https://wokwi.com/ +[web flash]: https://github.com/bjoernQ/esp-web-flash-server +[Dev Container section of the template Readme]: https://github.com/esp-rs/esp-template/tree/main/docs#dev-containers + diff --git a/src/writing-your-own-application/index.md b/src/writing-your-own-application/index.md new file mode 100644 index 00000000..d773ad06 --- /dev/null +++ b/src/writing-your-own-application/index.md @@ -0,0 +1,12 @@ +# Writing Your Own Application + +With the appropriate Rust compiler and toolchain installed, you're now ready to create an application. + +There are essentially two ways to do this: generating from a template or starting from scratch using only `cargo`. + +We strongly recomend starting projects from templates as it gives you a configured project saving all the time that would require +to setup a project started from scratch with `cargo`. + +> If you are looking for inspiration, check the [Projects section of our Awesome ESP Rust repository] + +[Projects section of our Awesome ESP Rust repository]: https://github.com/esp-rs/awesome-esp-rust#projects diff --git a/src/writing-your-application/writing-std-applications.md b/src/writing-your-own-application/writing-std-applications.md similarity index 100% rename from src/writing-your-application/writing-std-applications.md rename to src/writing-your-own-application/writing-std-applications.md