-D HW_PIN_SCL/SDA do not work as expected

[Will-wastelander]

What happened?

When attempting to configure SDA and SCL pins using -D HW_PIN_SCL= -D HW_PIN_SDA=, the pins do not get configured.
However when using -D I2CSDAPIN= -D I2CSCLPIN= the pins are configured correctly.

To Reproduce Bug

Attempt to use -D HW_PIN_SCL= -D HW_PIN_SDA= to configure the pins.

Expected Behavior

Using -D HW_PIN_SCL= -D HW_PIN_SDA= configures pins the same that -D I2CSDAPIN= -D I2CSCLPIN= does.

Install Method

Self-Compiled

What version of WLED?

17.x-dev

Which microcontroller/board are you seeing the problem on?

ESP32-S3

Relevant log/trace output

Anything else?

No response

Code of Conduct

• I agree to follow this project's Code of Conduct

[Will-wastelander]

From platformio_override_sample.ini

; configure I2C and SPI interface (for various hardware)
;   -D I2CSDAPIN=33 # initialise interface
;   -D I2CSCLPIN=35 # initialise interface
;   -D HW_PIN_SCL=35
;   -D HW_PIN_SDA=33
;   -D HW_PIN_CLOCKSPI=7
;   -D HW_PIN_DATASPI=11
;   -D HW_PIN_MISOSPI=9

[DedeHai]

@coderabbitai when was this change of renaming the defines introduced?

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Find when HW_PIN_SDA and HW_PIN_SCL were introduced
git log --oneline --all -S 'HW_PIN_SDA' | head -20
echo "---"
git log --oneline --all -S 'HW_PIN_SCL' | head -20
echo "---"
git log --oneline --all -S 'HW_PIN_CLOCKSPI' | head -20

Length of output: 374

---

🏁 Script executed:

#!/bin/bash
# Use GitHub search for PRs/commits mentioning the rename
gh search commits 'HW_PIN_SDA repo:wled/WLED' --limit 10 2>/dev/null || true
echo "==="
gh search prs 'HW_PIN_SDA repo:wled/WLED' --limit 10 2>/dev/null || true
echo "==="
# Also try searching issues
gh search issues 'HW_PIN_SDA HW_PIN_SCL repo:wled/WLED' --limit 10 2>/dev/null || true

Length of output: 1485

---

🏁 Script executed:

#!/bin/bash
# Get details of PR `#2955` which seems to have introduced HW_PIN defines
gh pr view 2955 --repo wled/WLED --json title,body,mergedAt,author,url

Length of output: 1716

---

🏁 Script executed:

#!/bin/bash
# Search for PRs that renamed the defines
gh search prs 'HW_PIN_SCL I2CSCLPIN repo:wled/WLED' --limit 10 2>/dev/null || true
echo "==="
gh search prs 'rename I2C pin defines repo:wled/WLED' --limit 10 2>/dev/null || true
echo "==="
# Look at PR `#2955`'s files to understand what defines it used
gh pr view 2955 --repo wled/WLED --json files 2>/dev/null || true
echo "==="
# Search for any PR mentioning HW_PIN in title or body
gh search prs 'HW_PIN_SCL repo:wled/WLED' --limit 15 2>/dev/null || true

Length of output: 2404

---

🏁 Script executed:

#!/bin/bash
# Check current state of the defines in const.h
rg -n 'HW_PIN_S|I2CSDAPIN|I2CSCLPIN|SPIMOSIPIN|SPIMISOPIN|SPISCLKPIN' wled00/const.h wled00/wled.h 2>/dev/null || true
echo "==="
# Try lighter git log on just const.h (no -S, just filename)
git log --oneline wled00/const.h | head -30
echo "==="
git log --oneline wled00/wled.h | head -30

Length of output: 5532

---

🏁 Script executed:

#!/bin/bash
# Check PR `#5361` which "Add Pin Info"
gh pr view 5361 --repo wled/WLED --json title,body,mergedAt,author,url 2>/dev/null || true
echo "==="
# Check what files were changed and look at the commit
git show 43e86d0f --stat 2>/dev/null | head -20
echo "==="
# Also check the specific lines added around HW_PIN_SCL in that commit
git show 43e86d0f -- wled00/const.h 2>/dev/null | grep -A5 -B5 'HW_PIN_SCL\|HW_PIN_SDA\|HW_PIN_CLOCKSPI' | head -60

Length of output: 3018

---

🏁 Script executed:

#!/bin/bash
# Look at const.h git log more carefully - check each major commit for HW_PIN
git log --oneline wled00/const.h | head -40
echo "==="
# Check commit b7d2c3cd for HW_PIN defines
git show b7d2c3cd -- wled00/const.h 2>/dev/null | grep -A3 -B3 'HW_PIN' | head -40
echo "==="
# Check the HUB75 commit 3a7de827
git show 3a7de827 -- wled00/const.h 2>/dev/null | grep -A3 -B3 'HW_PIN' | head -40

Length of output: 3702

---

🏁 Script executed:

