DIY Projects

Getting started with PlatformIO IDE on VSCode (Windows, macOS, Raspbian, Linux)

install platformio vscode discover 1536x864 1

PlatformIO is an alternative to the Arduino IDE for developing connected objects or code for microcontrollers in a more general way. PlatformIO is not a code editor, it is a set of tools (toolchains) in the form of plugins for Visual Studio Code (or VSCode) from Microsoft and Atom from GitHub (also Microsoft!). VSCode is a lightweight and free code editor for Windows, macOS, Linux (32 or 64-bit).

 

PlatformIO is available as a plugin for many code editors (Atom, CLion, CodeBlocks, Eclipse, Emacs, NetBeans, Qt Creator, Sublime Text, Vim, Visual Studio, VSCode). The functionalities are identical whatever the publisher. I opted for Microsoft’s Visual Studio Code, a fast, free, cross-platform editor. You choose !

Install Visual Studio Code (VSCode) for Windows, macOS, or Linux

Go to the official VSCode page to download and install the version that fits your environment.

Install the PlatformIO IDE package for VSCode

VSCode has an extension manager (plugin) that can be opened via the View -> Extension menu or directly from the icon located in the sidebar.

VSCode works very similar to Sublime Text (good ideas are often copied …), you can also invoke the extension manager with the CTRL + P key combination (or Cmd + P under macOS).

Enter platformio in the search field.

Click on Install to start installing the plugin and dependencies.

Be careful, some extension developers use the official project icon which can be confusing. You can trust the title of the extension. Development environment for Embedded, IoT, Arduino, ARM mbed, Espressif (ESP8266 / ESP32), AVR, RISC-V, STM32, PIC32, nRF51 / nRF52, MSP430, MCS-51 (8051), FPGA, FreeRTOS, ESP-IDF, CMSIS, SPL

The installation process takes place in the background, it’s a bit confusing when you discover VSCode. A window located at the bottom right of the screen allows you to follow the smooth progress of the installation. This is quite rare, but if you have an installation problem (or a crash), simply relaunch VSCode to resume the installation process.

Small tip by the way, VSCode having an operation very similar to Sublime Text (good ideas are often copied …) you can also call the extension manager with the key combination CTRL + P (Or Cmd + P under macOS) .

Starting PlatformIO for the first time on VSCode

At the end of the installation, it is not necessary to restart the editor. The PIO home page opens in a new tab ➀. This page greatly slows down the start of VSCode and does not help. I advise you to disable its opening at startup by unchecking the Show at startup ➁ option.

A new icon in the form of an ant head appears in the sidebar ➂. It provides access to all the functions of PIO. We will detail them a little later.

Finally, a mini toolbar ➃ appears at the bottom of the screen. It is a light version of the PIO menu ➂. It combines the following functions

For those who prefer to use keyboard shortcuts, you can summon the palette with the key combination Ctrl + Shift + P (or Cmd + + P on macOS).

Then enter the keyword platformio to display all the available commands

The PIO menu

Let’s go back to the PIO menu which is the easiest and most complete way to use PIO. It is always accessible from the sidebar. It combines all the functions of PIO.

Here are the most useful commands:

Build compile

Upload compiles and uploads the program

Monitor opens serial monitor

Upload and monitor compiles, uploads and opens the serial monitor

Upload File System image uploads all files stored in the data folder (SPIFFS or LittleFS format)

Erase Flash empties the flash memory of the development board

Devices List connected devices

Clean clears the build folder

Update project libraries updates the libraries used by the project

Create a new project (ESP32 or ESP8266)

It’s time to move on to a small example to test it all out.

Open the PIO home window (if necessary) and click +New Project to open the wizard for project creation

Name the project then select the development board from the list. The list is impressive.

You can enter the first letters of the manufacturer (LoLin, TTGO), that of the board (d1 mini), the type (ESP32, ESP8266 …) to filter the development board.

Leave Arduino in the framework. Depending on your board, you can opt for another framework, but in this case you will have to refer to the latter’s documentation for programming.

Finally, choose the directory for creating the project. If you check Use Default Location, the project will be created in the Documents/PlatformIO/Projects folder. The directory name will be the name of the project.

Click on Finish to start the initialization of the project. The operation only lasts a handful of seconds.

Be careful not to use special characters which may interfere with the compiler

The project is now accessible from the explorer

The folder contains several folders and configuration files.

