Overview

PlatformIO is an open-source, cross-platform IDE specifically designed for embedded software development. It features built-in library management, extensive ESP32 support, and compatibility with the Arduino framework.

This guide uses PlatformIO with Visual Studio Code. While the provided code is generally compatible with the Arduino IDE, note there may be minor differences in project structure and library handling.

💡 Tip:
Need more details on setting up or troubleshooting PlatformIO in VS Code? Check the official documentation:
PlatformIO IDE for VS Code.

Installing PlatformIO in VSCode

1. Click on Extension-Tab in the sidebar of Visual Studio

2. Search for “PlatformIO”

3. Install the extension. You might need to restart VS Code after that.

Contratulations 🎉 You’re now ready to start working with PlatformIO.
You will find all the things you need for the following steps in the PIO Home-Tab

Create a New Project

To get started, let’s create a new PlatformIO project for your ESP32 board:

1. Open PlatformIO Home
2. Click on “New Project”
3. Choose a board: Type “esp32 dev” in the search bar and select “Espressif ESP32 Dev Module”
4. Choose the Arduino framework (default)
5. Choose a project location by unchecking “Use default location” and selecting a folder
6. Click “Finish”

Once your project is created and opened, you’ll see its name appear in the bottom bar of VS Code (e.g., Default (demo_project)), confirming that your new project is active:

🔗 Jump to: 🧑‍💻 PlatformIO IDE · 📑 Table of Contents

Open an Existing PlatformIO Project

Want to continue working on an existing project? Here’s how to open it in PlatformIO.

1. Open PlatformIO Home
2. Click on “Open Project”
3. Select the project folder that contains the platformio.ini file
4. Click “Open”

When the project is loaded, its name will also appear in the bottom bar, just like with a newly created project:

🔗 Jump to: 🧑‍💻 PlatformIO IDE · 📑 Table of Contents

Project Folder Structure

When you create or open a PlatformIO project (e.g., 01_led_blink), you’ll see a folder structure like this:

Here’s what each folder is for:

• src/ – This is where your main code goes. Your entry point is main.cpp
• lib/ – Custom libraries you create for your project, or manually add (e.g. downloaded from GitHub)
• include/ – Header files (.h) for declaring functions, constants, etc
• .pio/ – PlatformIO uses this folder internally to store build output (build/) and libraries installed via the library manager (libdeps/)
• platformio.ini – Your project’s configuration file (defines board type, libraries, build settings)

For your programs, focus on writing your code in src/main.cpp.

PlatformIO automatically compiles and uploads the contents of that file to your ESP32.

🔗 Jump to: 🧑‍💻 PlatformIO IDE · 📑 Table of Contents

Libraries

PlatformIO uses a library manager to browse and install libraries. Libraries are installed per project, so you can have different libraries in different projects. They are listed in the platformio.ini file under the lib_deps line and are stored in the .pio folder within your project directory. If you no longer need a library, you can uninstall it through the library manager.

Install a Library:

1. Go to PlatformIO
2. Click on “Libraries”
3. Open the “Registry” tab
4. Search for the library you want to install
5. Click on the library
6. Click “Add to Project”
7. Choose your project
8. Click “Add”

Uninstall a Library:

1. Go to PlatformIO
2. Click on “Libraries”
3. Open the “Installed” tab
4. Locate the library you want to uninstall (make sure you select the correct project)
5. Click “Uninstall” and confirm with “Yes”

In some cases, the version of a library in the PlatformIO Library Manager may be outdated, while a newer version is available on GitHub. If you want to use the GitHub version instead, you can add it manually to your project:

Manually Install a Library from GitHub:

1. Copy the GitHub repository URL of the library you want to use
2. Open the platformio.ini file of your project
3. Add the URL to the lib_deps line, for example: lib_deps = https://github.com/Seeed-Studio/Grove_LED_Bar.git
4. Save the file
5. The library will be automatically downloaded and installed when you build or upload your code
6. You can find the installed library inside the lib folder of your project

🔗 Jump to: 🧑‍💻 PlatformIO IDE · 📑 Table of Contents

Run Your Code

Once your code is ready, you can upload it to your ESP32 board:

1. Make sure the correct project is selected in the bottom bar (e.g., Default (01_led_blink)).
2. Click the ➡️ Upload button (right arrow icon) in the bottom bar to build and flash your code to the ESP32.
3. Optionally, you can click the ✅ Build button first (checkmark icon) to compile the code without uploading – useful if you just want to check for errors.
4. Open the Serial Monitor (plug icon) to view messages from Serial.print() and other serial output.

Make sure your board is connected via USB and the correct COM port is selected (PlatformIO usually detects this automatically).

If your ESP doesn’t connect/respond while uploading press the BOOT-Button until you see “Connecting” on the terminal
If the error code reads “COM3 does not exist“, just unplug the USB-C cable on your laptop for a second.

If you don’t see any messages in the Serial Monitor, double-check that you’ve included Serial.begin(baud-rate); in your setup() function, and ensure the baud rate (e.g., 9600) matches the one selected in your Serial Monitor settings.

🔗 Jump to: 🧑‍💻 PlatformIO IDE · 📑 Table of Contents

❗IMPORTANT

You cannot use the example codes directly, as they are created for PlatformIO.
However, in the seperate example folders, you will find the code in the scr-folder in the main.cpp file.
You can directly copy the code in there, into the .ino file in a new arduino project.

