Help with support for ESP32-S3 Dev Module

Hi, I’m new to development with PlatformIO and am currently working on a project using the Waveshare ESP32-S3-Touch-LCD-1.28 Devolopment Module. The board currently isnt available in the Espressif boards section and I’d like to get some help creating a .json file for the same. The hardware specifications of the board can be found on the above link.

Currently I tried making a .json file for the board by referring the files for other boards available on the github page. However there are a bunch of fields that I am unaware of and need guidance to figure out.

Here’s what I have written so far:

  "build": {
      "ldscript": "esp32s3_out.ld",
      "memory_type": ""
      "partitions": ""
    "core": "esp32",
    "extra_flags": [
    "f_cpu": "240000000L",
    "f_flash": "80000000L",
    "flash_mode": "qio",
    "hwids": [
    "mcu": "esp32s3",
    "variant": "esp32s3r2"
  "connectivity": [
  "debug": {
    "default_tool": "esp-builtin",
    "onboard_tools": [
    "openocd_target": "esp32s3.cfg"
  "frameworks": [
  "name": "Waveshare ESP32-S3-Touch-LCD-1.28 (16 MB QD, 2MB PSRAM)",
  "upload": {
    "flash_size": "16MB",
    "maximum_ram_size": ,
    "maximum_size": 16777216,
    "require_upload_port": true,
    "speed": 921600
  "url": "",
  "vendor": "Waveshare"

I’d appreciate it if someone with experience in adding support for a custom board could review the code, especially the blank fields and tell me how I could go about getting this done.

Note: The board is currently supported(and perfectly functional) on the Arduino IDE, where we simply put

in the Additional board managers url, install the ESP32 board in boards manager and then select the ESP32S3 Dev Module.

You’ll be facing multiple issues.

The first being, that the variant for “Waveshare ESP32S3 Touch LCD 128” was only added in Arduino-ESP32 3.x, while PlatformIO operates on Arduino-ESP32 2.0.16. So, you would have to do a framework update, too. See

for that.

This should also be reflected in the choice for variant in your board file.

Next, the settings

The settings in the arduino object are handled by the Arduino-ESP32 builder script.

Specifically, the memory_type being used here

Selects one of these memory configuration folders according to <flash_mode_<psram_type>.


You should use the same value that the boards.txt selects for the board.

Thus that would be dio_qspi.The board is capable of qio_qspi as well, reading the list of supported flash modes. QIO would yield faster flash access.

The “partitions” setting is the default partition scheme. That can be changed by the user later anyways. The boards.txt again gives the default value as literally

Which references the default.csv partition table. So the value should be default.csv, given the new partiiton tables of the Arduino-ESP32 3.x core.

Hardware-IDs are pairs of USB VID and PID which are unique to your dev board. It’s used to automatically select the right serial port for, e.g., uploading and monitoring. The boards.txt again tells you the values for it.

This is an array so there can me multiple of them. But an array of length 1 is fine, too.

More things you’ve missed:

Filling out the macros for USB CDC on boot:

Which would be


And the

      "maximum_ram_size": 327680,

As taken from

So all in all, I would suggest this board.json / project:

1 Like

Thanks for your help, Ill look into it according to the guidelines you have given once again. Appreciate it!

Hi @maxgerhardt,

So I cloned your repo and tried uploading my code through it.

I used a code from the File → Examples → (Example codes for ESP32S3 Dev Module) → ESP32-> ChipID → GetChipID available in the Arduino IDE and wrote it in the main.cpp file. The code runs perfectly fine on my board on the Arduino IDE and shows the appropriate results on the serial monitor. Heres the code for your reference:

#include <Arduino.h>

/* The true ESP32 chip ID is essentially its MAC address.
This sketch provides an alternate chip ID that matches
the output of the ESP.getChipId() function on ESP8266
(i.e. a 32-bit integer matching the last 3 bytes of
the MAC address. This is less unique than the
MAC address chip ID, but is helpful when you need
an identifier that can be no more than a 32-bit integer
(like for

created 2020-06-07 by cweinhofer
with help from Cicicok */

uint32_t chipId = 0;

void setup() {

void loop() {
  for (int i = 0; i < 17; i = i + 8) {
    chipId |= ((ESP.getEfuseMac() >> (40 - i)) & 0xff) << i;

  Serial.printf("ESP32 Chip model = %s Rev %d\n", ESP.getChipModel(), ESP.getChipRevision());
  Serial.printf("This chip has %d cores\n", ESP.getChipCores());
  Serial.print("Chip ID: ");


The result generated by this code in the serial monitor of the Arduino IDE is as follows:

ESP32 Chip model = ESP32-S3 Rev 1
This chip has 2 cores
Chip ID: 15749028
ESP32 Chip model = ESP32-S3 Rev 1
This chip has 2 cores
Chip ID: 15749028

However when I write the same code on the plaform created by you on PlatformIO it compiles and uploads to the board successfully, however nothing is displayed on the serial monitor. There are no errors or warnings generated, just an empty serial monitor apart from the usual stuff thats written.

 *  Executing task: platformio run --target upload --upload-port /dev/ttyACM0 

Processing waveshare_esp32s3_touch_lcd_128 (platform: espressif32; board: waveshare_esp32s3_touch_lcd_128; framework: arduino)
Verbose mode can be enabled via `-v, --verbose` option
PLATFORM: Espressif 32 (6.7.0) > Waveshare ESP32-S3-Touch-LCD-1.28 (16 MB QD, 2MB PSRAM)
HARDWARE: ESP32S3 240MHz, 320KB RAM, 16MB Flash
DEBUG: Current (esp-builtin) On-board (esp-builtin) External (cmsis-dap, esp-bridge, esp-prog, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa)
 - framework-arduinoespressif32 @ 3.0.1+sha.cc50d90 
 - framework-arduinoespressif32-libs @ 5.1.0+sha.442a798083 
 - tool-esptoolpy @ 1.40501.0 (4.5.1) 
 - tool-mkfatfs @ 2.0.1 
 - tool-mklittlefs @ 1.203.210628 (2.3) 
 - tool-mkspiffs @ 2.230.0 (2.30) 
 - toolchain-riscv32-esp @ 12.2.0+20230208 
 - toolchain-xtensa-esp32s3 @ 12.2.0+20230208
LDF: Library Dependency Finder ->
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 38 compatible libraries
Scanning dependencies...
No dependencies
Building in release mode
Retrieving maximum program size .pio/build/waveshare_esp32s3_touch_lcd_128/firmware.elf
Checking size .pio/build/waveshare_esp32s3_touch_lcd_128/firmware.elf
Advanced Memory Usage is available via "PlatformIO Home > Project Inspect"
RAM:   [          ]   4.3% (used 14196 bytes from 327680 bytes)
Flash: [==        ]  21.0% (used 275113 bytes from 1310720 bytes)
Configuring upload protocol...
AVAILABLE: cmsis-dap, esp-bridge, esp-builtin, esp-prog, espota, esptool, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa
CURRENT: upload_protocol = esptool
Looking for upload port...
Using manually specified: /dev/ttyACM0
Uploading .pio/build/waveshare_esp32s3_touch_lcd_128/firmware.bin v4.5.1
Serial port /dev/ttyACM0
Chip is ESP32-S3 (revision v0.1)
Features: WiFi, BLE
Crystal is 40MHz
MAC: 7c:df:a1:f0:4f:a4
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600
Configuring flash size...
Flash will be erased from 0x00000000 to 0x00003fff...
Flash will be erased from 0x00008000 to 0x00008fff...
Flash will be erased from 0x0000e000 to 0x0000ffff...
Flash will be erased from 0x00010000 to 0x00053fff...
Compressed 14880 bytes to 10566...
Writing at 0x00000000... (100 %)
Wrote 14880 bytes (10566 compressed) at 0x00000000 in 0.4 seconds (effective 298.8 kbit/s)...
Hash of data verified.
Compressed 3072 bytes to 146...
Writing at 0x00008000... (100 %)
Wrote 3072 bytes (146 compressed) at 0x00008000 in 0.1 seconds (effective 337.4 kbit/s)...
Hash of data verified.
Compressed 8192 bytes to 47...
Writing at 0x0000e000... (100 %)
Wrote 8192 bytes (47 compressed) at 0x0000e000 in 0.1 seconds (effective 448.0 kbit/s)...
Hash of data verified.
Compressed 275472 bytes to 153892...
Writing at 0x00010000... (10 %)
Writing at 0x0001bb41... (20 %)
Writing at 0x00024796... (30 %)
Writing at 0x00029f57... (40 %)
Writing at 0x0002f34e... (50 %)
Writing at 0x000349f3... (60 %)
Writing at 0x0003d55b... (70 %)
Writing at 0x00045f30... (80 %)
Writing at 0x0004b6d8... (90 %)
Writing at 0x00050f07... (100 %)
Wrote 275472 bytes (153892 compressed) at 0x00010000 in 3.6 seconds (effective 605.3 kbit/s)...
Hash of data verified.

Hard resetting via RTS pin...
============================================================================ [SUCCESS] Took 7.47 seconds ============================================================================
 *  Terminal will be reused by tasks, press any key to close it. 

Serial Monitor

*  Executing task: platformio device monitor --port /dev/ttyACM0 

--- Terminal on /dev/ttyACM0 | 115200 8-N-1
--- Available filters and text transformations: colorize, debug, default, direct, esp32_exception_decoder, hexlify, log2file, nocontrol, printable, send_on_enter, time
--- More details at
--- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H

The only change I made to your project was passing the baudrate argument for the serial monitor parameter in the platform.ini file.

; PlatformIO Project Configuration File


; Build options: build flags, source filter

; Upload options: custom upload port, speed and extra flags

; Library options: dependencies, extra library storages

; Advanced options: extra scripting


; Please visit documentation for the other options and examples



platform = espressif32

board = waveshare_esp32s3_touch_lcd_128

framework = arduino

monitor_speed = 115200


framework-arduinoespressif32 @

framework-arduinoespressif32-libs @

I waited for all platform updates to occur that started when I initially used your project platform before writing or uploading any code.
Please let me know if you have any idea as to what might be causing this issue. Thank you for your time.

Mhm. This could be a multitude of things.

  • Boot fails completely
  • only USB serial / CDC broken
  • wrong monitor settings

Can you upload a blink LED sketch and see if it blinks it successfully? Then it can’t be a boot problem.

Another thing to try is because of

This is unusual because other S3 boards have that set to false

It might indicate that you have to have the monitor settings for monitor_dtr and monitor_rts to either both no or yes (sometimes the logic is inverted). Please try in any case all 4 possible combinations listed here.

I uploaded a blink sketch and the LED blinks successfully. I connected the LED to GPIO 33 and heres the code I uploaded:

#include <Arduino.h>

#define LED_PIN 33

void setup() {
  pinMode(LED_PIN, OUTPUT);

void loop() {

  digitalWrite(LED_PIN, HIGH);
  Serial.println("LED HIGH");
  digitalWrite(LED_PIN, LOW);
  Serial.println("LED LOW");

However the serial monitor still seems to be an issue as it returns nothing. I tried all the 4 cases you referenced, the only that showed something different was the case where:

monitor_rts = 0
monitor_dtr = 0

The result generated because of this in the serial monitor was:

Executing task: platformio device monitor --port /dev/ttyACM0 

--- forcing DTR inactive
--- forcing RTS inactive
--- Terminal on /dev/ttyACM0 | 115200 8-N-1
--- Available filters and text transformations: colorize, debug, default, direct, esp32_exception_decoder, hexlify, log2file, nocontrol, printable, send_on_enter, time
--- More details at
--- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H
Build:Mar 27 2021
rst:0x1 (POWERON),boot:0x18 (SPI_FAST_FLASH_BOOT)
mode:DIO, clock div:1
entry 0x403c9880

However this still doesnt show what is required on the serial monitor. The serial monitor was blank in all other cases.

Okay then very miracously the Arduino-ESP32 board definition is wrong. It clearly defines the native USB-CDC of the ESP32S3 as the standard Serial

but the schematics disagree. There, it has a CH343P USB-to-serial converter, and the ESP32-S3 feeds it via UART. Sneaky.

Please go into the waveshare_esp32s3_touch_lcd128.json and delete the line


then clean + upload + monitor again. Keep the settings for monitor_dtr and monitor_rts equal to 0.

1 Like

Thanks @maxgerhardt !

This does the job. I can now see the correct results on my serial monitor. Also everything works without the monitor_dtr and monitor_rts parameters as well are they really necessary?

Perhaps you could consider making a pull request to platform-espressif-32 so that the board is officially supported.

Once again, thanks for your help, highly appreciate it!