ESP32-S3 “SPIClass spi(HSPI)” but with pin definitions?

[Rob58329]

Board

"NodeMCU-32s" & "Firebeetle2 ESP32-3"

Device Description

Board connected to "Adafruit_ST7796S_kbv" tft (although not really relevant) using the HSPI .

Hardware Configuration

#define SD_CS 15
#define TFT_CS 33
#define TFT_DC 17
#define SPI_MISO 12 // default pin
#define SPI_MOSI 13 // default pin
#define SPI_CLK 14 // default pin
#define TFT_RST -1

Version

latest master (checkout manually)

IDE Name

Arduino IDE v1.8.19

Operating System

Windows 10

Flash frequency

n/a

PSRAM enabled

no

Upload speed

n/a

Description

The 1st below sketch works fine, but only with the default HSPI pin definitions.

#if CONFIG_IDF_TARGET_ESP32S3
    #define SD_CS    9 
    #define TFT_CS   18 
    #define TFT_DC   3 
    #define SPI_MOSI 15
    #define SPI_MISO 16
    #define SPI_CLK  17
    #define TFT_RST -1
#else
  #define SD_CS    15
  #define TFT_CS   33 
  #define TFT_DC   17 
  #define SPI_MISO 12 // default pin
  #define SPI_MOSI 13 // default pin
  #define SPI_CLK  14 // default pin
  #define TFT_RST -1
#endif
#define use_TFT true

#include <SPI.h>
#include <Adafruit_GFX.h>  // https://github.com/adafruit/Adafruit-GFX-Library 
#include <Adafruit_ST7796S_kbv.h> // https://github.com/prenticedavid/Adafruit_ST7796S_kbv1 

SPIClass MySPI(HSPI); // Declare an HSPI bus object (to use or BOTH TFT and SD-card)
Adafruit_ST7796S_kbv tft=Adafruit_ST7796S_kbv(&MySPI, TFT_DC, TFT_CS, TFT_RST);

#if (use_TFT)
  #define SerialD tft
#else
 #define SerialD Serial
#endif

void setup() {
  SerialD.begin();
  #if (use_TFT)
    tft.setRotation(3);
    tft.setTextSize(1); 
    tft.fillScreen(ST7796S_BLACK); tft.setCursor(0,0);
    tft.setTextColor(ST7796S_WHITE);
  #endif
} 

void loop() {
  SerialD.println("Loop");
  delay(1000);
}

The 2nd below sketch with new HSPI pin definitions compiles OK, but crashes at the line “SerialD.begin();” [aka tft.begin()]

#define SD_CS    15
#define TFT_CS   33 
#define TFT_DC   17 
#define SPI_MISO 12 // default pin
#define SPI_MOSI 13 // default pin
#define SPI_CLK  14 // default pin
#define TFT_RST -1

#define use_TFT true

#include <SPI.h>
#include <Adafruit_GFX.h>  // https://github.com/adafruit/Adafruit-GFX-Library 
#include <Adafruit_ST7796S_kbv.h> // https://github.com/prenticedavid/Adafruit_ST7796S_kbv1 

SPIClass *spi = NULL;
Adafruit_ST7796S_kbv tft=Adafruit_ST7796S_kbv(spi, TFT_DC, TFT_CS, TFT_RST);

#if (use_TFT)
  #define SerialD tft
#else
 #define SerialD Serial
#endif

void setup() {
  #if (use_TFT)
    spi = new SPIClass(HSPI);
    spi->begin(SPI_CLK, SPI_MISO, SPI_MOSI, TFT_CS);
  #endif
  SerialD.begin(); // crashes here
  #if (use_TFT)
    tft.setRotation(3);
    tft.setTextSize(1); 
    tft.fillScreen(ST7796S_BLACK); tft.setCursor(0,0);
    tft.setTextColor(ST7796S_WHITE);
  #endif
} 

void loop() {
  SerialD.println("Loop");
  delay(1000);
}

Is there any way to change the used HSPI pins outside of “setup()” and “loop()” so my above “#define SerialD tft” will work with “SerialD.print” etc?