#!/bin/bash
# Check d1ed547a - "Improved bus handling"
git show d1ed547a -- wled00/const.h 2>/dev/null | grep -A3 -B3 'HW_PIN' | head -40
echo "==="
# Check the full list further back
git log --oneline wled00/const.h | tail -40
echo "==="
# Look at even older commits - check ee9ac947 "Segment layering"
git show ee9ac947 -- wled00/const.h 2>/dev/null | grep -A3 -B3 'HW_PIN' | head -40

Length of output: 2232

---

🏁 Script executed:

#!/bin/bash
# Find the exact commit that introduced HW_PIN defines in const.h
# by checking commits from oldest to newest in the log
commits=$(git log --oneline wled00/const.h | awk '{print $1}' | tac)
for c in $commits; do
  result=$(git show $c -- wled00/const.h 2>/dev/null | grep '^\+.*HW_PIN_SCL' | head -1)
  if [ -n "$result" ]; then
    echo "Found in commit: $c"
    git show $c --stat 2>/dev/null | head -5
    git show $c -- wled00/const.h 2>/dev/null | grep -A5 -B5 'HW_PIN' | head -40
    break
  fi
done

Length of output: 1620

---

---

@DedeHai, the HW_PIN_* defines were originally introduced in commit f0992d56 on July 7, 2022 by Blaz Kristan (blazoncek), with the message "Added global I2C & SPI HW pin defines". This predates PR #2955 (December 2022, by @ezcGman), which added the I2CSDAPIN/I2CSCLPIN/SPIMOSIPIN etc. style as build flags.

The current state in const.h bridges the two:

// const.h — maps old-style → HW_PIN_*
`#if` defined(I2CSCLPIN) && !defined(HW_PIN_SCL)
  `#define` HW_PIN_SCL I2CSCLPIN
`#if` defined(I2CSDAPIN) && !defined(HW_PIN_SDA)
  `#define` HW_PIN_SDA I2CSDAPIN

However, the actual hardware pin initialization in wled.h still uses the old names:

// wled.h — used for real initialization
WLED_GLOBAL int8_t i2c_sda  _INIT(I2CSDAPIN);
WLED_GLOBAL int8_t i2c_scl  _INIT(I2CSCLPIN);

This is likely the root cause of issue #5680: -D HW_PIN_SDA=33 only defines the informational HW_PIN_SDA macro (used by usermods), but wled.h still defaults i2c_sda from I2CSDAPIN, which is never set — so the actual I2C hardware pin doesn't change. The const.h mapping only goes in the other direction (old → new), not from HW_PIN_SDA back to I2CSDAPIN.

[blazoncek]

FYI this is not a bug but design choice.

HW_PIN_* macros are used as an informational shortcut and are intended to define which HW pins are connected to external I2C hardware.

I.e. some controllers feature dedicated I2C circuitry (which can be repurposed as a LED output in some cases) attached to certain pins.
If a user reconfigures such pins for something else these macros can be used to check if pin is still intended for I2C.

EDIT: If you want to define I2C pins at compile time use I2CS* macros.

[softhack007]

Originally HW_PIN_SDA / HW_PIN_SCL were meant as an information to the UI, so the pin-dropdowns and and other features know what are the default I2C pins on the board.

We later found out that any pin can be used for I2C, even on 8266 where rumors about "only pin 4/5 have hardware I2C support" were very strong, and actually were wrong 😅.

I2CSDAPIN/I2CSCLPIN are initializing the I2C driver with specific pins at startup, any change needs a reboot.
This is usually not what people should want, because there is a pin dropdown in the UI. Using fixed pins may be necessary if you have a special board with additional hardware that is wired to dedicated pins - for example an audio board where specific pins are hard-wired to the audio chip for I2C communications.

[blazoncek]

There are two things to consider. One is hardware wiring of external circuitry (e.g. OLED display, etc) on the controller PCB and the other is ESP's muxer component which can tie any GPIO to internal hardware component.

HW_PIN_* macros are the former and I2C*PIN are used for the latter. If the HW_PIN_* are missing they are assigned from I2C*PIN if they exist.
Their purpose is entirely informational and not used in any code (except UI, see xml.cpp).
This is also written as a comment in the source files.

For people building their controller PCB's using non standard GPIO layout HW_PIN_* macros can be used as a visual cue if their users reconfigure and forget original settings.

In short: If you need to compile custom version of WLED which is tailored for certain controller, use I2CSDAPIN & I2CSCLPIN which will set both macros (and you can ignore HW_PIN_*). However if your controller also supports LED output on GPIO used for I2C (i.e. DigBrain type of boards) and you want to preconfigure all GPIO to be LED outputs but still want to provide visual cue for users (in the UI) then use HW_PIN_* macros but do not use I2CSDAPIN or I2CSCLPIN.

[Will-wastelander]

The documentation shows to use those build flags when trying to define the pins. I am working on support for the Waveshare RGB Matrix driver board, and trying to get onboard hardware configured at build, rather than making the user have to configure everything.

If they are not meant to be used, should documentation be updated to correct this info ?