Skip to content

Remove inappropriate usermod environment changes #5720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
willmmiles wants to merge 5 commits into
base: main
Choose a base branch
from
+97 −118
Open

Remove inappropriate usermod environment changes #5720

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9e10f31
Revert bad usermod fixes
willmmiles Jul 6, 2026
a1fb347
CI: Build usermod environments with WLED_DEBUG
willmmiles Jul 6, 2026
4ab8de3
ci(usermods): fold custom-env builds into the standard build job
willmmiles Jul 6, 2026
ef39d68
Enable PWM_fan test build
willmmiles Jul 6, 2026
78df59c
CI: Fix injection vulnerability
willmmiles Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
144 changes: 40 additions & 104 deletions .github/workflows/usermods.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,41 +22,51 @@ jobs:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Get changed usermod environments
- name: Get changed usermod build matrix
id: envs
run: |
# Usermods whose directories changed in this PR
changed=$(git diff --name-only ${{ github.event.pull_request.base.sha }} HEAD \
| grep '^usermods/' | cut -d/ -f2 | sort -u || true)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

# All usermods with a library.json (excluding known-incompatible ones)
all=$(find usermods/ -name library.json \
| xargs dirname | xargs -n 1 basename \
| grep -v PWM_fan | grep -v BME68X_v2 | grep -v pixels_dice_tray \
| sort || true)
# Shared override defining the standard build environments
default_ini="usermods/platformio_override.usermods.ini"

if [ -z "$changed" ] || [ -z "$all" ]; then
echo "usermods=[]" >> $GITHUB_OUTPUT
else
usermods=$(comm -12 <(echo "$all") <(echo "$changed") | jq -R | jq --slurp -c)
echo "usermods=$usermods" >> $GITHUB_OUTPUT
fi
matrix='[]'
for mod in $changed; do
# Skip usermods known to be incompatible
case "$mod" in PWM_fan|BME68X_v2|pixels_dice_tray) continue ;; esac
# Only build usermods that ship a library.json
[ -f "usermods/$mod/library.json" ] || continue

# A usermod may provide its own build environments via a sample override;
# otherwise the standard environments from the shared override are used.
# Either way, the env list comes from the ini file rather than being
# duplicated here.
sample="usermods/$mod/platformio_override.ini.sample"
[ -f "$sample" ] && ini="$sample" || ini="$default_ini"
envs=$(grep -oE '^\[env:[^]]+\]' "$ini" | sed 's/^\[env:\(.*\)\]$/\1/')

for env in $envs; do
matrix=$(echo "$matrix" | jq --arg u "$mod" --arg e "$env" -c '. + [{usermod: $u, env: $e}]')
done
done
echo "matrix=$matrix" >> $GITHUB_OUTPUT
outputs:
usermods: ${{ steps.envs.outputs.usermods }}
matrix: ${{ steps.envs.outputs.matrix }}


build:
# Only run for pull requests from forks (not from branches within wled/WLED)
# Skip when no changed usermods were found (e.g. only non-library changes)
if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository && needs.get_usermod_envs.outputs.usermods != '[]'
name: Build Enviornments
# Skip when no buildable usermods were found (e.g. only non-library changes)
if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name != github.repository && needs.get_usermod_envs.outputs.matrix != '[]'
name: Build (${{ matrix.usermod }} / ${{ matrix.env }})
runs-on: ubuntu-latest
needs: get_usermod_envs
strategy:
fail-fast: false
matrix:
usermod: ${{ fromJSON(needs.get_usermod_envs.outputs.usermods) }}
environment: [usermods_esp32, usermods_esp32c3, usermods_esp32s2, usermods_esp32s3]
include: ${{ fromJSON(needs.get_usermod_envs.outputs.matrix) }}
steps:
- uses: actions/checkout@v4
- name: Set up Node.js
Expand All @@ -72,102 +82,28 @@ jobs:
~/.platformio/.cache
~/.buildcache
build_output
key: pio-${{ runner.os }}-${{ matrix.environment }}-${{ hashFiles('platformio.ini', 'pio-scripts/output_bins.py') }}-${{ hashFiles('wled00/**', 'usermods/**') }}
restore-keys: pio-${{ runner.os }}-${{ matrix.environment }}-${{ hashFiles('platformio.ini', 'pio-scripts/output_bins.py') }}-
key: pio-${{ runner.os }}-${{ matrix.env }}-${{ hashFiles('platformio.ini', 'pio-scripts/output_bins.py') }}-${{ hashFiles('wled00/**', 'usermods/**') }}
restore-keys: pio-${{ runner.os }}-${{ matrix.env }}-${{ hashFiles('platformio.ini', 'pio-scripts/output_bins.py') }}-
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
cache: 'pip'
- name: Install PlatformIO
run: pip install -r requirements.txt
- name: Add usermods environment
- name: Configure build environment
run: |
cp -v usermods/platformio_override.usermods.ini platformio_override.ini
echo >> platformio_override.ini
echo "custom_usermods = ${{ matrix.usermod }}" >> platformio_override.ini
cat platformio_override.ini

