Overhaul ecosystem overview

src/SUMMARY.md

@@ -4,7 +4,6 @@
 - [Ecosystem Overview](./overview/index.md)
   - [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)
 - [Setting Up a Development Environment](./installation/index.md)
 - [Tooling](./tooling/index.md)
   - [Text Editors and IDEs](./tooling/text-editors-and-ides.md)

src/misc/troubleshooting.md

@@ -113,3 +113,51 @@ Some of the LLVM 15 releases, `esp-15.0.0-20220922` and `esp-15.0.0-20221014`, r
 - Fedora: `sudo dnf install ncurses-compat-libs`
 - openSUSE: `sudo dnf install libncurses5`
 - Arch Linux: `sudo pacman -S ncurses5-compat-libs`
+
+## 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
+cargo clean
+cargo build
+```
+
+### The documentation for the crates mentioned on this page is out of date or missing
+
+Due to the [resource limits] imposed by [docs.rs], internet access is blocked while building documentation and as such we are unable to build the documentation for `esp-idf-sys` or any crate depending on it.
+
+Instead, we are building the documentation and hosting it ourselves on GitHub Pages:
+
+- [`esp-idf-hal` Documentation]
+- [`esp-idf-svc` Documentation]
+- [`esp-idf-sys` Documentation]
+
+[resource limits]: https://docs.rs/about/builds#hitting-resource-limits
+[docs.rs]: https://docs.rs
+[`esp-idf-hal` documentation]: https://esp-rs.github.io/esp-idf-hal/esp_idf_hal/
+[`esp-idf-svc` documentation]: https://esp-rs.github.io/esp-idf-svc/esp_idf_svc/
+[`esp-idf-sys` documentation]: https://esp-rs.github.io/esp-idf-sys/esp_idf_sys/
+
+### \*\*\*ERROR\*\*\* A stack overflow in task main has been detected.
+
+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
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=7000
+```
+
+In this example, we are allocating 7kB for the main task's stack.
+
+### How can I completely disable the watchdog timer(s)?
+
+Add to your `sdkconfig.defaults` file:
+
+```ignore
+CONFIG_INT_WDT=n
+CONFIG_ESP_TASK_WDT=n
+```
+
+Recall that you must clean your project before rebuilding when modifying these configuration files.

src/overview/bare-metal.md

@@ -1,59 +1,64 @@
-# Bare Metal (`no_std`)
+# Developing on Bare Metal (`no_std`)
 
-Using `no_std` may be more familiar to embedded Rust developers; it does not use `std` (the Rust standard library) but instead uses a subset, the `core` library. The [official Rust embedded book] has a [great section on this].
+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 in general a `no_std` crate can always compile in `std` environment but the inverse is not true. Therefore, when creating crates it's worth keeping in mind if it needs the standard library to function.
+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.
 
-[great section on this]: https://docs.rust-embedded.org/book/intro/no-std.html
-[official rust embedded book]: https://docs.rust-embedded.org/
 
