esp-rs/esp-idf-template

Version mismatch between tutorial-recommended ESP-IDF and template dependencies

Closed this issue · 3 comments

wuertele commented

Issue Description

Following the official ESP-RS documentation to set up a new project results in build failures due to version incompatibilities between ESP-IDF and esp-idf-svc.

The official documentation guides users to install ESP-IDF 5.0, but the template generates a project using esp-idf-svc 0.49, which is incompatible with ESP-IDF 5.0+. This creates a confusing experience for new users who follow the documentation exactly but end up with unbuildable projects.

Steps to Reproduce

  1. Follow the installation steps at https://docs.esp-rs.org/book/installation/rust.html:

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install espup
espup install
cargo install cargo-generate
cargo install ldproxy

  2. Install ESP-IDF 5.0 as per documentation:

    mkdir -p ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh
source ./export.sh

  3. Generate a new project:

    cargo generate esp-rs/esp-idf-template
# Select 'cargo' template and 'esp32' target

  4. Try to build:

    cd <generated-project>
cargo build

Error Output

Compiling embedded-svc v0.28.0
error[E0063]: missing field `rssi_5g_adjustment` in initializer of `esp_idf_hal::sys::wifi_scan_threshold_t`
   --> /Users/dave/.cargo/registry/src/index.crates.io-6f17d22bba15001f/esp-idf-svc-0.49.1/src/wifi.rs:189:24
    |
189 |             threshold: wifi_scan_threshold_t {
    |                        ^^^^^^^^^^^^^^^^^^^^^ missing `rssi_5g_adjustment`

error[E0063]: missing field `duty_cycle_pos` in initializer of `esp_idf_hal::sys::sdspi_device_config_t`
  --> /Users/dave/.cargo/registry/src/index.crates.io-6f17d22bba15001f/esp-idf-svc-0.49.1/src/sd/spi.rs:41:29
   |
41 |         let configuration = sdspi_device_config_t {
   |                             ^^^^^^^^^^^^^^^^^^^^^ missing `duty_cycle_pos`

Environment

  • espup version: 0.12.2
  • ESP-IDF version: 5.0
  • Generated project's esp-idf-svc version: 0.49
  • Operating System: macOS
  • Rust toolchain: esp (from rust-toolchain.toml)

Additional Context

The current template generates a Cargo.toml that includes:

[dependencies]
esp-idf-svc = { version = "0.49", default-features = false }

This version of esp-idf-svc appears to be incompatible with ESP-IDF 5.0 structures, leading to compilation errors due to missing fields in struct definitions.

Suggested Solutions

  1. Update the template to use a version of esp-idf-svc that's compatible with ESP-IDF 5.0
  2. Add version checking/warnings during project generation
  3. Update the documentation to specify compatible versions of all components
  4. Consider maintaining different template branches for different ESP-IDF major versions

Documentation References

ivmarkov commented
  1. Follow the installation steps at https://docs.esp-rs.org/book/installation/rust.html: 
    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
cargo install espup
espup install
cargo install cargo-generate
cargo install ldproxy

So far so good, and per the documentation, yes.

  1. Install ESP-IDF 5.0 as per documentation: 
    mkdir -p ~/esp
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh
source ./export.sh

This is the problem. In fact, two problems:

  • Problem 1: Why are you doing this in the first place? The "esp-rs" book is NOT supposed to suggest this :) Since you are the second person trying to install ESP IDF "manually" (and then activates it), if you can point out which part in the docu lead you to believe this is necessary would be very appreciated! BTW, building against an activated ESP IDF (or even a non-activated but still separately-cloned one is a supported setup, but we don't advertise loudly to beginners, as it makes stuff even more confusing - as in your case - see below)
  • Problem 2: You are NOT installing (and activating) "ESP IDF 5.0". :) You are installing and activating the unstable ESP IDF master, which could be anything and we give no guarantees for compatibility with master. It might work today, but might not work tomorrow, as Espressif is pushing to it every single day. Including breaking changes.
    • To use a "stable" ESP IDF, you need - post cloning - to switch to a released ESP IDF tag. Look at the ESP IDF repo for released tags. We support all tags up to the latest 5.2.x (but not 5.3.x yet)
    • With that said, the bigger problem is Problem 1, i.e. the fact that you are trying to install (and activate, with source ./export.sh) the ESP IDF yourself. For a beginner setup this is completely unnecessary, as esp-idf-sys does this silently and automatically for you - look in the .embuild directory of your binary crate once you de-activate the above master ESP IDF
wuertele commented

I am doing this in the first place because my naive reading of the esp-rs book seemed to suggest it. I didn't know anything about the esp-idf repo, and I wouldn't have tried to clone it except for trying to follow the esp-rs book. But now that I look through the esp-rs book, I can't find the page that said I should install the esp-idf repo. So this is almost definitely a case of misleading myself about the required dependencies.
I removed the esp-idf repo and started a new shell without the esp-idf environment, and now when I generate using either the esp-rs/esp-template or the esp-rs/esp-idf-template, cargo build succeeds.
Thanks for the hint, this issue can be closed.

ivmarkov commented

I am doing this in the first place because my naive reading of the esp-rs book seemed to suggest it. I didn't know anything about the esp-idf repo, and I wouldn't have tried to clone it except for trying to follow the esp-rs book. But now that I look through the esp-rs book, I can't find the page that said I should install the esp-idf repo. So this is almost definitely a case of misleading myself about the required dependencies. I removed the esp-idf repo and started a new shell without the esp-idf environment, and now when I generate using either the esp-rs/esp-template or the esp-rs/esp-idf-template, cargo build succeeds. Thanks for the hint, this issue can be closed.

Hmmm, as I said, since you are not the first one to stumble on this (we just had another case a couple of weeks ago) and some others in the past, it must be something in the docu.

Well, the plan is anyway to not have any installation instructions in the Book itself, but just a link to the esp-idf-template README. And there I'll try to make it crystal clear in the next days/weeks, that you don't have to deal with ESP-IDF unless you want to (i.e. vendored use cases etc.).

  • ❤️1