- name: Build firmware
run: pio run -e ${{ matrix.environment }}


get_custom_build_envs:
name: Gather Custom Build Environments
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Find usermods with custom build environments
id: custom_envs
run: |
# On PRs: only scan usermods whose directories changed.
# On push: scan all usermods (validates the full set on merge).
if [ "${{ github.event_name }}" = "pull_request" ]; then
changed=$(git diff --name-only ${{ github.event.pull_request.base.sha }} HEAD \
| grep '^usermods/' | cut -d/ -f2 | sort -u || true)
if [ -z "$changed" ]; then
echo "matrix=[]" >> $GITHUB_OUTPUT
exit 0
fi
samples=$(for mod in $changed; do
f="usermods/$mod/platformio_override.ini.sample"
[ -f "$f" ] && echo "$f"
done | sort)
# Use the usermod's own override when it provides one, otherwise apply
# the shared usermods override with this usermod enabled.
sample="usermods/${{ matrix.usermod }}/platformio_override.ini.sample"
if [ -f "$sample" ]; then
cp -v "$sample" platformio_override.ini
else
samples=$(find usermods/ -name "platformio_override.ini.sample" | sort)
cp -v usermods/platformio_override.usermods.ini platformio_override.ini
echo >> platformio_override.ini
echo "custom_usermods = ${{ matrix.usermod }}" >> platformio_override.ini
fi
cat platformio_override.ini

result='[]'
for sample in $samples; do
usermod=$(dirname "$sample" | xargs basename)
# Skip usermods known to be incompatible (same list as get_usermod_envs)
case "$usermod" in PWM_fan|BME68X_v2|pixels_dice_tray) continue ;; esac
envs=$(grep -E '^\[env:[^]]+\]' "$sample" | sed 's/^\[env:\(.*\)\]$/\1/')
for env in $envs; do
result=$(echo "$result" | jq --arg u "$usermod" --arg e "$env" '. + [{usermod: $u, env: $e}]')
done
done
echo "matrix=$(echo "$result" | jq -c '.')" >> $GITHUB_OUTPUT
outputs:
matrix: ${{ steps.custom_envs.outputs.matrix }}


build_custom:
name: Build Custom Env (${{ matrix.usermod }} / ${{ matrix.env }})
runs-on: ubuntu-latest
needs: get_custom_build_envs
if: needs.get_custom_build_envs.outputs.matrix != '[]'
strategy:
fail-fast: false
matrix:
include: ${{ fromJSON(needs.get_custom_build_envs.outputs.matrix) }}
steps:
- uses: actions/checkout@v4
- name: Set up Node.js
uses: actions/setup-node@v4
with:
node-version-file: '.nvmrc'
cache: 'npm'
- run: npm ci
- name: Cache PlatformIO
uses: actions/cache@v4
with:
path: |
~/.platformio/.cache
~/.buildcache
build_output
key: pio-${{ runner.os }}-${{ matrix.env }}-${{ hashFiles('platformio.ini', 'pio-scripts/output_bins.py') }}-${{ hashFiles('wled00/**', 'usermods/**') }}
restore-keys: pio-${{ runner.os }}-${{ matrix.env }}-${{ hashFiles('platformio.ini', 'pio-scripts/output_bins.py') }}-
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
cache: 'pip'
- name: Install PlatformIO
run: pip install -r requirements.txt
- name: Apply custom build environment
run: cp -v "usermods/${{ matrix.usermod }}/platformio_override.ini.sample" platformio_override.ini
- name: Build firmware
run: pio run -e ${{ matrix.env }}

@coderabbitai coderabbitai Bot Jul 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔒 Security & Privacy | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

set -euo pipefail
wc -l .github/workflows/usermods.yml
cat -n .github/workflows/usermods.yml | sed -n '1,180p'

Repository: wled/WLED

Length of output: 5058

🏁 Script executed:

set -euo pipefail
grep -nE '^(on:|permissions:|- name:|run:|matrix:|grep -oE|custom_usermods|pio run -e)' .github/workflows/usermods.yml

Repository: wled/WLED

Length of output: 153

🏁 Script executed:

set -euo pipefail
wc -l .github/workflows/usermods.yml
cat -n .github/workflows/usermods.yml | sed -n '1,180p'
grep -nE '^(on:|permissions:|- name:|run:|matrix:|grep -oE|custom_usermods|pio run -e)' .github/workflows/usermods.yml

Repository: wled/WLED

Length of output: 5064

Quote the matrix values before using them in shell

matrix.usermod and matrix.env are interpolated directly into run: scripts. A fork can supply shell metacharacters through a changed usermod path or platformio_override.ini.sample, which turns into command execution on the runner. Move both values into env: and quote them, and restrict extracted env names to a safe pattern like ^[A-Za-z0-9_-]+$.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.github/workflows/usermods.yml around lines 98 - 109, The shell steps in the
usermods workflow are using matrix.usermod and matrix.env directly in run
commands, which can allow shell injection; update the workflow so these matrix
values are passed through env variables and always quoted before use. In the
same job, tighten the usermod/env handling around the sample copy and pio run
steps, and add validation for the extracted env name in the Build firmware step
using a safe pattern such as ^[A-Za-z0-9_-]+$ before invoking pio.

Source: Path instructions

@willmmiles willmmiles Jul 6, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this new to the PR, or was the previous logic also vulnerable?

@coderabbitai coderabbitai Bot Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
cd /tmp
gh pr view 5720 --repo wled/WLED --json baseRefOid,headRefOid,baseRefName,headRefName
gh api repos/wled/WLED/contents/.github/workflows/usermods.yml?ref=$(gh pr view 5720 --repo wled/WLED --json baseRefOid --jq .baseRefOid) --jq .content | base64 -d > usermods_base.yml
grep -nE 'matrix\.(usermod|env|environment)' usermods_base.yml

Length of output: 1655

@willmmiles Good question — I checked the base commit (bc2c80d, pre-PR main) and the same pattern already existed there:

88:        echo  "custom_usermods = ${{ matrix.usermod }}" >> platformio_override.ini
92:      run: pio run -e ${{ matrix.environment }}
...
171:      run: cp -v "usermods/${{ matrix.usermod }}/platformio_override.ini.sample" platformio_override.ini
173:      run: pio run -e ${{ matrix.env }}

So this isn't new to your PR — the previous logic (both the build and build_custom jobs) already interpolated matrix.usermod/matrix.environment/matrix.env directly into run: steps without quoting or env: indirection. Your change just renamed matrix.environment to matrix.env and merged the two jobs, carrying the same pattern forward.

That said, worth noting the practical exposure is bounded here: this workflow only runs for pull_request events where head.repo.full_name != github.repository (i.e., fork PRs), and the usermod/env values are derived from directory names and [env:...] section names in files under usermods/, not from arbitrary free-text PR input — so exploitability would require a crafted usermod directory name or ini section name in the fork's own changed files. Still, hardening this (passing values via env: and validating with ^[A-Za-z0-9_-]+$) is a reasonable follow-up given it touches fork-triggered CI.

Since this predates your PR, I won't hold up this PR on it — happy to open a separate tracking issue if you'd like.

🧠 Learnings used 
Learnt from: softhack007
Repo: wled/WLED PR: 5480
File: .github/copilot-instructions.md:73-73
Timestamp: 2026-04-05T23:41:30.189Z
Learning: When reviewing the repository’s `.github/` directory (any files under `.github/`), treat the literal filesystem path segment `.github/` as **mandatory lowercase**. If static analysis tools suggest changing `.github/workflows/...` (or similar `.github/...` paths) from `github` to `GitHub`, mark that suggestion as a false positive and do **not** recommend changing the casing in filesystem paths, code, docs, or references to those paths.

@softhack007 softhack007 Jul 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's still worth to check if the vulnerability gap can be closed with a few changes. Even when it predates this PR (so no regression).

@coderabbitai coderabbitai Bot Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

@willmmiles willmmiles Jul 6, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No objections from me! The changes seem reasonably achievable. I just wanted to be sure it wasn't something I'd done inadvertently - I'm not an expert in Github Actions - and I would like to move quickly on this PR as I consider it important.

