PlatformIO

Why bother, once the IDE works

Because the eight settings are not in the sketch. They live in the Arduino IDE's preferences, attached to a board rather than to a project — so a sketch you send somebody arrives with none of them, and a machine you set up in six months starts from the same blank menu.

PlatformIO puts them in a file called platformio.ini, next to the code, in the repository. That is the whole argument. The code stays Arduino code; setup and loop and every library you already use keep working.

The file, line by line

Each line here is one row of the Tools menu you already filled in.

Two entries in that list have no menu equivalent and are worth knowing anyway. CORE_DEBUG_LEVEL turns on the core's own logging — 3 is informative without being a flood, 5 is everything, 0 is silence. BOARD_HAS_PSRAM is the flag that tells the Arduino core to offer PSRAM to the allocator; without it the memory is initialised and nothing uses it.

Getting set up

1. Install VS Code, then the PlatformIO IDE extension from the Extensions view. It downloads PlatformIO Core on first run, which takes a few minutes.

2. PIO Home ▸ New Project. Name it, pick Espressif ESP32-S3-DevKitC-1, framework Arduino, and Finish.

3. Replace the generated platformio.ini with the one below.

4. Put your code in src/main.cpp. It is an Arduino sketch with one extra line at the top:

   Copy

   #include <Arduino.h>
   
   void setup() {
     Serial.begin(115200);
     delay(1500);
     Serial.printf("psram %u bytes\n", ESP.getPsramSize());
   }
   
   void loop() {
     delay(1000);
   }

   .ino files hide that include; .cpp files do not. That is the only change most sketches need.

5. Build and upload with the arrow in the status bar, then open the monitor with the plug icon beside it.

Name your ports

On a board with two sockets, this is worth adding the day you first plug both in:

upload_port  = /dev/cu.usbmodem101
monitor_port = /dev/cu.usbmodem101

Without them PlatformIO picks whichever serial device it finds first, which on a desk with a second board plugged in is a genuine coin toss — and the failure is an upload that goes somewhere else entirely.

Two environments, one file

The real reward comes when you stop choosing. A single file can describe both sockets, and you build whichever you want:

[env]
platform  = espressif32
board     = esp32-s3-devkitc-1
framework = arduino
monitor_speed = 115200
board_upload.flash_size = 16MB
board_build.partitions  = default_16MB.csv
board_build.arduino.memory_type = qio_opi
build_flags = -D BOARD_HAS_PSRAM

[env:usb]
build_flags = ${env.build_flags} -D ARDUINO_USB_MODE=1 -D ARDUINO_USB_CDC_ON_BOOT=1

[env:uart]
build_flags = ${env.build_flags}

pio run -e usb -t upload for the right-hand socket, -e uart for the left. The setting that caused every silent Serial Monitor in this book is now a command-line flag, and you can prove which one you built.