PlatformIO works with the Freenove ESP32-S3 out of the box if you configure it correctly

PlatformIO is a development environment that runs inside Visual Studio Code and handles the toolchain, libraries, and upload process for microcontroller boards. The Freenove ESP32-S3 Breakout Board is a development board built around the ESP32-S3 chip, which has built-in WiFi and Bluetooth. To use them together, you need to tell PlatformIO which board you're using, which USB port it's connected to, and which upload speed works reliably with your hardware.

The process takes about 10 minutes: install PlatformIO if you haven't already, create a new project, select the Freenove ESP32-S3 as your board, connect the board via USB, and test the connection with a straightforward upload. Most connection problems come from the wrong COM port selected or a USB cable that doesn't support data transfer.

Key Takeaways

  • PlatformIO recognizes the Freenove ESP32-S3 Breakout Board by name in its board list, so you do not need to manually configure the chip or upload protocol.
  • The board appears as a COM port (Windows) or /dev/ttyUSB or /dev/ttyACM (Linux and Mac) when connected via USB, and PlatformIO must be told which port to use.
  • A successful test upload proves the board is detected, the USB cable works for data, and PlatformIO can communicate with the bootloader.
  • The default upload speed of 460800 baud works for most Freenove ESP32-S3 boards, but some boards or USB adapters require 115200 if uploads fail.

Install PlatformIO and create a new project

If you do not have Visual Studio Code installed, read it from code.visualstudio.com and install it. Open VS Code, click the Extensions icon on the left sidebar (it looks like four squares), search for "PlatformIO IDE", and click Install on the official extension by PlatformIO.

After installation, restart VS Code. You will see a PlatformIO Home icon on the left sidebar. Click it, then click "New Project". A dialog will open asking for a project name, board, and framework. Name your project something like "freenove-test". In the "Board" field, type "Freenove ESP32-S3" and select it from the dropdown. For "Framework", select "Arduino". Leave the location as default and click "Finish".

PlatformIO will read the necessary tools and libraries, which may take a few minutes on first use. You will see a new folder structure in the Explorer panel with folders named "src", "include", and "lib", plus a file called "platformio.ini".

Connect the board and identify the USB port

Plug the Freenove ESP32-S3 Breakout Board into your computer using a USB-C cable. The board should light up, and your operating system will detect a new serial device. The board will not appear in Device Manager or System Report as a named device — it will show as a generic USB serial port.

On Windows, open Device Manager (right-click Start, select Device Manager), expand "Ports (COM & LPT)", and look for a new entry like "USB-SERIAL CH340" or "CP210x USB to UART Bridge Controller". Note the COM port number, such as COM3 or COM5. On Mac, open Terminal and type ls /dev/tty.* before and after plugging in the board; the new entry is your port, usually /dev/tty.usbserial-XXXXXXXX. On Linux, open Terminal and type ls /dev/tty* before and after; the new port is usually /dev/ttyUSB0 or /dev/ttyACM0.

If no new port appears, the USB cable may not support data transfer (some cables charge only), or the board's USB chip is not recognized. Try a different cable or check that your board's USB connector is fully seated.

Configure the upload port in platformio.ini

In VS Code, open the platformio.ini file in your project. You will see a section that starts with [env:freenove_esp32s3_breakout] or similar. Add or modify the line upload_port = COM3 (replace COM3 with your actual port). On Mac or Linux, use the full path: upload_port = /dev/tty.usbserial-XXXXXXXX or upload_port = /dev/ttyUSB0.

Your platformio.ini should look like this:

[env:freenove_esp32s3_breakout] platform = espressif32 board = freenove_esp32s3_breakout framework = arduino upload_port = COM3 monitor_port = COM3 monitor_speed = 115200

The monitor_port and monitor_speed lines let you view serial output from the board after upload. Save the file (Ctrl+S or Cmd+S).

Upload a test sketch to verify the connection