FWIW, CodeRabbit has been doing this to me a lot lately. I've been using to check some of my in-progress work before opening a PR, and it keeps finding bugs like this around areas I've been working that have always been there but could really use attention. Makes for better code, but it sure seems like a drag on getting things done... ;)

@softhack007 softhack007 Jul 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep, I was hoping that CodeRabbit would start to highlight such improvement opportunities with all the rules I've added to its database.

Especially for code robustness and "cyber security", I think we've collected a lot of technical debt that might "fall onto our feet" one day. I think it's good to spend more time if that makes our codebase better - even at the price of "reducing feature delivery speed" (not sure if my wording makes sense in english ;) ).

I've experienced this in my day job, too: "clean up the module while you work on it" does pay back in terms of quality, even when it's sometimes conflicting with the intuition of "don't fix stuff that's not (proven to be) broken".

2 changes: 1 addition & 1 deletion platformio.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -714,7 +714,7 @@ build_flags = ${common.build_flags} ${esp32s2.build_flags} -D WLED_RELEASE_NAME=
[env:usermods]
extends = env:esp32dev
build_flags = ${common.build_flags} ${esp32_idf_V4.build_flags} -D WLED_RELEASE_NAME=\"ESP32_USERMODS\"
-DTOUCH_CS=9 -DWLED_USE_SD_SPI ;; help a few usermods that require special flags to compile
-DTOUCH_CS=9

@coderabbitai coderabbitai Bot Jul 6, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== platformio.ini line count =="
wc -l platformio.ini

echo
echo "== around referenced line 717 =="
nl -ba platformio.ini | sed -n '690,740p'

echo
echo "== all TOUCH_CS occurrences =="
rg -n "TOUCH_CS|custom_usermods|\\[env:usermods\\]|\\[env:" platformio.ini

echo
echo "== env headers around usermods =="
python3 - <<'PY'
from pathlib import Path
text = Path('platformio.ini').read_text().splitlines()
for i, line in enumerate(text, 1):
    if line.strip().startswith('[env:') or 'TOUCH_CS' in line or 'custom_usermods' in line:
        start = max(1, i-3)
        end = min(len(text), i+3)
        print(f"\n--- lines {start}-{end} ---")
        for j in range(start, end+1):
            print(f"{j:4d}: {text[j-1]}")
PY

Repository: wled/WLED

Length of output: 272

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== platformio.ini context around TOUCH_CS =="
nl -ba platformio.ini | sed -n '700,730p'

echo
echo "== all env headers and custom_usermods references =="
rg -n "^\[env:|custom_usermods|TOUCH_CS" platformio.ini

echo
echo "== nearby override envs if present =="
python3 - <<'PY'
from pathlib import Path
lines = Path('platformio.ini').read_text().splitlines()
for i, line in enumerate(lines, 1):
    if line.strip().startswith('[env:') and ('usermods' in line.lower() or 'override' in line.lower() or 'touch' in line.lower()):
        start = max(1, i-2)
        end = min(len(lines), i+18)
        print(f"\n--- {i}: {line} ---")
        for j in range(start, end+1):
            print(f"{j:4d}: {lines[j-1]}")
PY

Repository: wled/WLED

Length of output: 232

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo "== lines 700-730 with line numbers =="
awk 'NR>=700 && NR<=730 { printf "%4d: %s\n", NR, $0 }' platformio.ini

echo
echo "== all occurrences of TOUCH_CS, custom_usermods, and relevant env headers =="
python3 - <<'PY'
from pathlib import Path
lines = Path('platformio.ini').read_text().splitlines()
for i, line in enumerate(lines, 1):
    if 'TOUCH_CS' in line or 'custom_usermods' in line or line.strip().startswith('[env:'):
        print(f"{i:4d}: {line}")
PY

echo
echo "== locate [env:usermods] block =="
python3 - <<'PY'
from pathlib import Path
lines = Path('platformio.ini').read_text().splitlines()
start = None
for i, line in enumerate(lines, 1):
    if line.strip() == '[env:usermods]':
        start = i
        break
if start is None:
    print("missing [env:usermods]")
    raise SystemExit(0)
end = len(lines)
for j in range(start + 1, len(lines) + 1):
    if lines[j-1].startswith('[env:') and j != start:
        end = j - 1
        break
for j in range(start, min(end, start + 40) + 1):
    print(f"{j:4d}: {lines[j-1]}")
PY

Repository: wled/WLED

Length of output: 5366