Edit2:
@lbernstone - many thanks for below info! Interestingly the default "SPI" object "SPI.begin();" appears to use the pre-defined (SCK,MOSI, MISO,SS) variables, which on my board (nodeMCU-32S) are GPIO 18,23,19 & 5 which I understand to be the VSPI interface. But this still works fine.

The 3rd below sketch DOES work, and it a little more complex than sketch 1 above, but not too bad!

#define SD_CS    15
#define TFT_CS   33 
#define TFT_DC   17 
#define SPI_MISO 12 // default pin but can be changed
#define SPI_MOSI 13 // default pin but can be changed
#define SPI_CLK  14 // default pin but can be changed
#define TFT_RST -1

#define use_TFT true

#include <SPI.h>
#include <Adafruit_GFX.h>  // https://github.com/adafruit/Adafruit-GFX-Library 
#include <Adafruit_ST7796S_kbv.h> // https://github.com/prenticedavid/Adafruit_ST7796S_kbv1 

Adafruit_ST7796S_kbv *tft= NULL; 

#if (use_TFT)
  #define SerialD (*tft) // synonym for ->
#else
 #define SerialD Serial
#endif

void setup() {
  Serial.begin(115200);
  #if (use_TFT)
    // SPIClass *spi = new SPIClass(HSPI);  // not required as we can use the already existing "SPI"
    SPI.begin(SPI_CLK, SPI_MISO, SPI_MOSI, TFT_CS); // NB. SPI appears to use VSPI not HSPI, but this is ok.
    tft = new Adafruit_ST7796S_kbv(&SPI, TFT_DC, TFT_CS, TFT_RST); 
  #endif
  SerialD.begin(); 
  #if (use_TFT)
    tft->setRotation(3);
    tft->setTextSize(1); 
    tft->fillScreen(ST7796S_BLACK); tft->setCursor(0,0);
    tft->setTextColor(ST7796S_WHITE);
  #endif
} 

void loop() {
  SerialD.println("Loop");
  delay(1000);
}

Edit 3: re. ESP32-S3

Note that the ESP32-S3 has 2 available/user SPI controllers named:

• SPIClass(HSPI); or SPIClass(1); = GP-SPI2 (or perhaps GP-SPI3)
• SPIClass(FSPI); or SPIClass(0); = GP-SPI3 (or perhaps GP-SPI2)
  (each has slightly different capabilities).

Also note that although both above SPI controllers can be routed to any GPIO, for the fastest performance you can only use GPIOs 0-21 & 26-48 (which use the IO MUX to connect to the pins). Other pins use the GPIO MATRIX to connect to the pins and is slower.

Finally note that the SPI/TFT/SD (Arduino-ID) spi-frequency settings seem to work a bit differently on the ESP32-S3 (github.com/espressif/arduino-esp32 as at 16Jan24) compared with the ESP32-original. Specifically on the ESP32-original the following code works:

SPIClass *myspi = NULL;
Adafruit_ST7796S_kbv *tft = NULL;
myspi = new SPIClass(HSPI);
myspi->begin(SPI_CLK, SPI_MISO, SPI_MOSI, TFT_CS);
tft = new Adafruit_ST7796S_kbv(myspi, TFT_DC, TFT_CS, TFT_RST);
tft->begin();
boolean sd_OK = SD.begin(SD_CS, *myspi);

BUT on the ESP32-S3 the SD card gives the error message “sdCommand(): no token received” (I think because the SPI has ignored the default 10MHz setting for the SD card and is still using the default 40MHz setting of the TFT.)

To fix you need to specifically set the spi-frequency to the SD-cards default 10MHz frequency by changing the last couple of lines as follows:

#define SPI_freq 10000000 // 10MHz
tft->begin(SPI_freq);
boolean sd_OK =  SD.begin(SD_CS, MY_SPI, SPI_freq);

Sketch

See above

Debug Message

Sketch 2 crashes at the "SerialD.begin();"

I have checked existing issues, online documentation and the Troubleshooting Guide

