Setting Up PlatformIO for the Freenove ESP32-S3 Breakout Board

What You Need Before You Start

PlatformIO is a development environment that runs inside Visual Studio Code and handles all the compiler settings, library management, and board configuration for you. To set it up for the Freenove ESP32-S3 Breakout Board, you need Visual Studio Code installed on your computer, the PlatformIO extension added to VS Code, and the board itself connected via USB. The whole process takes about 15 minutes and involves creating a new project, selecting the correct board from PlatformIO's list, and verifying the connection works.

The Freenove ESP32-S3 is recognized by PlatformIO under the name "Freenove ESP32-S3 Breakout Board" or sometimes listed as a generic ESP32-S3 variant. PlatformIO will automatically download the correct toolchain and libraries once you tell it which board you are using, so you do not need to hunt down drivers or compiler files yourself.

Key Takeaways

Install Visual Studio Code first, then add the PlatformIO extension from the Extensions marketplace inside VS Code.
Create a new PlatformIO project and search for "Freenove ESP32-S3" in the board selection menu to find the correct board definition.
Connect your Freenove board via USB and check that VS Code detects the COM port (Windows) or /dev/ttyUSB port (Linux/Mac) in the PlatformIO device monitor.
Write a test sketch, build it using the PlatformIO build button, and upload it to verify the configuration is working.
If the upload fails, check the board selection, USB cable, and COM port assignment in the platformio.ini file.

Installing PlatformIO in Visual Studio Code

Open Visual Studio Code and click the Extensions icon on the left sidebar (it looks like four squares). Type "PlatformIO" in the search box and click the official PlatformIO IDE extension by PlatformIO. Click the Install button and wait for the installation to finish — this may take a minute or two because PlatformIO downloads several components in the background.

Once installation is complete, you will see a PlatformIO icon appear on the left sidebar (a small house icon). Click it to open the PlatformIO home screen. You are now ready to create a project.

Creating a New Project for the Freenove Board

On the PlatformIO home screen, click "Create New Project". A dialog box will open asking for a project name, board selection, and framework. Type a name for your project — something like "freenove-test" works fine.

In the "Select a board" field, type "Freenove ESP32-S3". PlatformIO will search its database and show you matching boards. Click on "Freenove ESP32-S3 Breakout Board" when it appears in the list. For the framework, select "Arduino" — this is the most common choice for the Freenove board and gives you access to the Arduino library ecosystem. Click "Finish" and PlatformIO will create the project folder and download all necessary files.

The first time you create a project with a new board, PlatformIO downloads the ESP32-S3 toolchain, which can take several minutes depending on your internet speed. You will see a progress bar at the bottom of VS Code. Let it finish completely before moving on.

Checking the platformio.ini Configuration File

Once the project is created, open the file called platformio.ini in the project root. This file tells PlatformIO which board, framework, and upload settings to use. You should see something like this:

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

The board line should read "freenove_esp32s3_breakout" — if it shows something different, change it to match. The monitor_speed of 115200 is correct for this board. If you need to specify a particular COM port (Windows) or /dev/ttyUSB port (Linux/Mac), you can add a line like "upload_port = COM3" or "upload_port = /dev/ttyUSB0", but PlatformIO usually detects this automatically.

Connecting Your Board and Testing the USB Connection

Plug your Freenove ESP32-S3 Breakout Board into your computer using a USB-C cable. The board should light up with a power LED. In VS Code, click the PlatformIO icon on the left sidebar, then expand the "Devices" section. You should see your board listed with a COM port number (Windows) or a /dev/ttyUSB number (Linux/Mac).

If you do not see your board listed, try these steps: first, check that the USB cable is a data cable, not a power-only cable — many USB-C cables only carry power. Second, unplug the board, wait five seconds, and plug it back in. Third, restart VS Code. If the board still does not appear, you may need to install the CH340 USB driver, which is the chip the Freenove board uses for USB communication. Search for "CH340 driver" and your operating system to find the correct driver download.

Writing and Uploading a Test Sketch

In the project folder, open the file "src/main.cpp". This is where your code goes. Replace the contents with this simple test sketch:

void setup() { Serial.begin(115200); pinMode(LED_BUILTIN, OUTPUT); } void loop() { digitalWrite(LED_BUILTIN, HIGH); delay(1000); digitalWrite(LED_BUILTIN, LOW); delay(1000); Serial.println("LED toggled"); }

This code blinks the built-in LED and prints a message to the serial monitor every time it toggles. Save the file. Now click the checkmark icon at the bottom of VS Code to build the project. PlatformIO will compile your code and report any errors. If the build succeeds, you will see a green checkmark and a message saying "SUCCESS".

Once the build succeeds, click the arrow icon (the upload button) next to the checkmark. PlatformIO will upload the compiled code to your board. You should see progress messages and eventually a message saying the upload is complete. The LED on your board should now blink once per second.

Troubleshooting Upload Failures

If the upload fails, the most common cause is that PlatformIO cannot find the correct COM port. Check the platformio.ini file and verify the board name is exactly "freenove_esp32s3_breakout". If you see an error like "Failed to connect to ESP32", try holding down the BOOT button on the board while the upload is happening — this forces the board into bootloader mode.

Another common issue is that the USB driver is not installed. If you see "No device found on COM3" or similar, download and install the CH340 driver for your operating system. After installing the driver, unplug the board, restart your computer, and plug the board back in.

If the upload completes but the code does not run, check that you selected the Arduino framework in platformio.ini. Also verify that the board is powered — the power LED should be lit. If you still have trouble, try uploading the same sketch using the Arduino IDE to rule out a PlatformIO configuration issue.

Frequently Asked Questions

Do I need to install any drivers before PlatformIO can see my board?

The Freenove ESP32-S3 uses a CH340 USB chip, so you need the CH340 driver installed on your computer. Windows and Mac users often need to download this driver separately, while Linux usually includes it by default. If PlatformIO does not detect your board after plugging it in, install the CH340 driver for your operating system and restart your computer.

What if PlatformIO does not show the Freenove board in the board selection menu?

Make sure you typed "Freenove ESP32-S3" exactly in the search box. If nothing appears, click the "Advanced" button and search for just "ESP32-S3" to see all ESP32-S3 variants. You can also manually edit platformio.ini and set the board line to "freenove_esp32s3_breakout" if you know the exact board name.

Can I use PlatformIO with the Arduino IDE sketches I already have?

Yes. Copy your .ino file into the src folder of your PlatformIO project and rename it to main.cpp. PlatformIO uses the same Arduino libraries and syntax, so most sketches will work without changes. If your sketch uses setup() and loop() functions, it will work as-is.

Why does my board disconnect every time I open the serial monitor?

This is normal behavior for the ESP32-S3 — opening the serial monitor resets the board. If you want to see messages from startup, add a delay in your setup() function before printing, or use a serial monitor that does not reset on connect. PlatformIO's built-in monitor should handle this correctly, but some third-party serial monitors do not.

How do I change the upload speed if uploads are failing?

Add a line to platformio.ini like "upload_speed = 115200" or "upload_speed = 460800". The Freenove board supports speeds up to 921600, but 460800 is a good middle ground if you are having trouble. Start with 115200 if uploads consistently fail at higher speeds.

This guide is for general information only and is not medical, financial, legal, or other professional advice. For decisions specific to your situation, consult a qualified professional. See our Editorial Policy.