esp-rs/book

The Rust on ESP Book

book's Issues

Expand Debug section

• note that esp8266 is not supported via openocd-esp32

Glossary ...

I've started skimming through the book and (if it's ok) will note feedback as I go along in the form of issues (or maybe PR's if I feel bold :)

In overview.md: In the final table, you refer to PAC crates, but I'm not sure if that acronym is widely known outside of rust-embedded circles. Some other terms that may be worth adding to a glossary:

• SVD
• NVS
• HAL

Also, I assume rng is random num generator, which doesn't seem to be included in std (may be mistaken, not well versed in all things Rust)

Mermaid graph diagram not rendering

In overview section, there is a mermaid graph which isn't being rendered on live book.

This should have rendered to something like this:

graph TD;
    esp-idf-hal --> esp-idf-sys & embedded-svc
    esp-idf-svc --> esp-idf-sys & esp-idf-hal & embedded-svc

If we run mdbook serve locally, the graph gets rendered correctly, this issue is only when it's live on website.

winpty needed with cargo generate command

On a windows system, without 'winpty' running the cargo generate command would result in Error: Incorrect function. (os error 1).

After a bit of searching, I found than preceding the command with winpty made everything worked.

Tripped this newbie up good'n'proper!

Add a detailed tutorial creating a non-trivial application

Walking people through implementing a real-world project using Rust would likely help jumpstart many people's progress. One suggestion was a camera web server, or we could do a Wi-Fi lightbulb project or something similar.

• std
• no_std

Add troubleshooting step for "invalid toolchain name: 'esp'"

I've run into this message on ubuntu from running rustup show or cargo build after doing all the installation steps for ESP via espup and trying to build a new project based on esp-template

invalid toolchain name: 'esp'

This was caused by having rustup installed via snap, removing that and reinstalling rustup via the normal shell scripts resolved the issue.

This should be added to troubleshooting, it would have saved me an hour or more. Snap is really the worst :(

Add references in trooubleshooting

Add references to the sections in the troubleshooting chapter.

Originally posted by @f-hollow in #81 (comment)

esp-idf (rust) + esp-idf(C)

How can I generate FFI Bindings to Rust from a esp-idf library written in C ?

I want use this library ricardoquesada/bluepad32 on my project generated by esp-idf-template (rust).

Update actions using Node12

The repository contains actions using Node12 which are producing a warning in every CI run. Node12 will stop working this summer, so we should update them, for more information see: https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/

Improve the ESPFLASH section

Key need: specify port. In most cases, one needs to specify the port, and neither this document nor the espflash documentation is clear on how to do so. It appears the first argument is the name of the port, but not clear.

The espflash documentation states there is a configuration file on windows which is not true. ChatGPT thinks there is an environment variable which is used, also doesn't seem true.

There are also three esptools (or two, one with two invokation mechanism?): the one you may have from doing development with esp-idf, the one you get with a standard cargo and is global, and the per-project espflash. Instructions you find about these three are confusing because some take port as an option (--port) and some have it as a positional option. When I read different documents its very confusing because of the three tools. Documentation on one doesn't work for the others.

It seems most people get something working then just use it. in my C++ based env I just use idf.py so I've never had to understand espflash

I would suggest: bring up the different tools, explain which ones document what.

Then, suggest the per-project one as per the current document, but show how to override the port, and/or set a port in the config file.

Thanks! When I learn the answer, can I put in a PR? Right now I don't know the answer, can't flash yet.

The Installing Rust section should be updated to use `espup`

@SergioGasquez would you be able to take care of this when you get a chance please? (Very low priority)

RTOS Support

Hello!
Is there any current support for a RTOS with esp-rs (for example a safe API to work with the ESP-IDF FreeRTOS) ?
And if yes could it be documented in the Book? (And if not maybe add a part or note about the status of RTOS with esp-rs).
(I am new to this environment, sorry if the question isn't relevant.)

Thank you for your help

The "Debugging in Visual Studio Code" section should be updated to reflect all supported chips

https://esp-rs.github.io/std-training/02_2_software.html

Please add to 02_2_software.html these three packages.
Without them installing espflash doesn't work with WSL:

sudo apt install pkg-config libudev-dev make

Although it is mentioned in the "Troubleshooting area" (apt-get update \ && apt-get install -y vim nano git curl gcc ninja-build cmake libudev-dev python3 python3-pip libusb-1.0-0 libssl-dev \ pkg-config libtinfo5) it is still better to mention it a line before "cargo install cargo-espflash espflash ldproxy"

Improve wording of the results of installing the toolchain with `espup`

In section https://esp-rs.github.io/book/installation/index.html#risc-v-and-xtensa-targets:

After running espup install:

• no_std (bare-metal) applications should work out of the box
• std applications require additional software covered in std Development Requirements

An GPIO example would be nice to have, some analoge/SPI/I2C/UART Read/Write

Hello everyone,
I'm just getting started with Rust, as well as Embedded Rust. While finding a lot about Rust, I really don't get the Embedded part... how to communicate or read a sensor is faar from obvious and I find my self handling registers like in the old days. Is there some hidden relationship between creates I don't see? how can I read an i2C bus just one or two functions away? how do I program an PWM Pin without setting it's register? Are there abstractions for that? Are thous in the esp-idf-hal? I saw something called i2c and gpio or spi in there that sounds promising but it seams to be a documentation less create, were is the documentation? Is there some kind of Parent create?
All those questions are in my head when I think about programming my sweet esp32 in Rust and It would be super nice if at least a part could be answered it this Book. The best demo I could find is the rust-esp32-std-demo and while there is a lot of interesting stuff in here It's more about networking and less about micro controlling.
Thx in andvance and If somebody gets me on track with some stuff to read I would love to answer some of those questions with an easy DHT and or led example in the book.

Document `_latest` tags

Update devcontainers images section as we now generate _latest tags

Emphasize the need to use `rustup`, mention issues with using a system package manager

Installing Rust via a system package manager (eg. brew, apt, dnf, etc.) can result in various issues and incompatibilities, so it's best to use rustup instead.

Flashing from with WSL is also possible

It's not much more troublesome than flashing from Windows.

• Both need the CP210x driver to be installed
• Instead of flashing tools, the usbip-win USB/IP server needs to be installed

WSL has usbip within it, and the two are intended to work together. I would add a mention about this to the "Troubleshooting" section:

-build inside WSL and only flash the compiled MCU ELF file from outside of WSL.
+build inside WSL and only flash the compiled MCU ELF file from outside of WSL. A third is to use USB/IP to show the development board within WSL itself, and flash it from there <sub>[ESP32-WSL](https://github.com/lure23/ESP32-WSL)</sub>. Pick your poison.

Should I send this as a PR? Is it too much to have the repo link included?

Improve references to C IDF documentation

We should have an explicit reference to the C IDF documentation in case of std as the concepts there apply to Rust esp-idf-* as well. Some of the questions in the Matrix chat could have been self answered if people would have looked into the IDF documentation

Elaborate about different application models for std

In the std / IDF case there are different ways to implement an application model i.e. MessageLoop, async. I think it would be helpful to present these approaches. As a bonus presenting an approach for handling of peripherals as application state would ease it for beginners (I know there is a section in the embedded-rust book, but this is close to embassy)

Add general diagram

We could add a diagram that shows the whole ecosystem in some intro chapters of the book.
@FMFigueroa already created this: https://sharing.clickup.com/9008002852/wb/8cepdt4-184/whiteboard which can be used as a starting point

Mermaid diagrams are not working properly

Mermaid diagrams are not being rendered:

Here are the errors shown in the console:

error: could not compile `embuild`

Hi there,
I'm trying to get a "hello world" up and running but I'm getting an error.
I tried to follow the https://esp-rs.github.io/ guide

• ran the esp32 install wizard where the rust option was checked

rustup toolchain list gives me
stable-x86_64-pc-windows-msvc
nightly-x86_64-pc-windows-msvc
esp (default) (override)

• cargo install ldproxy
• cargo install cargo-espflash
• cargo install cargo-espmonitor
• cargo install cargo-generate
• cargo generate --git https://github.com/esp-rs/esp-idf-template cargo
• cargo build

I get the following.
I must be missing something...

cargo espflash 
Serial port: COM3
Connecting...

Chip type:         ESP32 (revision 1)
Crystal frequency: 40MHz
Flash size:        4MB
Features:          WiFi, BT, Dual Core, 240MHz, VRef calibration in efuse, Coding Scheme None
MAC address:       30:ae:a4:c5:57:80
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
   Compiling embuild v0.28.1
'+memctl' is not a recognized feature for this target (ignoring feature)
'+memctl' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
'+highpriinterrupts' is not a recognized feature for this target (ignoring feature)
error: edition 2021 is unstable and only available with -Z unstable-options

error: could not compile `embuild`

Update source commands

In the espup section, we should update the export commands as they now use the full path once espup v0.2.2 is released

Add `esp-hal-get-started` book content

Include @bjoernQ book esp-hal book content into the book

Improve QEMU section

Update code example in the `Writing no_std applications` section

A few things changes (in incompatible ways) so we need to update the example code and maybe some of the descriptions

Add more information about `esp-idf` regarding versions and components

• We should elaborate on std's dependency on esp-idf, and the various IDF versions
• We should explain how to go about using components from esp-idf

Add a section on probe-rs and builtin jtag

Improve instructions on sourcing espup files

Add notes on how to add the environment variables permanently

Mention the `CONFIG_ESP_CONSOLE_USB_CDC` configuration value

This has come up a number of times in Matrix already, when using an ESP32-S2's USB peripheral for printing (which is the case on a number of Adafruit boards) you must add the following to your sdkconfig file:

CONFIG_ESP_CONSOLE_USB_CDC=y

Apply guidelines, fix formatting and update chapter titles

Now that we've overhauled the content, we need to do some proofreading, update the format of the book, apply guidelines and update the chapter titles.

about translation

Hello!

Are there any plans to translate this book? Can I maintain a Chinese translation?

Clarify std vs no-std

The book currently says:

When You Might Want to Use the Core Library (no_std)

1. 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.
2. 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.
3. 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.
4. 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.

Are these really true?

1. As I understand it, esp32-rs uses build-std which (when using LTO) should allow unused code to be eliminated (tbf I haven't tested this).
2. Low level device drivers can surely work fine with std - any abstractions it adds (I guess you're thinking stuff like filesystem access?) are surely optional?
3. I guess this is talking about multithreading? But is there really any overhead if you never spawn more than one thread?
4. Seems pretty nebulous?

I'm sure there are reasons to use no_std but these descriptions didn't really convince me. More specifics would be great here!

It would also be great if there was a section on which parts of std are implemented. Seems like threads are? Presumably std::fs isn't, etc.

Tracking the overhaul and re-organization of the book

Due to a number of factors the book is not currently in the best shape. Due to the nature of organic growth things are not necessarily structured how they should be, and information is spread out all over the place.

In general, in addition to the structural changes listed below, the intent of this effort is to improve the quality of text and remove anything which may cause confusion and/or lie beyond the scope of this book. We can relegate to other documents more than we currently are, for example.

Based on a meeting between @SergioGasquez and myself:

• 1. Introduction #61
  • Why should I use Rust and/or ESP devices?
  • Make it clear that Espressif is involved in the project
• 2. Ecosystem Overview #75
  • What are the different approaches? (std, no_std)
  • Why should you use one or the other?
  • Combine chip support tables into one
  • Additional sub-chapters or appendices detailing each approach
• 3. #63 - #62 - #74
  • Defer to the tooling's documentation when possible
  • NOT going to document installing Rust
  • NOT going to document install ldproxy
  • Move troubleshooting to an Appendix (or something)
• 4. Writing an Application - #81
  • At the very least both std and no_std should have the same steps in the tutorial
  • We will need to decide how to structure all this
• 5. Tooling - #81
  • For editors, only discuss using VS Code and Rust Analyzer
  • Get rid of the espmonitor chapter
  • This whole chapter just needs general improvement (especially debugging)
• 6. Appendix A - Troubleshooting - #62

If you have any questions, concerns, or feedback about these changes please leave a comment below.

Improve debuging section

Tasks

Beta Give feedback

1. Document how to install GDB/openOCD, see esp-rs/espup#257 (comment)
2. Improve current sections
3. The "Debugging in Visual Studio Code" section should be updated to reflect all supported chips
4. note that esp8266 is not supported via openocd-esp32
5. Explain the differences between openOCD, VsCode and probe-rs

Add a comparison of `std` vs `no_std` approaches

It seems to be unclear to a number of newer users why you would select one approach over the other. It would be good to have a section dedicated to describing both approaches and comparing their advantages and disadvantages.

no_std training book

Shall we keep the content of the "no_std" book in this book or should it be an standalone book?

I don't have any hard opinion, what I would like to have is the code available in the repo, so we can have proper CI testing it. But since we already have a "std book" (Ferrous System training) I would do something equivalent (even if the examples are different) for no_std.

Try to redirect to updated pages where possible

It looks like mdbook has redirect support (rust-lang/mdBook#1237), we should try and leverage this with the rewrite to not break old links. At the very least we should try and redirect to the landing page instead of a 404.

Talk about async executors in the FAQ (or some other section)

We have been getting a number of questions in Matrix recently regarding async executors, and which executors are supported by which HALs. We should write some content about this so that we can just link to it instead of having to repeat ourselves so often.

Update `libtinfo5` error

Starting from version 1.66.0.0 of rust-build installer and espup v0.2.4. libtinfo5 is no longer required, so we should update the solution

Improve Wokwi section

Things to add:

• Binary simulation is available in template projects when using devcontainers
• Custom chips

Elaborate on third-party crate compatibility

In general most crates should work when using std, however in practice there seem to be some which rely on functionality which has yet to be implemented.

For example, supposedly the image crate fails with allocation errors during the encoding step (I have not confirmed this personally, but it was reported from the community).

Setting Up a Development Environment

How to debug with vscode

Can anyone detail the steps required to setup debugging?

I'm working with the ESP32-C3 and can flash with command line using "cargo espflash --monitor COM8" although would be good if this could be done through vscode, and optionally launch the debugger.

Add pointers to further guidance

It would be very useful to have a pointer in the book as to where to look for further information, especially if things simply don't work. For example, I've followed the instructions in Chapter 3 (installing Rust, nightly, espup (both the cargo install command and espup install), and sourcing the resulting environment file), and when I build and run the project I get something that's really not covered in the troubleshooting section at all:

$ cargo run                                                                                           1 ↵  10059  13:43:09
    Finished dev [unoptimized + debuginfo] target(s) in 0.39s
     Running `espflash flash --monitor target/riscv32imac-unknown-none-elf/debug/exp3`
[2024-01-31T18:43:17Z INFO ] Detected 6 serial ports
[2024-01-31T18:43:17Z INFO ] Ports which match a known common dev board are highlighted
[2024-01-31T18:43:17Z INFO ] Please select a port
✔ Remember this serial port for future use? · no
[2024-01-31T18:43:19Z INFO ] Serial port: '/dev/cu.usbmodem141401'
[2024-01-31T18:43:19Z INFO ] Connecting...
[2024-01-31T18:43:20Z INFO ] Using flash stub
Chip type:         esp32c6 (revision v0.0)
Crystal frequency: 40MHz
Flash size:        8MB
Features:          WiFi 6, BT 5
MAC address:       40:4c:ca:4e:6a:28
App/part. size:    202,480/8,323,072 bytes, 2.43%
[00:00:00] [========================================]      13/13      0x0
[00:00:00] [========================================]       1/1       0x8000
[00:00:01] [========================================]      79/79      0x10000                                                                                                      [2024-01-31T18:43:21Z INFO ] Flashing has completed!
Commands:
    CTRL+R    Reset chip
    CTRL+C    Exit

ESP-ROM:esp32c6-20220919
Build:Sep 19 2022
rst:0x15 (USB_UART_HPSYS),boot:0x4 (DOWNLOAD(USB/UART0/SDIO_FEI_FEO))
Saved PC:0x408007fe
0x408007fe - core::option::Option<T>::unwrap
    at /Users/<user>/.rustup/toolchains/nightly-x86_64-apple-darwin/lib/rustlib/src/rust/library/core/src/option.rs:929
waiting for download

and it just waits there.

I'm not expecting to get help on this error here in this issue tracker specifically. I wouldn't mind it of course, but mostly I'd just expect just a pointer to the right place to ask, and I think wherever you point me for this issue should probably be mentioned in the book in the troubleshooting section.