Skip to content

Require esp-idf 5.3.x with a clear error - #24

Open
jmarler wants to merge 65 commits into
ZimengXiong:mainfrom
jmarler:fix/idf-version-guard
Open

Require esp-idf 5.3.x with a clear error#24
jmarler wants to merge 65 commits into
ZimengXiong:mainfrom
jmarler:fix/idf-version-guard

Conversation

@jmarler

@jmarler jmarler commented Aug 18, 2026

Copy link
Copy Markdown

problem

main/idf_component.yml declares idf: '>=5.3,<5.4', but nothing enforces it. The Espressif installer (EIM) now defaults to 6.0.x, so a fresh setup builds against an unsupported version and fails several minutes into compilation with two confusing errors:

fatal error: driver/uart.h: No such file or directory
fatal error: mbedtls/rsa.h: No such file or directory

Neither message points at the real cause. The mbedtls one is actively misleading, because ESP-IDF's hint locates the header inside OpenThread's vendored copy of mbedtls and suggests adding an include directory, which cannot work.

Both are IDF 6.0 breaking changes:

  • the driver umbrella component no longer re-exports UART, so REQUIRES driver does not supply driver/uart.h
  • IDF 6.0 ships mbedTLS 4.x, which moved the legacy crypto modules into TF-PSA-Crypto and dropped the public headers. main/piv.c uses mbedtls_rsa_context and mbedtls_rsa_private, and main/touch_pin_hid.c uses mbedtls_aes_crypt_ctr, so no CMake change can fix it.

Reported in #8, where it was understandably attributed to the macOS version rather than the toolchain.

changes

  • firmware/tiny_touch_smartcard/CMakeLists.txt: fail at configure time with install instructions when IDF is not 5.3.x. The check is skipped if IDF_VERSION_MAJOR is undefined, so it cannot break builds on toolchains that do not expose it.
  • tinytouch: run_idf() now checks idf.py --version once before running anything, and reports the same guidance. This matters because run_idf() prefers whatever idf.py is on PATH, then $IDF_PATH/export.sh, so an EIM install silently supplies 6.0.x.
  • main/CMakeLists.txt: add esp_driver_uart to PRIV_REQUIRES. Not required on 5.3, but it is the correct explicit dependency for driver/uart.h.
  • README.md: state the required version in the build section, with install steps and a note to clear build/, sdkconfig, and dependencies.lock after a failed 6.0 attempt. A stale dependencies.lock records the old IDF version and keeps the build broken.

testing

  • Verified the Python guard against idf.py --version reporting 6.0.2, 5.3.3, 5.4.1, and unparseable output. Rejects with actionable text on mismatch, accepts 5.3.x, and falls through quietly when the version cannot be parsed.
  • Built successfully on ESP-IDF 5.3.3 for ESP32-S3 with the guard in place.

notes

This keeps the project on 5.3.x rather than porting to IDF 6.0. Supporting 6.0 means moving piv.c and touch_pin_hid.c to the PSA crypto API, and the raw RSA operation behind PIV general authenticate has no clean PSA equivalent. That felt like a separate decision, so this PR just makes the current requirement explicit and fast to diagnose.

Closes #8

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

does not compile for Mac OSX 26.6

2 participants