Skip to content
ESP32-S3-DevKitC-1

PlatformIO Setup

PlatformIO provides an IDE-centric development experience with Arduino or ESP-IDF framework support.

Installation

  1. Install VS Code
  2. Open Extensions (Ctrl+Shift+X)
  3. Search for “PlatformIO IDE”
  4. Install and restart VS Code

Project Setup

  1. Create new project

    1. Click PlatformIO icon in sidebar
    2. Select “New Project”
    3. Name: esp32s3-devkitc
    4. Board: esp32-s3-devkitc-1
    5. Framework: Arduino or ESP-IDF

  2. Configure for N16R8

    Edit platformio.ini:

    [env:esp32-s3-devkitc-1]
    platform = espressif32
    board = esp32-s3-devkitc-1
    framework = arduino
    

    ; Memory configuration for N16R8
    board_build.flash_mode = qio
    board_build.psram_type = opi
    board_upload.flash_size = 16MB
    board_build.arduino.memory_type = qio_opi
    

    ; Optional: Upload and monitor
    upload_speed = 921600
    monitor_speed = 115200
    

    ; Optional: Enable PSRAM in Arduino
    build_flags =
        -DBOARD_HAS_PSRAM
        -mfix-esp32-psram-cache-issue

N16R8 Memory Configuration

Complete platformio.ini for N16R8

[env:esp32-s3-devkitc-1-n16r8]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino


; === Flash Configuration ===
board_build.flash_mode = qio
board_upload.flash_size = 16MB


; === PSRAM Configuration (Octal) ===
board_build.psram_type = opi
board_build.arduino.memory_type = qio_opi


; === Build Flags ===
build_flags =
    -DBOARD_HAS_PSRAM
    -DARDUINO_USB_MODE=1
    -DARDUINO_USB_CDC_ON_BOOT=1


; === Upload Settings ===
upload_speed = 921600
upload_port = /dev/ttyUSB0


; === Monitor Settings ===
monitor_speed = 115200
monitor_port = /dev/ttyUSB0
monitor_filters = esp32_exception_decoder


; === Debug (optional) ===
debug_tool = esp-builtin
debug_init_break = tbreak setup

Using PSRAM in Code

#include <Arduino.h>


void setup() {
    Serial.begin(115200);


    // Check PSRAM availability
    if (psramFound()) {
        Serial.printf("PSRAM Size: %d bytes\n", ESP.getPsramSize());
        Serial.printf("Free PSRAM: %d bytes\n", ESP.getFreePsram());
    } else {
        Serial.println("PSRAM not found!");
    }
}


void loop() {
    // Allocate in PSRAM
    uint8_t* buffer = (uint8_t*)ps_malloc(1024 * 1024);  // 1MB
    if (buffer) {
        Serial.println("Allocated 1MB in PSRAM");
        free(buffer);
    }
    delay(5000);
}

USB Configuration

The DevKitC-1 has two USB ports. Configure based on your needs:

USB-CDC (Native USB as Serial)

build_flags =
    -DARDUINO_USB_MODE=1
    -DARDUINO_USB_CDC_ON_BOOT=1

USB-OTG (Custom USB Device)

build_flags =
    -DARDUINO_USB_MODE=0

UART Only (CP2102N)

build_flags =
    -DARDUINO_USB_MODE=0
    -DARDUINO_USB_CDC_ON_BOOT=0

Common Libraries

Add to platformio.ini:

lib_deps =
    ; NeoPixel for RGB LED
    adafruit/Adafruit NeoPixel@^1.12.0


    ; FastLED alternative
    ; fastled/FastLED@^3.6.0


    ; Wi-Fi Manager
    tzapu/WiFiManager@^2.0.16


    ; MQTT
    knolleary/PubSubClient@^2.8


    ; HTTP Client
    ; (included in ESP32 Arduino core)


    ; JSON
    bblanchon/ArduinoJson@^7.0.0


    ; AsyncWebServer
    me-no-dev/AsyncTCP@^1.1.1
    me-no-dev/ESPAsyncWebServer@^1.2.6

Build and Upload

  • Build: Click checkmark in bottom toolbar or Ctrl+Alt+B
  • Upload: Click arrow in bottom toolbar or Ctrl+Alt+U
  • Monitor: Click plug icon or Ctrl+Alt+S

Partition Tables

For 16MB flash, consider a custom partition table:

Create partitions.csv:

# Name,   Type, SubType,  Offset,   Size,     Flags
nvs,      data, nvs,      0x9000,   0x5000,
otadata,  data, ota,      0xe000,   0x2000,
app0,     app,  ota_0,    0x10000,  0x300000,
app1,     app,  ota_1,    0x310000, 0x300000,
spiffs,   data, spiffs,   0x610000, 0x9F0000,

Add to platformio.ini:

board_build.partitions = partitions.csv

Troubleshooting

PSRAM Not Detected

  1. Verify board_build.psram_type = opi
  2. Check board_build.arduino.memory_type = qio_opi
  3. Add -DBOARD_HAS_PSRAM to build flags

Upload Fails

; Try slower speed
upload_speed = 460800


; Or use explicit port
upload_port = /dev/ttyUSB0

Serial Monitor Shows Garbage

; Match baud rate to your code
monitor_speed = 115200


; Add decoder for crash traces
monitor_filters = esp32_exception_decoder

Build Errors After Update

Terminal window
pio pkg update
pio run -t clean
pio run

ESP-IDF Framework in PlatformIO

For full ESP-IDF access:

[env:esp32-s3-devkitc-1-idf]
platform = espressif32
board = esp32-s3-devkitc-1
framework = espidf


board_build.flash_mode = qio
board_upload.flash_size = 16MB
board_build.psram_type = opi

Next Steps