From bb7b521f3f9bbd5aaab4f19a3b5ba8abbe473522 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Wed, 4 Mar 2026 15:01:13 +0100 Subject: [PATCH 1/6] WIP - talk more about `esp-radio` and `esp-generate` Should be probably shortened, just a WIP prototype for now --- src/getting-started/tooling/esp-generate.md | 12 ++++++++++++ src/introduction/ancillary-crates.md | 4 ++-- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/src/getting-started/tooling/esp-generate.md b/src/getting-started/tooling/esp-generate.md index 582c6ca..fa09d12 100644 --- a/src/getting-started/tooling/esp-generate.md +++ b/src/getting-started/tooling/esp-generate.md @@ -12,6 +12,18 @@ cargo install esp-generate --locked You can also directly download pre-compiled [release binaries][release-binaries] or use [`cargo-binstall`][cargo-binstall]. +## What `esp-generate` configures + +`esp-generate` provides more than dependency selection: it applies a known set of crates and feature combinations corresponding to the chosen template options, reducing the amount of manual configuration required to produce a working project. + +Enabling various options may add additional crates to `Cargo.toml` of the generated project. Certain capabilities require supporting libraries in order to function correctly. The templates aim to keep the dependency set minimal while ensuring the generated project is functional and immediately runnable. + +All generated projects are based on `esp-hal`. Depending on the selected options, `esp-generate` adds the required support crates (for example `demft` logging, heap allocation, async executors etc.) and applies the appropriate feature flags so that the configuration is internally consistent. + +Wireless connectivity provided by `esp-radio`, as stated in [Ancillary Crates](../../introduction/ancillary-crates.md) chapter, relies on `esp-rtos`. For this reason, enabling Wi-Fi or BLE causes `esp-generate` to include this crate and configure it with the `esp-radio` feature, providing the scheduling and runtime integration required for reliable operation. When Embassy support is enabled, `esp-rtos` also serves as the integration point for async execution on supported chips, with a corresponding feature enabled in the template project. For IP networking, the templates include the surrounding networking components. This typically includes `smoltcp`, `embassy-net` for async networking, when Embassy is enabled. + +Some options have coupled configurations. Logging is configured either via `defmt` or `log` with a corresponding frontend, and panic handling and diagnostics are configured to match the selected logging method. `esp-generate` selects compatible versions and feature flags across the dependency graph. Certain crates are included as part of the standard baseline because they support common embedded workflows. For example, `esp-bootloader-esp-idf` includes additional support of 2nd stage bootloader, and `critical-section` is included because many embedded crates rely on it to implement interrupt-critical regions. + > [!TIP] > Each version of `esp-generate` targets a specific version of the ecosystem crates. Make sure to update `esp-generate` if you want to use the latest released versions. diff --git a/src/introduction/ancillary-crates.md b/src/introduction/ancillary-crates.md index ed106f5..7f82cf6 100644 --- a/src/introduction/ancillary-crates.md +++ b/src/introduction/ancillary-crates.md @@ -8,7 +8,7 @@ The first step in working with a project is to create it, the main way to do thi The core crate that ties all work with Espressif chips in Rust is the `esp-hal` crate. Through it, you will be able to perform basic initialization of the chip, as well as access drivers for the peripherals available on the chip. The full [`esp-hal` documentation] for selected chip will give unambiguous information about what peripherals are available to use, and the stability of their respective drivers. -Furthermore, you may want to use more advanced functionality of the chip. For example, network and connectivity. This part of the ecosystem is the responsibility of `esp-radio`, which combines drivers for the communication protocols available on one or another of Espressif's products: `Wi-Fi`, `BLE`, `esp-now` and low-level `IEEE 802.15.4` for the lower layers of communication. More detailed information for each chip is available in the [`esp-radio` sub-repository]. +Furthermore, you may want to use more advanced functionality of the chip. For example, network and connectivity. This part of the ecosystem is the responsibility of `esp-radio`, which combines drivers for the communication protocols available on one or another of Espressif's products: `Wi-Fi`, `BLE`, `esp-now` and low-level `IEEE 802.15.4` for the lower layers of communication. More detailed information for each chip is available in the [`esp-radio` sub-repository]. It is also worth mentioning that radio support requires the stack to run continuously in the background (timers, interrupts, state machines). `esp-radio` relies on `esp-rtos` for the scheduling/runtime glue needed to run reliably, and `esp-generate` will add `esp-rtos` automatically when you enable the appropriate template options. For more advanced work with chip memory and to use collections from the `alloc` crate in `no_std` that require heap allocation, you are welcome to use `esp-alloc`. A separate [chapter in the book](./../application-development/alloc.md) is devoted to this. @@ -32,7 +32,7 @@ The table below briefly describes all crates in the `esp-hal` ecosystem and thei | `esp-rtos` | Scheduler implementation for esp-radio, embassy support for `esp-hal`. | Unstable | | `esp-sync` | Synchronization primitives for Espressif devices. | Unstable | | `esp-storage` | Storage utilities for Espressif devices. | Unstable | -| `esp-radio` | Wi‑Fi, BLE, IEEE 802.15.4, and ESP‑NOW functionality for Espressif devices. | Unstable | +| `esp-radio` | Wi‑Fi, BLE, IEEE 802.15.4, and ESP‑NOW functionality for Espressif devices. | Stable | | `xtensa-lx` | Low-level access to Xtensa LX processors and peripherals. | Unstable | | `xtensa-lx-rt` | Minimal startup/runtime for Xtensa LX CPUs from Espressif. | Unstable | From 034b1ecba7520c4dff64bd92ed2564643be08e41 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Wed, 4 Mar 2026 16:25:45 +0100 Subject: [PATCH 2/6] cleanup more --- src/getting-started/tooling/esp-generate.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/getting-started/tooling/esp-generate.md b/src/getting-started/tooling/esp-generate.md index fa09d12..832275d 100644 --- a/src/getting-started/tooling/esp-generate.md +++ b/src/getting-started/tooling/esp-generate.md @@ -22,7 +22,7 @@ All generated projects are based on `esp-hal`. Depending on the selected options Wireless connectivity provided by `esp-radio`, as stated in [Ancillary Crates](../../introduction/ancillary-crates.md) chapter, relies on `esp-rtos`. For this reason, enabling Wi-Fi or BLE causes `esp-generate` to include this crate and configure it with the `esp-radio` feature, providing the scheduling and runtime integration required for reliable operation. When Embassy support is enabled, `esp-rtos` also serves as the integration point for async execution on supported chips, with a corresponding feature enabled in the template project. For IP networking, the templates include the surrounding networking components. This typically includes `smoltcp`, `embassy-net` for async networking, when Embassy is enabled. -Some options have coupled configurations. Logging is configured either via `defmt` or `log` with a corresponding frontend, and panic handling and diagnostics are configured to match the selected logging method. `esp-generate` selects compatible versions and feature flags across the dependency graph. Certain crates are included as part of the standard baseline because they support common embedded workflows. For example, `esp-bootloader-esp-idf` includes additional support of 2nd stage bootloader, and `critical-section` is included because many embedded crates rely on it to implement interrupt-critical regions. +Some options have coupled configurations. Logging is configured either via `defmt` or `log` with a corresponding frontend. Certain crates are also included as part of the standard baseline because they support common embedded workflows. For example, `esp-bootloader-esp-idf` includes additional support of 2nd stage bootloader, and `critical-section` is included because many embedded crates rely on it to implement interrupt-critical regions. > [!TIP] > Each version of `esp-generate` targets a specific version of the ecosystem crates. Make sure to update `esp-generate` if you want to use the latest released versions. From 27b437aef0bc3b71aa4d91660386a19e2646bca8 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Wed, 4 Mar 2026 16:39:45 +0100 Subject: [PATCH 3/6] Make the dawg happy --- src/getting-started/tooling/esp-generate.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/getting-started/tooling/esp-generate.md b/src/getting-started/tooling/esp-generate.md index 832275d..c761b22 100644 --- a/src/getting-started/tooling/esp-generate.md +++ b/src/getting-started/tooling/esp-generate.md @@ -12,11 +12,11 @@ cargo install esp-generate --locked You can also directly download pre-compiled [release binaries][release-binaries] or use [`cargo-binstall`][cargo-binstall]. -## What `esp-generate` configures +## What `esp-generate` Сonfigures `esp-generate` provides more than dependency selection: it applies a known set of crates and feature combinations corresponding to the chosen template options, reducing the amount of manual configuration required to produce a working project. -Enabling various options may add additional crates to `Cargo.toml` of the generated project. Certain capabilities require supporting libraries in order to function correctly. The templates aim to keep the dependency set minimal while ensuring the generated project is functional and immediately runnable. +Enabling various options may add additional crates to `Cargo.toml` of the generated project. Certain capabilities require supporting libraries to function correctly. The templates aim to keep the dependency set minimal while ensuring the generated project is functional and immediately runnable. All generated projects are based on `esp-hal`. Depending on the selected options, `esp-generate` adds the required support crates (for example `demft` logging, heap allocation, async executors etc.) and applies the appropriate feature flags so that the configuration is internally consistent. From aea1600aeb2e5db8c79da99e696bfc8be937bdde Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Wed, 4 Mar 2026 16:47:57 +0100 Subject: [PATCH 4/6] reviews + minimize a bit --- src/getting-started/tooling/esp-generate.md | 4 +--- src/introduction/ancillary-crates.md | 2 +- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/src/getting-started/tooling/esp-generate.md b/src/getting-started/tooling/esp-generate.md index c761b22..f57d725 100644 --- a/src/getting-started/tooling/esp-generate.md +++ b/src/getting-started/tooling/esp-generate.md @@ -16,9 +16,7 @@ You can also directly download pre-compiled [release binaries][release-binaries] `esp-generate` provides more than dependency selection: it applies a known set of crates and feature combinations corresponding to the chosen template options, reducing the amount of manual configuration required to produce a working project. -Enabling various options may add additional crates to `Cargo.toml` of the generated project. Certain capabilities require supporting libraries to function correctly. The templates aim to keep the dependency set minimal while ensuring the generated project is functional and immediately runnable. - -All generated projects are based on `esp-hal`. Depending on the selected options, `esp-generate` adds the required support crates (for example `demft` logging, heap allocation, async executors etc.) and applies the appropriate feature flags so that the configuration is internally consistent. +Enabling various options may add additional crates to `Cargo.toml` of the generated project. The templates aim to keep the dependency set minimal while ensuring the generated project is functional and immediately runnable. Wireless connectivity provided by `esp-radio`, as stated in [Ancillary Crates](../../introduction/ancillary-crates.md) chapter, relies on `esp-rtos`. For this reason, enabling Wi-Fi or BLE causes `esp-generate` to include this crate and configure it with the `esp-radio` feature, providing the scheduling and runtime integration required for reliable operation. When Embassy support is enabled, `esp-rtos` also serves as the integration point for async execution on supported chips, with a corresponding feature enabled in the template project. For IP networking, the templates include the surrounding networking components. This typically includes `smoltcp`, `embassy-net` for async networking, when Embassy is enabled. diff --git a/src/introduction/ancillary-crates.md b/src/introduction/ancillary-crates.md index 7f82cf6..a481e1a 100644 --- a/src/introduction/ancillary-crates.md +++ b/src/introduction/ancillary-crates.md @@ -32,7 +32,7 @@ The table below briefly describes all crates in the `esp-hal` ecosystem and thei | `esp-rtos` | Scheduler implementation for esp-radio, embassy support for `esp-hal`. | Unstable | | `esp-sync` | Synchronization primitives for Espressif devices. | Unstable | | `esp-storage` | Storage utilities for Espressif devices. | Unstable | -| `esp-radio` | Wi‑Fi, BLE, IEEE 802.15.4, and ESP‑NOW functionality for Espressif devices. | Stable | +| `esp-radio` | Wi‑Fi, BLE, IEEE 802.15.4, and ESP‑NOW functionality for Espressif devices. | Unstable | | `xtensa-lx` | Low-level access to Xtensa LX processors and peripherals. | Unstable | | `xtensa-lx-rt` | Minimal startup/runtime for Xtensa LX CPUs from Espressif. | Unstable | From 0e0731686479f059a9676cdba6f977023c267319 Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Wed, 1 Apr 2026 16:08:45 +0200 Subject: [PATCH 5/6] Be more "honest" about esp-rtos and rtos-driver (reviews) --- src/introduction/ancillary-crates.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/introduction/ancillary-crates.md b/src/introduction/ancillary-crates.md index a481e1a..f71a887 100644 --- a/src/introduction/ancillary-crates.md +++ b/src/introduction/ancillary-crates.md @@ -8,7 +8,7 @@ The first step in working with a project is to create it, the main way to do thi The core crate that ties all work with Espressif chips in Rust is the `esp-hal` crate. Through it, you will be able to perform basic initialization of the chip, as well as access drivers for the peripherals available on the chip. The full [`esp-hal` documentation] for selected chip will give unambiguous information about what peripherals are available to use, and the stability of their respective drivers. -Furthermore, you may want to use more advanced functionality of the chip. For example, network and connectivity. This part of the ecosystem is the responsibility of `esp-radio`, which combines drivers for the communication protocols available on one or another of Espressif's products: `Wi-Fi`, `BLE`, `esp-now` and low-level `IEEE 802.15.4` for the lower layers of communication. More detailed information for each chip is available in the [`esp-radio` sub-repository]. It is also worth mentioning that radio support requires the stack to run continuously in the background (timers, interrupts, state machines). `esp-radio` relies on `esp-rtos` for the scheduling/runtime glue needed to run reliably, and `esp-generate` will add `esp-rtos` automatically when you enable the appropriate template options. +Furthermore, you may want to use more advanced functionality of the chip. For example, network and connectivity. This part of the ecosystem is the responsibility of `esp-radio`, which combines drivers for the communication protocols available on one or another of Espressif's products: `Wi-Fi`, `BLE`, `esp-now` and low-level `IEEE 802.15.4` for the lower layers of communication. More detailed information for each chip is available in the [`esp-radio` sub-repository]. It is also worth mentioning that radio support requires the stack to run continuously in the background (timers, interrupts, state machines). `esp-radio` relies on an implementation of [`esp-radio-rtos-driver`], which defines the scheduling and runtime interface the stack needs to run reliably. `esp-rtos` is the default backend we ship and support; in principle user is free replace it with another implementation of the driver. `esp-generate` will add `esp-rtos` automatically when you enable the appropriate template options. For more advanced work with chip memory and to use collections from the `alloc` crate in `no_std` that require heap allocation, you are welcome to use `esp-alloc`. A separate [chapter in the book](./../application-development/alloc.md) is devoted to this. @@ -50,6 +50,7 @@ The most popular Hardware Abstraction Layer in the Embedded Rust environment is [`esp-hal` documentation]: https://docs.espressif.com/projects/rust/esp-hal/latest/ [`esp-radio` sub-repository]: https://github.com/esp-rs/esp-hal/tree/main/esp-radio +[`esp-radio-rtos-driver`]: https://github.com/esp-rs/esp-hal/tree/main/esp-radio-rtos-driver [`embedded-hal`]: https://docs.rs/embedded-hal/latest/embedded_hal/index.html [`rand_core`]: https://crates.io/crates/rand_core [`embedded-io`]: https://crates.io/crates/embedded-io From f5558e91fa6a4bef9e7bd14fc4bc68bdc47037be Mon Sep 17 00:00:00 2001 From: Kirill Mikhailov Date: Mon, 20 Apr 2026 14:34:19 +0200 Subject: [PATCH 6/6] "democratize" the esp-generate section a bit --- src/getting-started/tooling/esp-generate.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/getting-started/tooling/esp-generate.md b/src/getting-started/tooling/esp-generate.md index f57d725..a687974 100644 --- a/src/getting-started/tooling/esp-generate.md +++ b/src/getting-started/tooling/esp-generate.md @@ -16,9 +16,9 @@ You can also directly download pre-compiled [release binaries][release-binaries] `esp-generate` provides more than dependency selection: it applies a known set of crates and feature combinations corresponding to the chosen template options, reducing the amount of manual configuration required to produce a working project. -Enabling various options may add additional crates to `Cargo.toml` of the generated project. The templates aim to keep the dependency set minimal while ensuring the generated project is functional and immediately runnable. +When options are selected for the template, `esp-generate` updates the generated `Cargo.toml` with the crates and Cargo features those choices require. The templates aim to keep that list as short as practical while still creating a skeleton of an applications that builds and runs for the selected profile, without the need to manually configure the dependencies for the first successful build. -Wireless connectivity provided by `esp-radio`, as stated in [Ancillary Crates](../../introduction/ancillary-crates.md) chapter, relies on `esp-rtos`. For this reason, enabling Wi-Fi or BLE causes `esp-generate` to include this crate and configure it with the `esp-radio` feature, providing the scheduling and runtime integration required for reliable operation. When Embassy support is enabled, `esp-rtos` also serves as the integration point for async execution on supported chips, with a corresponding feature enabled in the template project. For IP networking, the templates include the surrounding networking components. This typically includes `smoltcp`, `embassy-net` for async networking, when Embassy is enabled. +The [Ancillary Crates](../../introduction/ancillary-crates.md) chapter describes how wireless, async, and networking choices map onto individual crates when that level of detail is needed. Some options have coupled configurations. Logging is configured either via `defmt` or `log` with a corresponding frontend. Certain crates are also included as part of the standard baseline because they support common embedded workflows. For example, `esp-bootloader-esp-idf` includes additional support of 2nd stage bootloader, and `critical-section` is included because many embedded crates rely on it to implement interrupt-critical regions.