Keep [env:usermods] generic.
TOUCH_CS=9 in [env:usermods] forces every custom_usermods = * build to inherit the same touch pin. Move it to the specific env that needs it so usermods with different wiring don't pick up the wrong default.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@platformio.ini` at line 717, The generic [env:usermods] configuration is
leaking a touch pin default into every custom_usermods build. Remove TOUCH_CS
from the shared usermods env and move it into the specific environment that
actually needs that wiring, using the relevant env block in platformio.ini so
other usermods can define their own pin settings.

Source: Path instructions

@softhack007 softhack007 Jul 6, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@willmmiles -DTOUCH_CS=9 is actually an older "workaround" for making TFT_eSPI based usermods compile in the CI workflow. Not sure if we should keep this flag?

@coderabbitai coderabbitai Bot Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail
rg -n "TOUCH_CS" --type=cpp --type=ini -g '*.ini' -g '*.h' -g '*.cpp' . || true
rg -n "TOUCH_CS" .

Length of output: 331

@softhack007, I searched the repo and TOUCH_CS appears only in platformio.ini (Line 717) — it's not referenced anywhere in the WLED core .cpp/.h sources. That confirms it's purely a compile-time define consumed by an external library's config (likely TFT_eSPI's User_Setup.h/pin-select macros), not something WLED itself depends on.

Given that, and consistent with this PR's stated goal of keeping the shared [env:usermods] environment free of usermod-specific flags:

  • If there's currently no usermod in-tree that still needs TOUCH_CS=9 to compile in CI, it's probably safe to drop it entirely from [env:usermods].
  • If some TFT_eSPI-based usermod does still need it, it should move into that usermod's own platformio_override.ini.sample (the same pattern being introduced for WLED_USE_SD_SPI/SD_Card and PWM_fan in this PR), rather than leaking a pin default into every custom_usermods = * build.

I'll leave the final call to you/willmmiles since you have more context on which usermods currently rely on this workaround in CI.

🧠 Learnings used 
Learnt from: netmindz
Repo: wled/WLED PR: 5311
File: platformio.ini:395-395
Timestamp: 2026-01-31T18:19:28.320Z
Learning: In platformio.ini for WLED, understand that usermods can be pulled as out-of-tree dependencies via lib_deps (external repositories). The custom_usermods setting controls only in-tree usermods; setting custom_usermods =  (empty) disables in-tree usermods but does not disable out-of-tree usermods included through library dependencies.

Learnt from: softhack007
Repo: wled/WLED PR: 5048
File: platformio.ini:486-491
Timestamp: 2026-02-10T13:52:36.924Z
Learning: In PlatformIO projects, prefer using build_unflags in the PlatformIO configuration to remove inherited -D defines rather than using GCC's -U option. The -U approach is order-dependent and may be unreliable if the build command order is not guaranteed by PlatformIO. Use build_unflags in platformio.ini to explicitly remove inherited build flags for more robust and maintainable builds.

Learnt from: softhack007
Repo: wled/WLED PR: 5456
File: platformio.ini:788-850
Timestamp: 2026-03-31T13:31:01.488Z
Learning: For PlatformIO projects using `platform = pioarduino/platform-espressif32` with dual frameworks (`framework = arduino, espidf`), do not require an explicit `board_build.sdkconfig = sdkconfig.<env_name>` setting. `sdkconfig.<env_name>` (e.g., `sdkconfig.esp32s3_matter_wifi`) is a per-environment build artifact generated by pioarduino from merged board defaults plus the project-root `sdkconfig.defaults`. The project-root `sdkconfig.defaults` is automatically loaded by ESP-IDF’s CMake build, so the absence of `board_build.sdkconfig` should not be flagged as a missing configuration.

Learnt from: softhack007
Repo: wled/WLED PR: 5456
File: platformio.ini:788-850
Timestamp: 2026-03-31T13:31:01.488Z
Learning: For PlatformIO projects using `pioarduino/platform-espressif32` with dual framework (`framework = arduino, espidf`), treat `sdkconfig.<env_name>` (e.g., `sdkconfig.esp32s3_matter_wifi`) as a per-environment build artifact generated in the project root. PlatformIO will create it from `sdkconfig.defaults` on first build if it doesn’t exist, and will reuse the existing file on subsequent builds. In code review, do not recommend setting `board_build.sdkconfig = sdkconfig.<env_name>` because that file is an output, not required input. Only use `board_build.cmake_extra_args = -DSDKCONFIG_DEFAULTS=...` to select different defaults files when different environments truly need different SDK config defaults. As a sanity check, if `sdkconfig.<env_name>` is deleted and a rebuild regenerates it with the same content, that indicates `sdkconfig.defaults` is the correct source of truth.