-## Hardware Abstraction Layers
+[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
 
-Previously, the primary focus of `no_std` development was the ESP32 and (to a lesser extent) the ESP8266.
 
-Now there is a renewed effort to implement `no_std` support for the entire lineup of Espressif devices from the ESP32 and newer. These new HALs can be found in the [esp-rs/esp-hal] repository.
+## Current support
 
-There is also some level of support for Wi-Fi and Bluetooth via [esp-rs/esp-wifi] for ESP32, ESP32-C3, ESP32-S2, and ESP32-S3.
+The table below covers the current support for `no_std` at this moment for different Espressif products.
 
-[esp-rs/esp-hal]: https://github.com/esp-rs/esp-hal
-[esp-rs/esp-wifi]: https://github.com/esp-rs/esp-wifi
 
-## Chip Support
+|          | [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    |           ✅           |                  ✅                   |                 ✅                 |               ✅               |
+| ESP32-C2 |           ✅           |                  ✅                   |                 ✅                 |               ✅               |
+| ESP32-C3 |           ✅           |                  ✅                   |                 ✅                 |               ✅               |
+| ESP32-C6 |           ✅           |                  ✅                   |                 ✅                 |               ✅               |
+| ESP32-S2 |           ✅           |                  ✅                   |                 ✅                 |               ✅               |
+| ESP32-S3 |           ✅           |                  ✅                   |                 ✅                 |               ✅               |
+| ESP32-H2 |           ⏳           |                  ⏳                   |                 ✅                 |               ⏳               |
 
-Chip support for `no_std` requires LLVM/Clang support just like for `std`. However, this has no dependency on `esp-idf`. In addition to compiler support, it's necessary to have peripheral access crates (PAC) and hardware abstraction layers (HAL) for your desired chip.
+> **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.
 
-Refer to the table below to see if your chip is supported. Please note that the `no_std` HALs are still in the early phases of development, so not all peripherals have had drivers implemented.
+[esp-wifi-current-support]: https://github.com/esp-rs/esp-wifi#current-support
+### Relevant `esp-rs` crates
 
-|   Chip   |    PAC    |    HAL    |
-| :------: | :-------: | :-------: |
-|  ESP32   |     ✅     |     ✅     |
-| ESP32-C2 |     ✅     |     ✅     |
-| ESP32-C3 |     ✅     |     ✅     |
-| ESP32-C6 | _planned_ | _planned_ |
-| ESP32-S2 |     ✅     |     ✅     |
-| ESP32-S3 |     ✅     |     ✅     |
-| ESP32-H2 | _planned_ | _planned_ |
-| ESP8266  |     ✅     |     ✅     |
+| Repository             | Description                                                |
+| ---------------------- | ---------------------------------------------------------- |
+| [esp-rs/esp-hal]       | Hardware abstraction layer                                 |
+| [esp-rs/esp-pacs]      | Peripheral access crates                                   |
+| [esp-rs/esp-wifi]      | Wi-Fi, BLE and ESP-NOW support                             |
+| [esp-rs/esp-alloc]     | Simple heap allocator                                      |
+| [esp-rs/esp-println]   | `print!`,  `println!`                                      |
+| [esp-rs/esp-backtrace] | Exception and panic handlers                               |
+| [esp-rs/esp-storage]   | Embedded-storage traits to access unencrypted flash memory |
 
-## Relevant `esp-rs` Crates
+### When you might want to use bare metal (`no_std`)
 
-| Repository             | Description                                                                                                        |
-| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| [esp-rs/esp-pacs]      | A monorepo containing PACs for each supported device.                                                              |
-| [esp-rs/esp-hal]       | An implementation of the `embedded-hal` traits and more for the ESP32, ESP32-C2, ESP32-C3, ESP32-S2, and ESP32-S3. |
-| [esp-rs/esp8266-hal]   | An implementation of the `embedded-hal` traits and more for the ESP8266.                                           |
-| [esp-rs/esp-alloc]     | A simple no_std heap allocator.                                                                                    |
-| [esp-rs/esp-println]   | Provides `print!` and `println!`.                                                                                  |
-| [esp-rs/esp-backtrace] | Backtrace support for bare-metal applications.                                                                     |
-| [esp-rs/esp-storage]   | Implementation of embedded-storage traits to access unencrypted flash memory.                                      |
-| [esp-rs/esp-wifi]      | _WIP_: Experimental Wifi and Bluetooth LE support.                                                                 |
+- Small memory footprint: If your embedded system has limited resources and needs to have a small memory footprint, you will likely want to use bare-metal because `std` features add a significant amount of final binary size and compilation time.
+- Direct hardware control: If your embedded system requires more direct control over the hardware, such as low-level device drivers or access to specialized hardware features you will likely want to use bare-metal because `std` adds abstractions that can make it harder to interact directly with the hardware.
+- 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"
+[esp-rs/esp-wifi]: https://github.com/esp-rs/esp-wifi "Wi-Fi, BLE and ESP-NOW support"
+[esp-rs/esp-alloc]: https://github.com/esp-rs/esp-alloc "Simple heap allocator"
+[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"
 
 
-[esp-rs/esp-pacs]: https://github.com/esp-rs/esp-pacs
-[esp-rs/esp-hal]: https://github.com/esp-rs/esp-hal
-[esp-rs/esp8266-hal]: https://github.com/esp-rs/esp8266-hal
-[esp-rs/esp-alloc]: https://github.com/esp-rs/esp-alloc
-[esp-rs/esp-backtrace]: https://github.com/esp-rs/esp-backtrace
-[esp-rs/esp-storage]: https://github.com/esp-rs/esp-storage
-[esp-rs/esp-wifi]: https://github.com/esp-rs/esp-wifi
-[esp-rs/esp-println]: https://github.com/esp-rs/esp-println

src/overview/index.md

@@ -1,21 +1,59 @@
 # Ecosystem Overview
 
-There are two approaches for using Rust on Espressif chips:
+There are the following approaches to using Rust on Espressif chips:
 
-1. _With_ the full standard library available (`std`)
-2. _Without_ the standard library available (`no_std`)
+- Using the `std` library, a.k.a. Standard library.
+- Using the `core` library (`no_std`), a.k.a. bare metal development.
 
-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 followed by a brief comparison between them.
+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 Rust Standard Library (`std`)](./using-the-standard-library.html)
-- [Bare Metal (`no_std`)](./bare-metal.html)
-- [Comparing `std` and `no_std`](./comparing-std-and-no_std.html)
+- [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
+
+See also the comparison of the different runtimes in [The Embedded Rust Book][embedded-rust-book-intro-std].
+
+[embedded-rust-book-intro-std]: https://docs.rust-embedded.org/book/intro/no-std.html#a-no_std-rust-environment
 
 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.
 
 > A note on the repository naming convention
-> In the [esp-rs organization] we use the folling wording:
-> - Repositories starting with `esp-idf-` are focused on `std` apporach. E.g. `esp-idf-hal`
-> - Repositories starting with `esp-` are focused on `no_std` apporach. E.g. `esp-hal`
+> 
+> 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-`
 
 [esp-rs organization]: https://github.com/esp-rs/
+
+## Support for Espressif Products
+
+> **Notes**:
+>
+> - ✅ - The feature is implemented or supported
+> - ⏳ - The feature is under development
+> - ❌ - The feature is not supported
+
+| Chip     | `std` | `no_std` |
+| -------- | :---: | :------: |
+| ESP32    |   ✅   |    ✅     |
+| ESP32-C2 |   ⏳   |    ✅     |
+| ESP32-C3 |   ✅   |    ✅     |
+| ESP32-C6 |   ⏳   |    ✅     |
+| ESP32-S2 |   ✅   |    ✅     |
+| ESP32-S3 |   ✅   |    ✅     |
+| 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].
+
+[esp-idf-release-compatibility]: https://github.com/espressif/esp-idf#esp-idf-release-and-soc-compatibility