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.

ref.:

https://esp32.com

http://platformio.org

Step 2: Arduino Vs PlatformIO

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

Version Upgrade

Arduino

Manual download from offical site

PlatformIO

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

Add platform support

Arduino

Append Additional Board Manager URL
Install new board in Board Manager
Select appropriate board and options in Sketchbook
Support arduino-esp32 framework

PlatformIO

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

Add library

Arduino

search and install in Library Manager

PlatformIO

search and install with 'pio lib' command

Platform and Library Update

Arduino

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

PlatformIO

Manually check and update with 'pio update' command

IDE feature

Arduino

Simple code editor
Decent Serial Monitor and Plotter

PlatformIO

Colourful code editor, IntelliSence, Github support and rich of package extendable features
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:

VSCode: https://code.visualstudio.com/download

Atom: https://atom.io

Step 4: Install PlatformIO

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

Ref.: http://platformio.org/platformio-ide

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.

Settings

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.

Ref.: https://code.visualstudio.com/docs/getstarted/user...

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:

Select 'File' menu -> Open Floder
Select the project folder (you may create a new folder in the select folder dialog)
Open Command Palette and search 'PlatformIO init'
Wait a while for the init process
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)

Ref.: http://docs.platformio.org/en/latest/ide/vscode.ht...

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.

Open a new project folder called 'ble_hello_world'
Press Ctl + Alt + I shortcut key to initialize PlatformIO project
Select your ESP32 board
Modify 'framework = espidf' and append 'monitor_baud = 115200' in platformio.ini
Right click the 'src' folder and select 'new file' (all project source code should under this folder)
Input a file name, e.g. 'app_bt.c'
Copy the sample code from ESP-IDF Github (press raw button, select all, copy):
https://github.com/espressif/esp-idf/blob/master/e...
Paste the sample code to app_bt.c and save
Press 'PlatformIO: Build' button (left bottom corner)
Wait a while for build success (it require some time for downloading the firmware for the first build)
Connect ESP32 board
Press 'PlatformIO: Upload' button
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
Press 'PlatformIO: Serial Monitor' button
Reset ESP32 by pressing reset / EN button on the board
Serial Monitor should show advertising BLE signal
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: https://github.com/espressif/esp-idf/tree/master/e...

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.

Open a new project folder called 'oled'
Press Ctl + Alt + I shortcut key to initialize PlatformIO project
Select 'WeMOS LOLIN32' board
Modify 'framework = espidf' and append 'monitor_baud = 115200' in platformio.ini
Right click 'lib' folder in explorer panel and select 'new folder'
Input 'ssd1306' as the lib folder name
Download the ssd1306 lib source code from Github: https://github.com/imxieyi/esp32-i2c-ssd1306-oled
Copy files font*.*, i2c.* and ssd1306.* to the project lib ssd1306 folder
Copy main.cpp to project src folder
The finished folder structure should be like the above screen capture
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
build and upload
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.

Ref.:

https://github.com/espressif/esp-idf/tree/master/e...

https://github.com/EspressifApp/EsptouchForAndroid

https://espressif.com/en/products/software/esp-tou...