Introduction: Develop ESP32 With PlatformIO IDE

This instructables show how to use PlatformIO IDE develop with ESP32 board.

Step 1: Why ESP32? Why PlatformIO IDE?

ESP32 is a new SoC (System on Chip) that integrated Bluetooth and WiFi capability at the same time, and also 32 bit dual processor, higher speed, more RAM, bar, bar, bar...

However, since it is a new chip, the support in the Arduino framework is still very limited, especially bluetooth related features. Many advanced feature sample code direct using the official ESP-IDF framework but not Arduino one. So it is the time trying something besides Arduino.

There are few methods I can found in the internet developing with ESP-IDF:

  • using your own editor and compile the code in command line
  • using Eclipse IDE
  • using PlatformIO IDE

I am trying PlatformIO IDE in this instructables.


Step 2: Arduino Vs PlatformIO

Before choosing PlatformIO IDE let me try to compare it with Arduino:

Version Upgrade


  1. Manual download from offical site


  1. Code editor (VSCode or Atom) itself capable auto update
  2. PlatformIO manual update by 'pio update' command

Add platform support


  1. Append Additional Board Manager URL
  2. Install new board in Board Manager
  3. Select appropriate board and options in Sketchbook
  4. Support arduino-esp32 framework


  1. Append platform and framework parameters in project platformio.ini
  2. Required source automatically download while build
  3. Single project can support multiple platform at the same time
  4. Support both arduino-esp32 and ESP-IDF framework

Add library


  1. search and install in Library Manager


  1. search and install with 'pio lib' command

Platform and Library Update


  1. Auto detect platform and library updates and prompt to the user
  2. User manually update in Board Manager and Library Manager


  1. Manually check and update with 'pio update' command

IDE feature


  1. Simple code editor
  2. Decent Serial Monitor and Plotter


  1. Colourful code editor, IntelliSence, Github support and rich of package extendable features
  2. A very simple console based serial monitor

Step 3: Install Code Editor

PlatformIO IDE live on top of a code editor, it can be installed as an extension in Atom or VSCode.

So, you should choose one of the code editor first. I have tried both code editors, I think VSCode is more rich feature out of the box for an entry level developer. Atom also have similar feature by installing extra packages, so don't worry if you are more familiar with Atom.

I will use VSCode as the Code Editor in the following steps.

Download link:



Step 4: Install PlatformIO

  1. Open VSCode Extension Manager.
  2. Search for official platformio-ide extension.
  3. Install PlatformIO IDE.
  4. After install PlatformIO IDE, few further packages will auto install and ask you reload when finished.


Step 5: Familiar With VSCode and PlatformIO IDE

Before start coding, it is better familiar with the code editor.

Command Palette

VSCode is a package extendable code editor, so it can have unlimited command set and related shortcut keys. It is very hard to remember all the location of function menu items and their shortcut keys. So VSCode consolidate all command in Command Palette. You may bring up the Command Palette in 2 ways:

  • Select 'View' menu -> Command Palette
  • Press Ctl + Shift + P shortcut key

Then type a keyword to search the function command you want.


There are 3 ways to open the setting in VSCode:

  • Select 'File' menu -> Preference -> Setting
  • search 'user settings' in Command Palette
  • Press Ctl + Comma shurtcut key

The setting UI is actually 2 text editor panel. The left hand side show all available settings and their default value; The right hand side is your customize setting in JSON format. You can search the setting keyword and select your desired values, e.g. the above screen shot show I am searching with keyword 'startup' and then turned off the VSCode and PlatformIO IDE welcome screen when VSCode startup.


Step 6: Create PlatformIO Project

VSCode use a folder as a project unit, so you should create a new folder when creating a new PlatformIO project.

Let's create your First PlatformIO project:

  1. Select 'File' menu -> Open Floder
  2. Select the project folder (you may create a new folder in the select folder dialog)
  3. Open Command Palette and search 'PlatformIO init'
  4. Wait a while for the init process
  5. Select a board for your project, type ESP32 to narrow down the list (you may add further board at the same project)