• I confirm I have checked existing issues, online documentation and Troubleshooting guide.

[lbernstone]

HSPI is the default, and there is already an object (SPI) defined on that bus.

#include <SPI.h>
...
   SPI.begin(SPI_CLK, SPI_MISO, SPI_MOSI, TFT_CS);

If you want to use VSPI, you can do so like:

#include <SPI.h>
SPIClass vspi(1);
...
   vspi.begin(SPI_CLK, SPI_MISO, SPI_MOSI, TFT_CS);

[lbernstone]

Edit2: @lbernstone - many thanks for below info! Interestingly the default "SPI" object "SPI.begin();" appears to use the pre-defined (SCK,MOSI, MISO,SS) variables, which on my board (nodeMCU-32S) are GPIO 18,23,19 & 5 which I understand to be the VSPI interface. But this still works fine.

In arduino-esp32 context, SPI names are just names- HSPI evaluates to bus 2, and should be the horizontal pins (2,4,12,15), but that's just not how they are defined in the variants file. Since it is all muxed through the gpio matrix, that doesn't really matter (although a bit confusing). Espressif has gotten away from the H/V naming, since it doesn't really apply to the other variants, but it is kinda stuck in arduino to maintain backwards compatibility. If you are going to define your own objects, I'd stick to using the numbers

[eMUQI]

@lbernstone Hello, sorry to bother you. Thank you for your detailed explanations in previous discussions. I'd like to make a further inquiry regarding the SPI bus naming convention for ESP32-S3.

While researching SPI bus configuration, I noticed the following usage pattern:

SPIClass oledSPI(HSPI);
...
oledSPI.begin(OLED_SCK, -1, OLED_MOSI, OLED_CS);

At the same time, I noticed the following definitions in the current version (3.2.0) of esp32-hal-spi.h:

#ifdef CONFIG_IDF_TARGET_ESP32S2
#define FSPI 1  //SPI 1 bus. ESP32S2: for external memory only (can use the same data lines but different SS)
#define HSPI 2  //SPI 2 bus. ESP32S2: external memory or device  - it can be matrixed to any pins
#define SPI2 2  // Another name for ESP32S2 SPI 2
#define SPI3 3  //SPI 3 bus. ESP32S2: device only - it can be matrixed to any pins
#elif CONFIG_IDF_TARGET_ESP32
#define FSPI 1  //SPI 1 bus attached to the flash (can use the same data lines but different SS)
#define HSPI 2  //SPI 2 bus normally mapped to pins 12 - 15, but can be matrixed to any pins
#define VSPI 3  //SPI 3 bus normally attached to pins 5, 18, 19 and 23, but can be matrixed to any pins
#else
#define FSPI 0
#define HSPI 1
#endif

My question is: why doesn't ESP32-S3 have a VSPI definition? From my understanding, ESP32-S3 has 4 SPI buses, with SPI2 and SPI3 being available for users. Following the ESP32 naming convention, shouldn't these two buses correspond to HSPI and VSPI respectively?

I saw your previous comment that "Espressif has gotten away from the H/V naming, since it doesn't really apply to the other variants." Does this mean that for ESP32-S3, the official recommendation is to use HSPI uniformly (or use numeric IDs directly) to access user SPI buses?

Also, how should I specifically use SPI2 or SPI3 on ESP32-S3? Should it be:

• SPIClass spi2(HSPI); and SPIClass spi3(?);
• Or SPIClass spi2(1); and SPIClass spi3(2);
• Or something else?

@P-R-O-C-H-Y I noticed your recent changes in #11510 - would appreciate your thoughts on this naming convention question as well.

Looking forward to your guidance, thank you!

[Rob58329]

@eMUQI From the above:

Note that the ESP32-S3 has 2 available/user SPI controllers named:

    SPIClass(HSPI); or SPIClass(1); = GP-SPI2 (or perhaps GP-SPI3)
    SPIClass(FSPI); or SPIClass(0); = GP-SPI3 (or perhaps GP-SPI2)
    (each has slightly different capabilities).

You can use which ever naming convention makes most sence to you.