Learnt from: netmindz
Repo: wled/WLED PR: 5543
File: platformio.ini:133-136
Timestamp: 2026-04-26T09:03:12.551Z
Learning: For WLED platformio.ini files: do not mark the audioreactive usermod as “unsupported” for ESP8266 build environments. While ESP8266 can’t process audio locally, it may still receive audioreactive sync data over the network (e.g., from an ESP32 or other source), so the outdated readme note about “ESP8266 is not supported” should be interpreted as only local audio processing. Reviewers should allow audioreactive to be included in ESP8266 environments in platformio.ini when network sync-receive is being used.

Learnt from: softhack007
Repo: wled/WLED PR: 5692
File: platformio.ini:798-799
Timestamp: 2026-06-20T15:08:04.789Z
Learning: For PlatformIO INI files, validate variable interpolation syntax as `${section_name.variable}` where `section_name` is the exact literal section header text (including any `env:` prefix for build environments like `[env:some_name]`). This refers to INI section data, not OS/system environment variables. Therefore, `${env:some_name.variable}` is correct for values in `[env:some_name]` (e.g., `${env:esp32S3_wroom2_32MB.build_unflags}` references `build_unflags` from that `[env:esp32S3_wroom2_32MB]` section); do not flag it as incorrect interpolation.

@willmmiles willmmiles Jul 6, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think it's actually necessary. TFT_eSPI generates warnings to indicate that the touch subsystem is disabled without it, but that's normal and expected if you don't actually have a touch screen!

I'm almost done the PR for the TFT_eSPI shim anyways. It's been another one where CodeRabbit has been pretty good at finding issues before I push. ;)

@coderabbitai coderabbitai Bot Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like the humans are having a chat. I'll hop back into my burrow for now. If you need me again, just tag @coderabbitai in a new comment, and I'll come hopping out!

custom_usermods = * ; Expands to all usermods in usermods folder
board_build.partitions = ${esp32.extreme_partitions} ; We're gonna need a bigger boat

Expand Down
13 changes: 4 additions & 9 deletions usermods/platformio_override.usermods.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,36 +3,31 @@ default_envs = usermods_esp32, usermods_esp32c3, usermods_esp32s2, usermods_esp3

[env:usermods_esp32]
extends = env:esp32dev
build_flags = ${env:esp32dev.build_flags}
-DTOUCH_CS=9 -D WLED_USE_SD_SPI ;; help a few usermods that require special flags to compile
custom_usermods = ${usermods.custom_usermods}
board_build.partitions = ${esp32.extreme_partitions} ; We're gonna need a bigger boat
build_flags = ${env:esp32dev.build_flags} -D WLED_DEBUG


[env:usermods_esp32c3]
extends = env:esp32c3dev
build_flags = ${env:esp32c3dev.build_flags}
-DTOUCH_CS=9 -D WLED_USE_SD_SPI ;; help a few usermods that require special flags to compile
board = esp32-c3-devkitm-1
custom_usermods = ${usermods.custom_usermods}
board_build.partitions = ${esp32.extreme_partitions} ; We're gonna need a bigger boat
build_flags = ${env:esp32c3dev.build_flags} -D WLED_DEBUG


[env:usermods_esp32s2]
extends = env:lolin_s2_mini
build_flags = ${env:lolin_s2_mini.build_flags}
-DTOUCH_CS=9 -D WLED_USE_SD_SPI ;; help a few usermods that require special flags to compile
custom_usermods = ${usermods.custom_usermods}
board_build.partitions = ${esp32.extreme_partitions} ; We're gonna need a bigger boat
build_flags = ${env:lolin_s2_mini.build_flags} -D WLED_DEBUG


[env:usermods_esp32s3]
extends = env:esp32s3dev_16MB_opi
build_flags = ${env:esp32s3dev_16MB_opi.build_flags}
-DTOUCH_CS=9 -D WLED_USE_SD_SPI ;; help a few usermods that require special flags to compile
-D WLED_DEBUG ;; try to catch broken DEBUG_PRINT statements
custom_usermods = ${usermods.custom_usermods}
board_build.partitions = ${esp32.extreme_partitions} ; We're gonna need a bigger boat
build_flags = ${env:esp32s3dev_16MB_opi.build_flags} -D WLED_DEBUG



Expand Down
Loading