Pin the WLED sources a firmware image is built from

[PSi86]

Both workflows resolved the upstream ref themselves — "the latest published WLED release", read fresh on every run — and took the list of upstream pull requests to apply from a workflow_dispatch input that defaults to empty. Two things followed from that.

The rehearsal never rehearsed a release. Nothing passes wled_patch_prs on a push, so the compile-only build always ran unpatched: a tree no release has ever shipped. On the other side, a release carried wled/WLED#5521 only when whoever pressed the button remembered to type 5521. Miss it and nothing fails — the battery usermod exports no um_data, getUMData(USERMOD_ID_BATTERY) never succeeds, and the node ships reporting no battery state, because the lookup is retried rather than failed.

The unpinned ref is the larger one. Every build profile inherits its platform, toolchain and NeoPixelBus version from WLED's shared [esp32], [esp32s2], [esp32s3] and [esp32c3] sections, and on WLED's main those have already moved from ESP-IDF 4.4 to 5.5 (706 commits past v16.0.1, codename now "Kagayaki"). Unpinned, that toolchain switch — and whatever it means for the OTA images already in the field — arrives the day the next WLED release is published, with no commit here to point at.

What this changes

wled_source.json now names both, and the workflows read it:

{ "ref": "v16.0.1", "patch_prs": [5521] }

Pinned to what v0.1.14 shipped, so the merge itself changes no firmware. The inputs still override for a one-off run; what changed is that an empty input means "what the repository says" rather than "whatever upstream looks like right now", and asking for something else is explicit: latest for the newest published release, none for a stock tag.

• scripts/wled_source.py (new) — loads and validates the pin. An unknown key is an error rather than an ignored field: a misspelled one would otherwise be dropped in silence and build the default it was meant to change.
• resolve_wled_release.py — empty input falls through to the pin; latest still hits the releases API. --print repository no longer resolves a ref on the way to answering a constant, which saves an API call per run in the latest case.
• apply_wled_patches.py — same precedence, plus the none sentinel. Blank and "no patches" were previously the same string, which is exactly how #5521 went missing without anything failing.
• Both workflows — input descriptions and comments updated. The push/PR build now compiles the same tree a release does.

Notes

patch_prs carries wled/WLED#5521, which is still open upstream. wled/WLED#5399 rewrites the same file, and once it merges this patch stops applying — git apply is strict on purpose, so that surfaces as a failed build rather than a silently unpatched one. Decoupling from it is separate work; the pin file's notes records the dependency next to the number.

Testing

• Full suite green: 96 tests, 18 new in tests/test_wled_source.py covering validation and the input-over-pin precedence, plus guards that the committed ref is a tag (not a branch, not latest), that both workflows document the pin in their input descriptions, and that the readme's clone command cannot drift from it.
• resolve_wled_release.py with no input returns v16.0.1 without touching the network.
• Integrate um_data structure to battery usermod wled/WLED#5521 verified to still apply cleanly to v16.0.1 (git apply --check).
• The full patch-and-build path is what CI on this PR exercises; the sandbox this was written in gets a 403 from the unauthenticated GitHub API, so that step was verified by applying the same diff through git rather than end to end.

---

Generated by Claude Code