feat(lws): bump submodule for mbedTLS 4 support; allow IDF v6.0 by vikramdattu · Pull Request #1070 · espressif/esp-protocols

vikramdattu · 2026-06-04T11:09:21Z

Summary

Bump libwebsockets submodule from `a74362ff` → `7726361c` (warmcat main HEAD) which carries Andy Green's mbedTLS 4 migration commits (`3079d311 mbedtls4` + `7726361 sai-fixes` completing it).
Drop the `idf <6.0` cap from `idf_component.yml` — IDF v6.0 ships mbedTLS 4 by default and the bumped libwebsockets supports it. Component version `4.3.3~~1` → `4.3.3~~2`.

Verification

`examples/client` builds clean on IDF release/v6.0 (target esp32) — exit 0, full link.
No release tag of libwebsockets carries mbedTLS 4 support yet (v4.5.8 predates the migration); pinning by SHA is the only option until warmcat cuts a tag.

Notes

Sequenced after PR feat(lws): add Kconfig toggles + bump submodule #1061 (libwebsockets Kconfig + 4.3-stable bump). feat(lws): add Kconfig toggles + bump submodule #1061 stays on 4.3-stable; this PR moves to main.

Note

Medium Risk
Substantial CMake and TLS/errno linkage workarounds for IDF v6; mistakes could affect v5.x builds despite guards, or TLS/HTTP behavior on v6 targets.

Overview
Enables libwebsockets on ESP-IDF v6.0 by lifting the idf <6.0 dependency cap and adding release-v6.0 to the libwebsockets CI build and on-target matrices.

The ESP-IDF port gains mbedTLS 4–aware CMake: it forces LWS_HAVE_MBEDTLS_V4 when IDF’s mbedTLS major is ≥4, adds tf-psa-crypto and v6-only include paths (flash/PSA/security/gpio), fixes picolibc TLS errno via LWIP_ERRNO_INCLUDE and esp_libc prepend, and relaxes -Werror for known v6 header noise. esp_driver_gpio is a public REQUIRES so lws-freertos.h consumers get driver/gpio.h.

port/lws_port.c supplies if_nametoindex when LWIP_NETIF_API==0 (IDF ≤5.3) for newer lws link requirements. The client example pulls espressif/cjson for v6, defaults to a large app partition, and CI ignores MBEDTLS_PSA_BUILTIN redefinition warnings.

^{Reviewed by Cursor Bugbot for commit 9bbf1ab. Bugbot is set up for automated code reviews on this repo. Configure here.}

vikramdattu · 2026-06-04T13:07:19Z

Hi @david-cermak — heads up on the clang-tidy failure: it's not the
code in this PR, it's an upstream libwebsockets bug.

At the SHA we pin (7726361c) — and at every SHA after a68609413 "qpack" (May 20) — the tree declares a gitlink
minimal-examples-lowlevel/api-tests/api-test-qpack/qifs but ships no
.gitmodules file. So git submodule update --init --recursive
fails. I checked: .gitmodules was never in the repo; Andy Green
added the gitlink without registering it. Bisecting to an earlier
lws SHA can't escape it without losing the mbedtls4 commit.

I've filed the upstream fix: warmcat/libwebsockets#3597.

Two paths:

Wait for the warmcat maintainer to review and merge #3597 — could
be a few days.
Interim workaround in this PR's CI: replace the recursive
submodule init with explicit per-component non-recursive inits
(scoped to lws, doesn't touch asio/mosquitto).

Which do you prefer?

david-cermak · 2026-06-04T14:45:48Z

Wait for the warmcat maintainer to review and merge #3597 — could
be a few days.

Interim workaround in this PR's CI: replace the recursive
submodule init with explicit per-component non-recursive inits
(scoped to lws, doesn't touch asio/mosquitto).

Both options are fine with me. If the upstream fix gets merged within days, I would wait.

vikramdattu · 2026-06-04T15:44:56Z

@@ -1,5 +1,5 @@
-version: "4.3.3~1"
+version: "4.3.3~2"


@david-cermak the version and the changelog above will pick the commit title automatically?

@vikramdattu see https://github.com/espressif/esp-protocols/blob/master/CONTRIBUTING.md#release-process

the commit (when created by the bump command) will update the version files and changelog (based on commit delta from the previous tag)

when created by the bump command

but that doesn't support these ~postfix numbers (yet), so you'd need to edit the commit.

Here's an example #1071

PS: If you like, we can merge #1071 to release v4.3.3~2 for now, and after the upstream maintainers fix the above, we can merge this one to release v4.3.3~3

vikramdattu · 2026-06-09T09:37:00Z

Rebase needed once warmcat/libwebsockets#3600 and warmcat/libwebsockets#3601 and warmcat/libwebsockets#3602 are merged

cursor · 2026-06-20T15:20:04Z

+     _mbedtls_major REGEX "^#define MBEDTLS_VERSION_MAJOR[ \t]+[0-9]+")
+if(_mbedtls_major MATCHES "[ \t]+([0-9]+)" AND CMAKE_MATCH_1 GREATER_EQUAL 4)
+    set(LWS_HAVE_MBEDTLS_V4 1 CACHE INTERNAL "mbedtls 4 detected on IDF")
+endif()


MBTLS v4 CMake cache stale

Medium Severity

LWS_HAVE_MBEDTLS_V4 is written with CACHE INTERNAL only when mbedTLS major is at least 4, and never reset when it is not. Reconfiguring the same build directory after switching from IDF v6 to v5.x can leave the flag at 1, so libwebsockets still takes the mbedTLS 4 path against mbedTLS 3 headers.

^{Reviewed by Cursor Bugbot for commit 49985d5. Configure here.}

Pin the libwebsockets submodule at warmcat main (mbedTLS 4 + the FreeRTOS/ESP-IDF v6 build fixes), allow IDF v6.0, and force lws's mbedTLS 4 code path on IDF: lws's own V4 probe doesn't run on FreeRTOS, so detect the version from the IDF mbedtls component and inject the tf-psa-crypto include dirs.

…upstream) The mbedTLS 4 / ESP-IDF v6 build support (warmcat/libwebsockets#3603) is now on libwebsockets main, so point the submodule at upstream main instead of the PR branch. Verified: examples/client builds clean on ESP-IDF v6.0 (esp32, stock mbedtls).

Make the component + client example build under ESP-IDF v6 (mbedTLS 4): - keep upstream lws warnings non-fatal under IDF's global -Werror (-Wno-error) so harmless format/redefinition warnings in lws sources don't fail the build - expose tf-psa-crypto/include + the split-out v6 component includes lws needs - point lwip errno at <sys/errno.h> and prefer esp_libc TLS errno (picolibc) - set LWS_HAVE_MBEDTLS_V4 when IDF mbedtls is v4 so lws takes the v4 code paths - example: add espressif/cjson (left IDF built-ins in v6) + large single-app partition All additions are EXISTS-guarded / version-gated, so IDF v5.x is unaffected.

idf_component_get_property() hard-errors when the component isn't in the build, so the esp_hal_mspi / esp_blockdev / esp_libc include workarounds broke CMake configure on IDF v5.x (those components are v6-only). Check BUILD_COMPONENTS membership before each lookup; v6 still picks them up by bare name (verified), v5.x cleanly skips them.

The previous pin (b4f9c5cb 'h2-h3-happy-eyeballs') introduced an unrelated format-specifier warning in lib/core-net/client/connect3.c ('%u' vs uint32_t) that is fatal under -Werror on the v5.3/v5.4 toolchains (where uint32_t is 'long unsigned int'). Its parent 906de57a0 still carries the mbedTLS 4 / IDF v6 support (e6f4d0ec) and the wrapper-removal refactor, without the QUIC regression. Upstream fix to be filed separately.

warmcat/libwebsockets#3618 (cast uint32_t grace_us for the %u format specifier in connect3.c) is now on main, so move the pin forward from the temporary parent-commit pin to current main (00130694a). Verified: examples/client builds clean on ESP-IDF v6.0 (esp32).

Recent libwebsockets uses if_nametoindex() in lws_get_addr_scope(). ESP-IDF <= v5.3 builds lwip with LWIP_NETIF_API==0, so if_api.c isn't compiled and the symbol - declared in newlib's <net/if.h> - is never defined, breaking the link. Provide a fallback in the port shim that mirrors lwip's own implementation (the ungated core netif_name_to_index helper), gated on !LWIP_NETIF_API so v5.4+ (where lwip supplies it) is untouched. Verified no regression on v6.0.

…F v6 IDF v6's mbedtls port esp_config.h redefines MBEDTLS_PSA_BUILTIN_ALG_HMAC (and siblings) that tf-psa-crypto already defines. The build compiles and links fine (our -Wno-error keeps it non-fatal), but idf-build-apps' check_warnings flags the 'warning: redefined' line and fails the job. It's a harmless IDF-side redefinition; add it to the CI ignore list.

…6/mbedTLS-4 lws-freertos.h pulls <driver/gpio.h> (esp_driver_gpio) into every consumer, and the mbedTLS-4 PSA header chain needs esp_security/esp_hal_security include dirs that mbedtls links PRIVATE. Add them so the add_subdirectory websockets target and consumers resolve on IDF v6.

vikramdattu · 2026-07-14T14:53:52Z

@david-cermak heads-up for when you set the component version on this PR — it'll be a minor bump + a ~ snapshot suffix, not a routine ~N revision.

The lws submodule is pinned to a warmcat main snapshot (da5d6f5f9, git describe = v4.5.0-590-gda5d6f5f9), not a release tag — because the mbedTLS-4 / IDF-v6 support isn't in any tagged v4.5.x release yet; it only exists on main. So the component's lws version moves from 4.3.3 up to the ~4.5.x line (minor jump), and the ~1 denotes "esp-protocols snapshot of that main state." Same rationale is noted inline in idf_component.yml.

(We pinned an older/settled main commit deliberately — warmcat force-pushes main and has orphaned our pins before; a 1–2-day-old commit is likelier to survive. Once a tagged lws release carries mbedTLS-4, we can switch to the tag.)

Replaces the moving-main churn pins with a single settled warmcat main commit (v4.5.0-590-gda5d6f5f9, 2026-07-13) that carries the mbedTLS-4/IDF-v6 support the v4.5.x release tags lack. Older, so likelier to survive warmcat's main force-pushes. (Version bump is the maintainer's call — see PR discussion.)

