Skip to content

SD Card usermod: Adjust SPI configuration for ESP32-S3 support #5679

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
Will-wastelander wants to merge 18 commits into
base: main
Choose a base branch
from
+36 −7
Open

SD Card usermod: Adjust SPI configuration for ESP32-S3 support #5679

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
9dbe71c
Adjust SPI configuration for ESP32-S3 support
Will-wastelander Jun 14, 2026
11e3e9e
Make SD card pin configuration customizable
Will-wastelander Jun 15, 2026
80490a6
Update readme with SD card pin customization
Will-wastelander Jun 15, 2026
d38fd09
Improve formatting of SD card configuration code
Will-wastelander Jun 15, 2026
96f21c1
Added original comments back
Will-wastelander Jun 15, 2026
4920af2
Change SPI port from HSPI to FSPI for ESP32-S3
Will-wastelander Jun 15, 2026
c5d03af
Change pin configuration types from int8_t to uint8_t
Will-wastelander Jun 15, 2026
f6567cc
Update usermods/sd_card/sd_card.cpp
Will-wastelander Jun 15, 2026
ad21b1d
Merge branch 'main' into main
Will-wastelander Jun 16, 2026
9a9ab8b
Change SPI port from FSPI to HSPI for ESP32-S3
Will-wastelander Jun 18, 2026
4e17ff4
Change pin configuration types from uint8_t to int8_t
Will-wastelander Jun 20, 2026
9684c95
Update SPI configuration for SD card support
Will-wastelander Jun 20, 2026
951f362
Define SD card configuration pins if not defined
Will-wastelander Jun 20, 2026
9dc89db
Refactor SD card pin configuration logic
Will-wastelander Jun 20, 2026
b802162
Merge branch 'main' into main
Will-wastelander Jun 20, 2026
0a001f6
Merge branch 'main' into main
Will-wastelander Jun 20, 2026
3db59af
Fix macro definitions for SD card pin configurations
Will-wastelander Jun 20, 2026
e67f030
Add warning for SD card and Ethernet conflicts
Will-wastelander Jun 21, 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
1 change: 1 addition & 0 deletions usermods/sd_card/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@
- choose the way your SD is connected
1. via `-D WLED_USE_SD_MMC` when connected via MMC
2. via `-D WLED_USE_SD_SPI` when connected via SPI (use usermod page to setup SPI pins)
3. Customize pins with the following `-D UM_SD_SELECT=16 -D UM_SD_CLOCK=14 -D UM_SD_POCI=36 -D UM_SD_PICO=15`

### Test
- enable `-D SD_PRINT_HOME_DIR` and `-D WLED_DEBUG`
Expand Down
42 changes: 35 additions & 7 deletions usermods/sd_card/sd_card.cpp
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,9 +13,34 @@
#include "SPI.h"
#endif

#ifndef UM_SD_SELECT
#define UM_SD_SELECT 16;
#endif
#ifndef UM_SD_CLOCK
#define UM_SD_CLOCK 14;
#endif
#ifndef UM_SD_POCI
#define UM_SD_POCI 36;
#endif
#ifndef UM_SD_PICO
#define UM_SD_PICO 15;
#endif


#ifdef WLED_USE_SD_MMC
// SD_MMC configuration handled elsewhere
#elif defined(WLED_USE_SD_SPI)
SPIClass spiPort = SPIClass(VSPI);
#if defined(CONFIG_IDF_TARGET_ESP32S3)
// FSPI (SPI2) is the global SPI used by dotstar/2-pin LED drivers; use HSPI (SPI3) for SD
SPIClass spiPort = SPIClass(HSPI);
#elif defined(WLED_USE_ETHERNET)
#warning "SD card may have conflicts with ethernet."
// Ethernet builds: dotstar uses HSPI (SPI2), so SD uses VSPI (SPI3)
SPIClass spiPort = SPIClass(VSPI);

@softhack007 softhack007 Jun 21, 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 can remember that the reason for "dotstar uses HSPI (SPI2) with WLED_USE_ETHERNET" is that the other SPI unit (VSPI) is in use for ethernet already.

It might be useful to add a #warning compile-time message for this case, to warn users that SD card may have conflicts with ethernet.

@DedeHai DedeHai Jun 21, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

hm, so it may be best to always use HSPI as ethernet is probably more common than 2-pin LEDs and change the warning that 2-pin LEDs are in conflict with SD card.

#else
// Non-Ethernet classic ESP32: dotstar uses global SPI (VSPI/SPI3), so SD uses HSPI (SPI2)
SPIClass spiPort = SPIClass(HSPI);
#endif
#endif

void listDir( const char * dirname, uint8_t levels);
Expand All @@ -24,11 +49,14 @@ class UsermodSdCard : public Usermod {
private:
bool sdInitDone = false;

#ifdef WLED_USE_SD_SPI
int8_t configPinSourceSelect = 16;
int8_t configPinSourceClock = 14;
int8_t configPinPoci = 36; // confusing names? Then have a look :)
int8_t configPinPico = 15; // https://www.oshwa.org/a-resolution-to-redefine-spi-signal-names/
// confusing names? Then have a look
// https://oshwa.org/resources/a-resolution-to-redefine-spi-signal-names/
#ifdef WLED_USE_SD_SPI
int8_t configPinSourceSelect = UM_SD_SELECT;
int8_t configPinSourceClock = UM_SD_CLOCK;
int8_t configPinPoci = UM_SD_POCI;
int8_t configPinPico = UM_SD_PICO;
#endif

//acquired and initialize the SPI port
void init_SD_SPI()
Expand Down Expand Up @@ -241,4 +269,4 @@ void listDir( const char * dirname, uint8_t levels){
#endif

static UsermodSdCard sd_card;
REGISTER_USERMOD(sd_card);
REGISTER_USERMOD(sd_card);
Loading