Installing ESP32 Dependencies from Boardmanager

Open the Board Manager over Tools> Board> Boardmanager

If the ESP32 is not already installed, search for esp32 by espressiv and install it.
Select the DOIT DEVKIT V1 Version

Create a new Project

Open existing Project

Folder structure (or lack thereof)

In Arduino V2 you can set a sketchbook location, where the program is able to find existing code to open.

However, it does not work with subfolders

Libraries

Run your code

You can compile your code with the first button on the top-left

if you want to compile and upload it, choose the second button, as shown.

Always make sure the correct board is selected.

Pin Configuration

Learn how to define pins and configure them correctly for input and output:

• Define a Pin
  • Create a named constant for a pin to make your code more readable and easier to maintain.
  • Example:

const int LED_PIN = 2;  // Replace 2 with the actual GPIO pin number you want to use

• pinMode(pin, mode)🔗
  • Configures a specified pin to behave as either an input or an output.
  • Example:

pinMode(LED_PIN, OUTPUT);
pinMode(SENSOR_PIN, INPUT);
pinMode(BUTTON_PIN_1, INPUT_PULLDOWN);
pinMode(BUTTON_PIN_2, INPUT_PULLUP);

📝 Note:
Not sure which GPIO pin number to use?
See GPIO Pinout to find all pin assignments for the ESP32 and
MCP23018 in your FactoryBox.

🔗 Jump to: 💡 Common Functions You’ll Use · 📑 Table of Contents

Read/Write Data

Discover how to interact with sensors, buttons, LEDs, and more:

• digitalWrite(pin, value)🔗
  • Writes a HIGH or LOW value to a digital pin.
  • Example:

digitalWrite(LED_PIN, HIGH);  // Turn the LED on
digitalWrite(LED_PIN, LOW);   // Turn the LED off

• digitalRead(pin)🔗
  • Reads the value (HIGH or LOW) from a specified digital pin.
  • Example:

int buttonState = digitalRead(BUTTON_PIN);
int sensorReading = digitalRead(SENSOR_PIN);

• analogWrite(pin, value)🔗
  • Writes an analog (PWM) value to a pin. On most boards, the default resolution is 8-bit (0 to 255).
  • Example:

analogWrite(LED_PIN, 180);  // Set LED brightness (0 = off, 255 = full brightness)

• analogRead(pin)🔗
  • Reads the value from an analog pin. ESP32 analog inputs have a 12-bit resolution (0 to 4095).
  • Example:

int sensorReading = analogRead(SENSOR_PIN);

🔗 Jump to: 💡 Common Functions You’ll Use · 📑 Table of Contents

Timing and Logic

Essential tools to control the flow and timing of your program:

• delay(milliseconds)🔗
  • Pauses the program for a set amount of time. Useful for blinking LEDs, debouncing buttons, and slowing down actions.
  • Example:

digitalWrite(LED_PIN, HIGH);
delay(500);  // Wait 500 milliseconds (code execution is paused)
digitalWrite(LED_PIN, LOW);
delay(500);

📝 Note:
While delay() is simple and useful, it blocks your program – meaning no other code runs during the wait.
If you need to do multiple things at once (like blinking an LED while checking a button),
consider the non-blocking millis() approach instead.

• if🔗 / else🔗 Statement (Conditional Statement)
  • Control the flow of your program based on conditions. Perfect for checking sensor values, buttons, or states.
  • Example:

if (buttonState == HIGH) {
  digitalWrite(LED_PIN, HIGH);  // LED on
} else {
  digitalWrite(LED_PIN, LOW);   // LED off
}

• for Loop🔗
  • Use a for loop when you want to repeat something a specific number of times or iterate over a range of values.
  • General Syntax:

for (initialization; condition; increment) {
  // statement(s);
}
// A for-loop starts with an initialization, executed once.
// Then the condition is evaluated – if true, the loop body runs.
// After each run, the increment step is executed.
// This repeats until the condition becomes false, and the loop ends.

• Example:

// Blink an LED 5 times
for (int i = 0; i < 5; i++) {
  digitalWrite(LED_PIN, HIGH);
  delay(500);
  digitalWrite(LED_PIN, LOW);
  delay(500);
}
// Count from 0 to 4 and print the numbers
for (int i = 0; i < 5; i++) {
  Serial.println(i);
}
// Loop explanation:
// int i = 0: Initializes the loop counter i
// i < 5: The loop runs while this condition is true
// i++: Increments i by 1 after each loop cycle

🔗 Jump to: 💡 Common Functions You’ll Use · 📑 Table of Contents

Utility Functions

Helpful built-in functions to simplify common tasks in your code:

• map(value, fromLow, fromHigh, toLow, toHigh)🔗
  • Maps a number from one range to another.
  • Example:

int ledValue = map(potiRead, 0, 4095, 0, 255);
// Maps the potentiometer value (0 to 4095, 12-bit) to the analogWrite range (0 to 255, 8-bit PWM)

• constrain(value, min, max)🔗
  • Constrains a value to a specified range.
  • Example:

int constrainedValue = constrain(sensorValue, 1000, 3000);  // Limits the value between 1000 and 3000

🔗 Jump to: 💡 Common Functions You’ll Use · 📑 Table of Contents