# Ecosystem Overview There are the following approaches to use Rust on Espressif chips: - Using the `standard` library (`std`) - 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. - [Standard library (`std`) vs. Bare Metal (`no_std`)][rust-esp-book-std-vs-no-std] - [Using the Standard Library (`std`)][rust-esp-book-std] - [Developing on Bare Metal (`no_std`)][rust-esp-book-no-std] [rust-esp-book-std-vs-no-std]: ./comparing-std-and-no_std.html [rust-esp-book-std]: ./using-the-standard-library.html [rust-esp-book-no-std]: ./bare-metal.html 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` > > 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/ --- # Standard library (`std`) vs. Bare Metal (`no_std`) ## Support for Espressif Products | Chip | `std` | `no_std` | | -------- | :--------: | :---: | | ESP32 | ✅ | ✅ | | ESP32-C2 | _planned_ | ✅ | | ESP32-C3 | ✅ | ✅ | | ESP32-C6 | ? | _planned_ | | ESP32-S2 | ✅ | ✅ | | ESP32-S3 | ✅ | ✅ | | ESP32-H2 | _planned_ | _planned_ | | 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. ## Software Stacks `std` - Rust `std` library - [newlib][newlib-env] - esp-idf `no_std` - Rust `core` library - peripheral access crates (PAC) - hardware abstraction layers (HAL) In both cases, LLVM/Clang is required for compilation. [newlib-env]: https://sourceware.org/newlib/ --- # Using the Standard Library (`std`) Espressif provides a C-based development framework called [esp-idf][esp-idf-github] which has support for all Espressif chips starting with the ESP32; note that this framework does _not_ support the ESP8266. See also Section [Support for Espressif Products][rust-esp-book-std-vs-no-std-support]. [rust-esp-book-std-vs-no-std-support]: ./comparing-std-and-no_std.html#support-for-espressif-products `esp-idf` in turn provides a [newlib][newlib-env] environment with enough functionality to build the Rust standard library (`std`) on top of it. This is the approach that is being taken to enable `std` support on ESP devices. [esp-idf-github]: https://github.com/espressif/esp-idf ### Supported `std` Features Espressif products support a lot of `std` features that exist in [esp-idf][esp-idf-github], including threads, mutexes and other synchronization primitives, collections, random number generation, sockets. [esp-rs/esp-idf-svc](https://github.com/esp-rs/esp-idf-svc) adds extra support for services/modules not available in the standard library, such as Wi-Fi management, NVS (non-volatile storage), networking services, such as `httpd` and `ping`, etc. ### Relevant `esp-rs` crates [esp-idf-github]: https://github.com/espressif/esp-idf | Repository | Description | | --------------------- | ------------------------------------------------------------------------------------------------------------- | | [esp-rs/esp-idf-svc] | An implementation of [embedded-svc] using `esp-idf` drivers. | | [esp-rs/esp-idf-hal] | An implementation of the `embedded-hal` and other traits using the `esp-idf` framework. | | [esp-rs/esp-idf-sys] | Rust bindings to the `esp-idf` development framework. Gives raw (`unsafe`) access to drivers, Wi-Fi and more. | | [esp-rs/embedded-svc] | Abstraction traits for embedded services (`WiFi`, `Network`, `Httpd`, `Logging`, etc.) | [newlib]: https://sourceware.org/newlib/ [embedded-svc]: https://github.com/esp-rs/embedded-svc [esp-idf-svc]: https://github.com/esp-rs/esp-idf-svc The aforementioned crates have interdependencies, and this relationship can be seen below. ```mermaid graph TD; esp-idf-hal --> esp-idf-sys & embedded-svc esp-idf-svc --> esp-idf-sys & esp-idf-hal & embedded-svc ``` [esp-rs/embedded-svc]: https://github.com/esp-rs/embedded-svc [esp-rs/esp-idf-svc]: https://github.com/esp-rs/esp-idf-svc [esp-rs/esp-idf-sys]: https://github.com/esp-rs/esp-idf-sys [esp-rs/esp-idf-hal]: https://github.com/esp-rs/esp-idf-hal --- # 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 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. [embedded-rust-book]: https://docs.rust-embedded.org/ [embedded-rust-book-no-std]: https://docs.rust-embedded.org/book/intro/no-std.html ## Relevant `esp-rs` crates The table below covers what `no_std` features are supported by Espressif products. > **Notes**: > > - Hover your cursor over the links in the table header to see feature details. > - The icon ⏳ indicates that the feature is under development. > - Features marked with * must be installed for `no_std` to work. | | [HAL][esp-rs/esp-hal]* | [PAC][esp-rs/esp-pacs]* | [Wi-Fi][esp-rs/esp-wifi] | [Bluetooth][esp-rs/esp-wifi] | [Heap][esp-rs/esp-alloc] | [Println][esp-rs/esp-println] | [Backtrace][esp-rs/esp-backtrace] | [Storage][esp-rs/esp-storage] | | -------- | :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: | | ESP32 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | ESP32-C2 | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | | ESP32-C3 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | ESP32-C6 | ✅ | ✅ | ✅ | ⏳ | ❌ | ✅ | ✅ | ❌ | | ESP32-S2 | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | | ESP32-S3 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | | ESP32-H2 | ❌ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | | ESP8266 | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | The `no_std` features are elaborated on below. - **HAL** -- Hardware abstraction layer, see [esp-rs/esp-hal] and [esp-rs/esp8266-hal] - **PAC** -- Peripheral access crates, see [esp-rs/esp-pacs] - **Wi-Fi** -- Wi-Fi support, see [esp-rs/esp-wifi] - **Bluetooth** -- Bluetooth LE support, see [esp-rs/esp-wifi] - **Heap** -- Simple heap allocator, see [esp-rs/esp-alloc] - **Println** -- `print!`, `println!`, see [esp-rs/esp-println] - **Backtrace** -- Exception and panic handlers, see [esp-rs/esp-backtrace] - **Storage** -- Embedded-storage traits to access unencrypted flash memory, see [esp-rs/esp-storage] [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 [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 and Bluetooth LE 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"