> For the complete documentation index, see [llms.txt](https://robotlabs.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://robotlabs.gitbook.io/docs/esp32/platformio/1.2-install-platformio.md).

# 1.2 Install PlatformIO

{% embed url="<https://youtu.be/g7ItXoZfbgE>" %}

## Install VS Code and Python

1. Go to <https://code.visualstudio.com/> and download the stable build for your operating system.
2. Go to [python.org/download](https://python.org/download) and download Python 3.8.5 or a newest version.

<figure><img src="/files/4y8bR8miyrnzFHdAyA1J" alt=""><figcaption><p>C<strong>heck the option Add VS Code and Python to PATH during installation</strong></p></figcaption></figure>

{% hint style="info" %}
**IMPORTANT: Make sure you check the option Add VS Code and Python to PATH.**
{% endhint %}

## Installing PlatformIO IDE Extension on VS Code <a href="#id-2" id="id-2"></a>

It is possible to program the ESP32 and ESP8266 boards using VS Code with the PlatformIO IDE extension. Follow the next steps to install the PlatformIO IDE extension.

Open VS Code:

1. Click on the **Extensions** icon or press **Ctrl**+**Shift**+**X** to open the **Extensions** tab
2. Search for “**PlatformIO IDE**”
3. Select the first option
4. Finally, click the **Install** button (Note: the installation may take a few minutes)

<figure><img src="/files/k156YFRNCwbsxWPK8zga" alt=""><figcaption></figcaption></figure>

After installing, make sure that PlatformIO IDE extension is enabled as shown below.

<figure><img src="/files/rI6Kvj4rmvl9l8B36sD3" alt=""><figcaption></figcaption></figure>

After that, the PlatformIO icon should show up on the left sidebar as well as an **Home** icon that redirects you to PlatformIO home. Restart VS code for the changes to take effect.

<div align="left"><figure><img src="/files/FuSUcH7fN8vuKXzoil8H" alt=""><figcaption></figcaption></figure></div>

At the bottom of the IDE, there’s a blue bar with PlatformIO commands. From left to right:

* PlatformIO Home
* Build/Compile
* Upload
* Clean
* Serial Monitor
* New Terminal

If you hover your mouse over the icons, it will show what each icon does. Alternatively, you can also click on the PIO icon to see all the PlatformIO tasks. You may need to click on the three dot icon at the top and enable PlatformIO tasks as shown below.

<figure><img src="/files/XV5K2CltyAzolmlb0mBw" alt=""><figcaption></figcaption></figure>

## PlatformIO IDE Quick Overview <a href="#id-3" id="id-3"></a>

### Create a New Project

On VS Code, click on the PlartfomIO **Home** icon. Click on **+ New Project** to start a new project.

<figure><img src="/files/WjMPBl5M7h1kawjpmF6q" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/2apu7FTx0yx4mVQQ9JX4" alt="" width="299"><figcaption></figcaption></figure>

Give your project a name (for example *Blink\_LED*) and select the board you’re using. The Framework should be “**Arduino**” to use the Arduino core.

The default location is in this path *Documents* >*PlatformIO* >*Projects*. Finally, click “Finish”. The Blink\_LED project should be accessible from the Explorer tab.

<figure><img src="/files/26ejTSHBZpvJ8zTfUz4N" alt=""><figcaption></figcaption></figure>

VS Code and PlatformIO have a folder structure that is different from the standard *.ino* project. If you click on the File Explorer tab, you’ll see all the files it created under your project folder. It may seem a lot of files to work with. But, don’t worry, usually you’ll just need to deal with one or two of those files.

{% hint style="info" %}
**Warning:** you shouldn’t delete, modify or move the folders and the *platformio.ini* file. Otherwise, you will no longer be able to compile your project using PlatformIO.
{% endhint %}

### platformio.ini file

The *platformio.ini* file is the PlatformIO Configuration File for your project. It shows the platform, board, and framework for your project. You can also add other configurations like libraries to be included, upload options, changing the Serial Monitor baud rate and other configurations.

<div data-full-width="false"><figure><img src="/files/Cf62iHPKmRTCtA9QKhWb" alt=""><figcaption></figcaption></figure></div>

* **platform**: which corresponds to the SoC used by the board.
* **board**: the development board you’re using.
* **framework**: the software environment that will run the project code.
* **monitor\_speed**: set the baud rate. The default baud rate used by PlatformIO is 9600. However, it is possible to set up a different value.

In this file, you can also include the identifier of libraries you’ll use in your project using the `lib_deps` directive, save that file if you make any changes.

### src folder

Under the *src* folder, there’s a *main.cpp* file. That’s where you write your code. Click on that file. The structure of an Arduino program should open with the setup() and loop() functions.

<figure><img src="/files/PhdDDUNj6rbvyIaQwoxF" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
In PlatformIO, all your Arduino sketches should start with the #include \<Arduino.h>.
{% endhint %}

After writing code, press **Ctrl**+**S** or go to **File** > **Save** to save the file. Now, you can click on the Upload icon to compile and upload the code. Alternatively, you can go to the PIO Project Tasks menu and select **Upload**.

<figure><img src="/files/VpprRuns5nXX6FUU202X" alt=""><figcaption></figcaption></figure>

If the code is successfully uploaded, you should get the following message. Now, click on the Serial Monitor, and if you don’t see the Terminal window, go to the menu Terminal > New Terminal.

<figure><img src="/files/lLXXEnbAn2viPNddvqli" alt=""><figcaption></figcaption></figure>

### Detect COM Port

PlatformIO will automatically detect the port your board is connected to. To check the connected devices you can go to the **PIO Home** and click the **Devices** icon.

<figure><img src="/files/O48J1nMRB22cdCAbJovF" alt=""><figcaption></figcaption></figure>

### Troubleshooting

1. If you try to upload a new sketch to your ESP32 and you get this error message “*A fatal error occurred: Failed to connect to ESP32: Timed out… Connecting…*“. It means that your ESP32 is not in flashing/uploading mode. Having the right board name and COM por selected, follow these steps:
   1. Hold-down the **BOOT** button in your ESP32 board
   2. Press the **Upload** button in the Arduino IDE to upload your sketch
   3. After you see the  “*Connecting….*” message in your Arduino IDE, release the finger from the **BOOT** button
   4. After that, you should see the “*Done uploading*” message\
      You’ll also have to repeat that button sequence every time you want to upload a new sketch.&#x20;
2. If you get the error “COM Port not found/not available”, you might need to install the CP210x Drivers

## Installing ESP32 Libraries on PlatformIO IDE <a href="#id-7" id="id-7"></a>

Click the **Home** icon to go to PlatformIO Home. Click on the **Libraries** icon on the left side bar. Search for the library you want to install. For example *Adafruit\_BME280*. Click on the library you want to include in your project.&#x20;

<figure><img src="/files/W8Z7V26scwttO291ShMn" alt=""><figcaption></figcaption></figure>

### Install Library way 1

Click **Add to Project**. Select the project that you want to use the library.

<div align="center"><figure><img src="/files/ARVYzKir89ElW6FOTBm3" alt="" width="559"><figcaption></figcaption></figure></div>

<figure><img src="/files/3R0slDDq613BDMQXf5YE" alt="" width="351"><figcaption></figcaption></figure>

This will add the library identifier using the `lib_deps` directive on the *platformio.ini* file. If you open your project’s *platformio.ini* file, it should look as shown in the following image.

<figure><img src="/files/S6rMSEXn7s1Jo5umd2qK" alt=""><figcaption></figcaption></figure>

### Install Library way 2

Alternatively, on the library window, if you select the **Installation** tab and scroll a bit, you’ll see the identifier for the library. You can choose any of those identifiers depending on the options you want to use. The library identifiers are highlighted in red.

<figure><img src="/files/zayxeUp4LCwODdf9trlJ" alt=""><figcaption></figcaption></figure>

Then, go to the *platformio.ini* file of your project and paste the library identifier into that file, like this:

```
lib_deps = adafruit/Adafruit BME280 Library@^2.1.0
```

If you need multiple libraries, you can separate their name by a coma or put them on different lines. For example:

```
lib_deps =
  arduino-libraries/Arduino_JSON @ 0.1.0
  adafruit/Adafruit BME280 Library @ ^2.1.0
  adafruit/Adafruit Unified Sensor @ ^1.1.4
```

{% hint style="info" %}
PlatformIO has a built-in powerful Library Manager, that allows you to specify custom dependencies per project in the Project Configuration File *platformio.ini* using `lib_deps`. This will tell PlatformIO to **automatically** download the library and all its dependencies when you save the configuration file or when you compile your project.
{% endhint %}

## Summary

VS Code with the PlatformIO IDE extension is a great alternative to the classical Arduino IDE, especially when you’re working on more advanced sketches for larger applications.

Here’s some of the advantages of using VS Code with PlatformIO IDE over Arduino IDE:&#x20;

* It detects the COM port your board is connected to automatically;&#x20;
* VS Code IntelliSense: Auto-Complete.&#x20;
* Error Highlights: VS Code + PIO underlines errors in your code before compiling;
* Multiple open tabs: you can have several code tabs open at once;
* You can hide certain parts of the code;
* Advanced code navigation;
* And much more…

If you’re looking for a more advanced IDE to write your applications for the ESP32 boards, VS Code with the PlatformIO IDE extension is a great option.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://robotlabs.gitbook.io/docs/esp32/platformio/1.2-install-platformio.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.