P.S. since various ESP32 dev board is very similar in configuration, you may simply select one of it if you cannot find your board name.

Step 7: PlatformIO IDE Toolbar

After init the PlatformIO project, you may find an additional PlatformIO toolbar at the left bottom coner. From left to right it is:

  • Home (PIO Account, library and platform managers, board explorer, and more...)
  • Build
  • Upload (deploy the built binary to the board)
  • Clean
  • Initialize new PlatformIO Project or Update existing... (select further board)
  • Serial Port Monitor (commuicate or debug with deployed program)
  • PIO Terminal (run pio command or OS compatible command)


Step 8: Platformio.ini

PlatformIO support both arduino-ESP32 and ESP-IDF framework. By default, PlatformIO selected arduino-ESP32. We need to change it to ESP-IDF.

Select 'platformio.ini' in Explorer Panel and modify the framwork line to:

framework = espidf

And also the Serial Port Monitor default baud rate is 9600, we need to change it as 115200 to communicate with ESP32, append the follow line to the platformio.ini:

monitor_baud = 115200

Save and close the file.

Step 9: Example 1: BLE Hello World

ESP-IDF have a better support in BLE related feature, let's begin with a BLE hello world program.

  1. Open a new project folder called 'ble_hello_world'
  2. Press Ctl + Alt + I shortcut key to initialize PlatformIO project
  3. Select your ESP32 board
  4. Modify 'framework = espidf' and append 'monitor_baud = 115200' in platformio.ini
  5. Right click the 'src' folder and select 'new file' (all project source code should under this folder)
  6. Input a file name, e.g. 'app_bt.c'
  7. Copy the sample code from ESP-IDF Github (press raw button, select all, copy):

  8. Paste the sample code to app_bt.c and save
  9. Press 'PlatformIO: Build' button (left bottom corner)
  10. Wait a while for build success (it require some time for downloading the firmware for the first build)
  11. Connect ESP32 board
  12. Press 'PlatformIO: Upload' button
  13. The upload program should be able to auto switch the ESP32 board to program mode, however I found my boards (2 different board bought from Taobao) failed to do that. I need hold the ESP32 board program button while upload for manually switch it to program mode
  14. Press 'PlatformIO: Serial Monitor' button
  15. Reset ESP32 by pressing reset / EN button on the board
  16. Serial Monitor should show advertising BLE signal
  17. Open a BLE tool, like 'nRF Connect' or 'LightBlue' in the mobile, you should see a 'ESP-BLE-HELLO' device in the list

You may find more sample code at ESP-IDF Github:

Step 10: Example 2: ESP32 With OLED

Some ESP32 board like this one built-in an I2C OLED but not connected to the ESP32 hardware I2C pin. This example show how to import imxieyi's esp32-i2c-ssd1306-oled as the project library.

  1. Open a new project folder called 'oled'
  2. Press Ctl + Alt + I shortcut key to initialize PlatformIO project
  3. Select 'WeMOS LOLIN32' board
  4. Modify 'framework = espidf' and append 'monitor_baud = 115200' in platformio.ini
  5. Right click 'lib' folder in explorer panel and select 'new folder'
  6. Input 'ssd1306' as the lib folder name
  7. Download the ssd1306 lib source code from Github:
  8. Copy files font*.*, i2c.* and ssd1306.* to the project lib ssd1306 folder
  9. Copy main.cpp to project src folder
  10. The finished folder structure should be like the above screen capture
  11. Code fix
    • since there are no 'include' folder structure, remove all 'include/' in all source code files
    • fill the correct I2C pin, replace 'GPIO_NUM_19' to 'GPIO_NUM_4' and 'GPIO_NUM_22' to 'GPIO_NUM_5' in main.cpp
  12. build and upload
  13. you should see the OLED plotting the ADC value

Step 11: Example 3: Esptouch

Similar to the steps in example 2 but replace the attached main.cpp file.

This example combined offical Esptouch example with the OLED display, you can use your mobile with the Esptouch App help to set the ESP32 board WiFi connection on the fly. After input the settings, the connection details will show on the OLED.



Bluetooth Challenge

Participated in the
Bluetooth Challenge