Develop ESP32 With PlatformIO IDE

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

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

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

Version Upgrade

Arduino

1. Manual download from offical site

PlatformIO

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

Add platform support

Arduino

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

PlatformIO

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

Arduino

1. search and install in Library Manager

PlatformIO

1. search and install with 'pio lib' command

Platform and Library Update

Arduino

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

PlatformIO

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

IDE feature

Arduino

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

PlatformIO

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

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

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.

Ref.: http://platformio.org/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...

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.

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...

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.

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):

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

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: https://github.com/espressif/esp-idf/tree/master/e...

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: https://github.com/imxieyi/esp32-i2c-ssd1306-oled
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

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...