Warning, you must never intervene (delete, modify, move) the folders and the platformio.ini file otherwise you will no longer be able to compile your project.

Open the main.cpp file located in the src (source) folder. As you can see, you must declare the Arduino.h library when developing Arduino code in PIO.

<span class="token macro property">#<span class="token directive keyword">include</span> <span class="token string">"Arduino.h"</span></span>

<span class="token keyword">void</span> <span class="token keyword">setup</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token punctuation">}</span>

<span class="token keyword">void</span> <span class="token keyword">loop</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">{</span>
<span class="token punctuation">}</span>

Replace the code with the blink code and save the change

<span class="token macro property">#<span class="token directive keyword">include</span> <span class="token string">"Arduino.h"</span></span>

<span class="token keyword">void</span> <span class="token keyword">setup</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
   <span class="token comment">// initialize digital pin LED_BUILTIN as an output.</span>
   <span class="token function">pinMode</span><span class="token punctuation">(</span><span class="token constant">LED_BUILTIN</span><span class="token punctuation">,</span> <span class="token constant">OUTPUT</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
<span class="token punctuation">}</span>

<span class="token comment">// the loop function runs over and over again forever</span>
<span class="token keyword">void</span> <span class="token keyword">loop</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
   <span class="token function">digitalWrite</span><span class="token punctuation">(</span><span class="token constant">LED_BUILTIN</span><span class="token punctuation">,</span> <span class="token constant">HIGH</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// turn the LED on (HIGH is the voltage level)</span>
   <span class="token function">delay</span><span class="token punctuation">(</span><span class="token number">1000</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// wait for a second</span>
   <span class="token function">digitalWrite</span><span class="token punctuation">(</span><span class="token constant">LED_BUILTIN</span><span class="token punctuation">,</span> <span class="token constant">LOW</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// turn the LED off by making the voltage LOW</span>
   <span class="token function">delay</span><span class="token punctuation">(</span><span class="token number">1000</span><span class="token punctuation">)</span><span class="token punctuation">;</span> <span class="token comment">// wait for a second</span>
<span class="token punctuation">}</span>

Decryption of the platformio.ini file

Now let’s find out how to decrypt what the platformio.ini configuration file contains at the root of the project.

The strength of PIO is to be able to compile the same code (project) towards as many targets (development boards, MCUs) as one wishes. The configuration of each board is done by block which starts with the key env: between brackets, for example [env: esp12e] for the LoLin d1 mini.

You need 3 parameters to completely define a board:

<span class="token punctuation">[</span>env<span class="token operator">:</span>esp12e<span class="token punctuation">]</span>             
platform <span class="token operator">=</span> espressif8266   
board <span class="token operator">=</span> esp12e
framework <span class="token operator">=</span> arduino

We can then specify other parameters, for example

upload_port specify the COM port

upload_speed specify the baud transfer speed

monitor_speed serial monitor speed

More options here

To add a new development board, I advise you to directly retrieve the configuration of your board from the official WiKi rather than using the configuration wizard. Over 850 development boards are already listed.

You will not have to fumble to find the right settings as for this Heltec ESP32 dev board with LoRa connectivity which exists in 2 versions.

Compile from PlatformIO

Now that everything is ready, you can launch the creation of the build from the PIO menu

or from the tool palette

For some reason that still escapes me, the test and code verification (check) ends with an error message.

Unlike the Arduino IDE, it is not necessarily necessary to install the libraries before compiling. PIO takes care of everything as long as the dependencies are correctly indicated in the ini file.

A Terminal opens below the code and indicates the progress of the compilation. The compilation time is identical to the Arduino IDE.

If everything went without error, you should get a message from [success]

Linking .pio/build/esp12e/firmware.elf
Retrieving maximum program size .pio/build/esp12e/firmware.elf
Checking size .pio/build/esp12e/firmware.elf
Building .pio/build/esp12e/firmware.bin
Advanced Memory Usage is available via <span class="token string">"PlatformIO Home > Project Inspect"</span>
RAM: <span class="token punctuation">[</span><span class="token operator">==</span><span class="token operator">=</span> <span class="token punctuation">]</span> 32.7% <span class="token punctuation">(</span>used 26816 bytes from 81920 bytes<span class="token punctuation">)</span>
Flash: <span class="token punctuation">[</span><span class="token operator">==</span> <span class="token punctuation">]</span> 24.6% <span class="token punctuation">(</span>used 257212 bytes from 1044464 bytes<span class="token punctuation">)</span>
Creating BIN <span class="token function">file</span> <span class="token string">".pio/build/esp12e/firmware.bin"</span> using <span class="token string">".pio/build/esp12e/firmware.elf"</span>
<span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span> <span class="token punctuation">[</span>SUCCESS<span class="token punctuation">]</span> Took 32.26 seconds <span class="token operator">==</span><span class="token operator">==</span>

Check that the development board is correctly detected

On the Arduino IDE, just go to the Tools -> Port menu to find out if the development board has been detected.

On PIO, an equivalent function is available. Open the PIO home page and open the Devices tab. The boards are automatically detected and appear in the list (here on a Mac). If this is not the case, use the Refresh button to force the detection of devices.

As a reminder, if you have difficulty uploading the program to the board, it is possible to specify the port and the transfer speed in the configuration (see above)

Upload the program to the development board (Arduino, ESP8266, ESP32, STM32 …)

Everything is ready to upload the program to the development board. As before, the Upload method is accessible from the palette or from the PIO menu

PIO compiles the project, connects to the board and uploads the binary.

<span class="token operator">></span> Executing task <span class="token keyword">in</span> folder Demo ESP8266: platformio run --target upload <span class="token operator"><</span>

Warning<span class="token operator">!</span> Ignore unknown configuration option <span class="token variable"><span class="token variable">`</span>upload_serial<span class="token variable">`</span></span> <span class="token keyword">in</span> section <span class="token punctuation">[</span>env:esp12e<span class="token punctuation">]</span>
Processing esp12e <span class="token punctuation">(</span>platform: espressif8266<span class="token punctuation">;</span> board: esp12e<span class="token punctuation">;</span> framework: arduino<span class="token punctuation">)</span>
----------------------------------------------------------------------------------------------------------------------------------------------
Verbose mode can be enabled via <span class="token variable"><span class="token variable">`</span>-v, --verbose<span class="token variable">`</span></span> option
CONFIGURATION: https://docs.platformio.org/page/boards/espressif8266/esp12e.html
PLATFORM: Espressif 8266 2.5.1 <span class="token operator">></span> Espressif ESP8266 ESP-12E
HARDWARE: ESP8266 80MHz, 80KB RAM, 4MB Flash
PACKAGES: 
- framework-arduinoespressif8266 3.20701.0 <span class="token punctuation">(</span>2.7.1<span class="token punctuation">)</span> 
- tool-esptool 1.413.0 <span class="token punctuation">(</span>4.13<span class="token punctuation">)</span> 
- tool-esptoolpy 1.20800.0 <span class="token punctuation">(</span>2.8.0<span class="token punctuation">)</span> 
- tool-mkspiffs 1.200.0 <span class="token punctuation">(</span>2.0<span class="token punctuation">)</span> 
- toolchain-xtensa 2.40802.200502 <span class="token punctuation">(</span>4.8.2<span class="token punctuation">)</span>
LDF: Library Dependency Finder -<span class="token operator">></span> http://bit.ly/configure-pio-ldf
LDF Modes: Finder ~ chain, Compatibility ~ soft
Found 30 compatible libraries
Scanning dependencies<span class="token punctuation">..</span>.
No dependencies
Building <span class="token keyword">in</span> release mode
Retrieving maximum program size .pio/build/esp12e/firmware.elf
Checking size .pio/build/esp12e/firmware.elf
Advanced Memory Usage is available via <span class="token string">"PlatformIO Home > Project Inspect"</span>
RAM: <span class="token punctuation">[</span><span class="token operator">==</span><span class="token operator">=</span> <span class="token punctuation">]</span> 32.7% <span class="token punctuation">(</span>used 26816 bytes from 81920 bytes<span class="token punctuation">)</span>
Flash: <span class="token punctuation">[</span><span class="token operator">==</span> <span class="token punctuation">]</span> 24.6% <span class="token punctuation">(</span>used 257212 bytes from 1044464 bytes<span class="token punctuation">)</span>
Configuring upload protocol<span class="token punctuation">..</span>.
AVAILABLE: espota, esptool
CURRENT: upload_protocol <span class="token operator">=</span> esptool
Looking <span class="token keyword">for</span> upload port<span class="token punctuation">..</span>.
Auto-detected: /dev/cu.usbserial-1410
Uploading .pio/build/esp12e/firmware.bin
esptool.py v2.8
Serial port /dev/cu.usbserial-1410
Connecting<span class="token punctuation">..</span><span class="token punctuation">..</span>
Chip is ESP8266EX
Features: WiFi
Crystal is 26MHz
MAC: 5c:cf:7f:85:e6:20
Uploading stub<span class="token punctuation">..</span>.
Running stub<span class="token punctuation">..</span>.
Stub running<span class="token punctuation">..</span>.
Configuring flash size<span class="token punctuation">..</span>.
Auto-detected Flash size: 4MB
Compressed 261360 bytes to 192964<span class="token punctuation">..</span>.

Writing at 0x00000000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>8 %<span class="token punctuation">)</span>
Writing at 0x00004000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>16 %<span class="token punctuation">)</span>
Writing at 0x00008000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>25 %<span class="token punctuation">)</span>
Writing at 0x0000c000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>33 %<span class="token punctuation">)</span>
Writing at 0x00010000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>41 %<span class="token punctuation">)</span>
Writing at 0x00014000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>50 %<span class="token punctuation">)</span>
Writing at 0x00018000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>58 %<span class="token punctuation">)</span>
Writing at 0x0001c000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>66 %<span class="token punctuation">)</span>
Writing at 0x00020000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>75 %<span class="token punctuation">)</span>
Writing at 0x00024000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>83 %<span class="token punctuation">)</span>
Writing at 0x00028000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>91 %<span class="token punctuation">)</span>
Writing at 0x0002c000<span class="token punctuation">..</span>. <span class="token punctuation">(</span>100 %<span class="token punctuation">)</span>
Wrote 261360 bytes <span class="token punctuation">(</span>192964 compressed<span class="token punctuation">)</span> at 0x00000000 <span class="token keyword">in</span> 18.6 seconds <span class="token punctuation">(</span>effective 112.6 kbit/s<span class="token punctuation">)</span><span class="token punctuation">..</span>.
Hash of data verified.