cursor

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

^{Reviewed by Cursor Bugbot for commit 9bbf1ab. Configure here.}

cursor · 2026-07-14T14:58:04Z

 warning: unknown kconfig symbol 'EXAMPLE_ETH_PHY_IP101'
 WARNING: The following Kconfig variables were used in "if" clauses, but not
 warning: unknown kconfig symbol 'LIBC_NEWLIB'
+warning: 'MBEDTLS_PSA_BUILTIN_[A-Z0-9_]+' redefined


CI ignore pattern quote mismatch

Medium Severity

The new ignore entry wraps the macro name in single quotes, but GCC emits this redefinition diagnostic with double quotes ("MBEDTLS_PSA_BUILTIN_..."). idf-build-apps regex-matches warning lines, so the pattern will not suppress the IDF v6 PSA redefinition warnings that -Wno-error still leaves in the build log, and the new release-v6.0 CI matrix entry can fail check_warnings.

^{Reviewed by Cursor Bugbot for commit 9bbf1ab. Configure here.}

espressif-bot added the Status: Opened Issue is new label Jun 4, 2026

vikramdattu force-pushed the feat/libwebsockets/mbedtls4-idf6 branch from 231032f to 98a9ac5 Compare June 4, 2026 14:39

david-cermak added the lws libwebsockets label Jun 4, 2026