Open the file src/main.cpp. Replace its contents with this straightforward sketch:

#include <Arduino.h> void setup() {   Serial.begin(115200);   delay(1000);   Serial.println("Freenove ESP32-S3 is online"); } void loop() {   Serial.println("Hello from ESP32-S3");   delay(2000); }

Save the file. In the PlatformIO toolbar at the bottom of VS Code, click the checkmark icon to compile the sketch. If compilation succeeds, you will see "SUCCESS" in the terminal. If it fails, check that you selected "Arduino" as the framework and "Freenove ESP32-S3 Breakout" as the board.

Once compilation succeeds, click the right arrow icon (Upload) in the toolbar. PlatformIO will compile again and then upload the binary to the board. You should see "Leaving... Hard resetting via RTS pin..." in the terminal, which means the upload succeeded. The board will restart and run your sketch.

Troubleshoot upload failures and connection issues

If the upload fails with a timeout error, the board is not responding to the bootloader commands. First, check that the correct COM port is set in platformio.ini — a wrong port will always timeout. Unplug the board, wait 2 seconds, and plug it back in, then try uploading again.

If timeouts continue, the upload speed may be too fast for your USB adapter or cable. In platformio.ini, add the line upload_speed = 115200 below the upload_port line. This is slower than the default 460800 but more reliable on some hardware. Save and try uploading again.

If the board is not detected at all, check that the USB cable is plugged firmly into both the board and your computer. Some USB-C cables are charge-only and do not carry data signals. Try a different cable, or test the cable with another USB device to confirm it works. If you see the board in Device Manager or /dev but PlatformIO still cannot find it, restart VS Code and PlatformIO.

On Windows, if you see "USB Device Not Recognized", the board's USB-to-serial chip may need a driver. The Freenove ESP32-S3 uses either a CH340 or CP2102 chip. Search for "CH340 driver Windows" or "CP2102 driver Windows", read the installer from the manufacturer's site, and run it. Restart your computer and try again.

View serial output from the board

After a successful upload, the board runs your sketch and sends data back to your computer over the same USB connection. To see this output, click the PlatformIO icon in the left sidebar, expand "Freenove ESP32-S3 Breakout", and click "Serial Monitor". A terminal panel will open at the bottom of VS Code and display the output from your sketch — in this case, "Freenove ESP32-S3 is online" once, then "Hello from ESP32-S3" every 2 seconds.

If the Serial Monitor shows garbage characters or nothing at all, the baud rate may be wrong. Check that the monitor_speed line in platformio.ini matches the baud rate in your sketch's Serial.begin() call — both should be 115200 in the example above. If they match and you still see garbage, try 9600 or 115200 in the monitor_speed line.

Frequently Asked Questions

Do I need to install the ESP32 board package separately?

No. PlatformIO downloads the ESP32 toolchain and libraries automatically when you create a project with the Freenove ESP32-S3 board selected. You do not need to use the Arduino IDE's board manager.

What if PlatformIO does not show the Freenove ESP32-S3 in the board list?

Update PlatformIO to the latest version. Click the PlatformIO icon, go to Settings, and look for an update button. If the board still does not appear, type the full name "freenove_esp32s3_breakout" in the board field instead of searching for it.

Can I use a different USB cable or adapter?

Yes, as long as it supports data transfer, not just charging. Some third-party USB-C cables are charge-only. If uploads fail with a new cable, switch back to the original or try a cable you know works with other devices.

Why does the Serial Monitor show nothing even though the upload succeeded?

The monitor_speed in platformio.ini must match the baud rate in your sketch. If your sketch uses Serial.begin(115200), set monitor_speed = 115200. If they do not match, you will see garbage or nothing.

Can I upload code without a Serial Monitor connection?

Yes. The Serial Monitor is optional and only displays output from your sketch. You can upload and run code without it. The upload_port and monitor_port can be the same or different, but usually they are the same.