Leaving<span class="token punctuation">..</span>.
Hard resetting via RTS pin<span class="token punctuation">..</span>.
<span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span> <span class="token punctuation">[</span>SUCCESS<span class="token punctuation">]</span> Took 23.11 seconds <span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span>

Frequent problems

Unable to upload

esptool.py cannot connect to the development board (ESP32, ESP8266…)

Looking <span class="token keyword">for</span> upload port<span class="token punctuation">..</span>.
Auto-detected: /dev/cu.usbserial-1420
Uploading .pio/build/esp12e/firmware.bin
esptool.py v2.8
Serial port /dev/cu.usbserial-1420
Connecting<span class="token punctuation">..</span><span class="token punctuation">..</span><span class="token punctuation">..</span><span class="token punctuation">..</span>_____<span class="token punctuation">..</span><span class="token punctuation">..</span>._____<span class="token punctuation">..</span><span class="token punctuation">..</span>._____<span class="token punctuation">..</span><span class="token punctuation">..</span>._____<span class="token punctuation">..</span><span class="token punctuation">..</span>._____<span class="token punctuation">..</span><span class="token punctuation">..</span>._____<span class="token punctuation">..</span><span class="token punctuation">..</span>._____

A fatal error occurred: Failed to connect to ESP8266: Timed out waiting <span class="token keyword">for</span> packet header
*** <span class="token punctuation">[</span>upload<span class="token punctuation">]</span> Error 2
<span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">=</span> <span class="token punctuation">[</span>FAILED<span class="token punctuation">]</span> Took 27.38 seconds <span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">==</span><span class="token operator">=</span>

Possible causes and remedies:

Unable to connect with Serial Monitor

By default, the serial port is configured at 9600 baud on the official extension. Jun Han added a parameter to set the speed. To use a different speed, open Terminal and run the following command pio device monitor -b 115200.

You can also specify the speed in the plaformio.ini file using the monitor_speed option.

How to disable PlatformIO extension ?

PIO can slow down the startup of VSCode. If you have one-time use, you can deactivate it from the extension manager. Activate it when you need the functionality of PIO. The loading is done hot, no need to restart VSCode!

Visual Studio Code is a very good alternative to the Atom editor. Very light, it starts much faster than Atom. It will also fit very well in a light configuration or a recycled PC running 32-bit Linux. You will be a little less guided than on Atom which remains PlatformIO’s official development platform. The SDK is very well documented, the grip is very fast.

Click to rate this post!
[Total: 6 Average: 5]
Exit mobile version