vikramdattu commented Jun 4, 2026

View reviewed changes

espressif-bot assigned david-cermak Jun 5, 2026

espressif-bot added Status: Selected for Development and removed Status: Opened Issue is new labels Jun 5, 2026

vikramdattu changed the title ~~feat(lws): bump submodule for mbedTLS 4 support; allow IDF v6.0~~ Draft: feat(lws): bump submodule for mbedTLS 4 support; allow IDF v6.0 Jun 8, 2026

vikramdattu changed the title ~~Draft: feat(lws): bump submodule for mbedTLS 4 support; allow IDF v6.0~~ feat(lws): bump submodule for mbedTLS 4 support; allow IDF v6.0 Jun 8, 2026

vikramdattu marked this pull request as draft June 9, 2026 09:37

vikramdattu mentioned this pull request Jun 9, 2026

quic: gate mbedtls_ssl_get_alpn_protocol on LWS_HAVE probe warmcat/libwebsockets#3598

Closed

vikramdattu marked this pull request as ready for review June 9, 2026 15:58

vikramdattu force-pushed the feat/libwebsockets/mbedtls4-idf6 branch from c144d26 to 617e107 Compare June 9, 2026 16:03

vikramdattu mentioned this pull request Jun 19, 2026

mbedTLS 4 / ESP-IDF v6 build support warmcat/libwebsockets#3603

Closed

cursor Bot reviewed Jun 20, 2026

View reviewed changes

david-cermak added lws libwebsockets and removed lws libwebsockets labels Jun 22, 2026

vikramdattu added 9 commits July 14, 2026 20:21

vikramdattu force-pushed the feat/libwebsockets/mbedtls4-idf6 branch from c08f08a to e816078 Compare July 14, 2026 14:53

vikramdattu force-pushed the feat/libwebsockets/mbedtls4-idf6 branch from e816078 to 9bbf1ab Compare July 14, 2026 14:54

cursor Bot reviewed Jul 14, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(lws): bump submodule for mbedTLS 4 support; allow IDF v6.0#1070

feat(lws): bump submodule for mbedTLS 4 support; allow IDF v6.0#1070
vikramdattu wants to merge 10 commits into
espressif:masterfrom
vikramdattu:feat/libwebsockets/mbedtls4-idf6

vikramdattu commented Jun 4, 2026 •

edited by cursor Bot

Loading

Uh oh!

vikramdattu commented Jun 4, 2026

Uh oh!

david-cermak commented Jun 4, 2026

Uh oh!

vikramdattu Jun 4, 2026

Uh oh!

david-cermak Jun 5, 2026

Uh oh!

david-cermak Jun 5, 2026

Uh oh!

vikramdattu commented Jun 9, 2026 •

edited

Loading

Uh oh!

cursor Bot Jun 20, 2026

Uh oh!

vikramdattu commented Jul 14, 2026

Uh oh!

cursor Bot left a comment

Uh oh!

cursor Bot Jul 14, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

vikramdattu commented Jun 4, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Notes

Uh oh!

vikramdattu commented Jun 4, 2026

Uh oh!

david-cermak commented Jun 4, 2026

Uh oh!

vikramdattu Jun 4, 2026

Choose a reason for hiding this comment

Uh oh!

david-cermak Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

david-cermak Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

vikramdattu commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cursor Bot Jun 20, 2026

Choose a reason for hiding this comment

MBTLS v4 CMake cache stale

Uh oh!

vikramdattu commented Jul 14, 2026

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 14, 2026

Choose a reason for hiding this comment

CI ignore pattern quote mismatch

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vikramdattu commented Jun 4, 2026 •

edited by cursor Bot

Loading

vikramdattu commented Jun 9, 2026 •

edited

Loading