How to Use PlatformIO Core?
Friday, January 7, 2022 • 6 minutes to read
PlatformIO provides an integrated development environment for developing embedded solutions supporting, as of the start of 2022, 51 platforms and 28 frameworks for over 1000 different boards. It is called PlatformIO IDE, and in my opinion, it is the best free and open-source solution for developing embedded solutions. Especially in comparison to such bad products like Arduino IDE.
Why should you bother? The embedded world comes with the complicated process of setting up your environments, different toolchains, platforms, and libraries. In addition, dependencies differ between development boards and micro-controllers. PlatformIO helps conquer that mess.
What is the difference between PlatformIO Core vs. PlatformIO IDE?
Why did I put PlatformIO Core instead of IDE in the title? PlatformIO IDE is PlatformIO Core plus plugins and extensions for a couple of popular, existing IDEs. The default download configuration is bundled with VSCode but could work with other multi-platform IDEs. In the end, what those plugins and extensions do, are run PlatformIO Core commands in the background.
Understanding how to use PlatformIO Core without IDE plugins will help you use it with any IDE of your choice or in continuous integration and deployment jobs, automated tests, or any other automated tasks. You could also use this platform remotely.
How to install PlatformIO Core?
PlatformIO Core is a Python application, so obviously, it requires Python on your local or remote machine. I assume you already have it or at least know how to install it. The current version of PlatformIO Core, which is 5, requires Python in version 3.6 or newer.
As the PlatformIO Core is a Python program, you can install it in many ways, but you should probably use pip for it. I do it by using a virtual environment, so there is no global installation, and if necessary, I can use different versions or setups.
We create a virtual environment in the .platformio directory in the user’s home directory. Then activate it and install platformio using pip. The following command would be enough for Linux-like systems or WSL on Windows.
python3 -m venv ~/.platformio/penv
source ~/.platformio/penv/bin/activate
python3 -m pip install -U platformio
For Windows, using PowerShell, you should use the following commands.
python3 -m venv $env:userprofile\.platformio\penv
~\.platformio\penv\Scripts\activate.ps1
All PlatformIO Core commands that I describe should run inside a virtual environment. It is enough to navigate to your project’s root directory and activate the virtual environment. The commands are environment-independent.
How to initialize a project using PlatformIO Core?
Create and navigate to your new project directory. From there, activate the virtual environment. To initialize a new PlatformIO Core project, you will need to run the pio init command and provide a board ID as an argument. For example, pio init -b nanoatmega328 will create a popular Arduino Nano board project.
By initializing the project, you will create the directory structure and the basic platformio.ini configuration file. For example, the configuration file looks like the below for the command above.
[env:nanoatmega328]
platform = atmelavr
board = nanoatmega328
framework = arduino
How to find PlatformIO board ID?
To find a development board ID in PlatformIO, use the pio boards command. As an argument, you should provide a text query, like pio boards nano or pio board atmelavr. Try keywords, microcontrollers names, vendors, and common names to get the best results.
How to build and upload your project?
Building a project is very straightforward as the PlatformIO will install and keep track of every building requirement, toolchains, and framework. Then, all you need to do is run the pio run command inside your project root directory.
Uploading your project is also easy, but you need to know where to upload it. First, you need to connect your development board, ISP over a USB circuit or similar to your computer. Then with pio device list, check if your device is on the list. If not, install the correct drivers.
If you have only one device connected to your computer, it would be enough to run pio run -t upload. If there is more than one active device, add the desired port as an argument, like pio run -t upload --upload-port USB3.
How to read serial port using PlatformIO Core?
It is not uncommon while developing an embedded solution to read data sent by a device over a serial port. There is, of course, a command in PlatformIO Core to read that serial port messages. It has many encoding and transformation features, including RTS/CTS and software flow control, end-of-line modes, and filtering.
Using the default configuration values, you need to run pio device monitor to activate it. Otherwise, you can change port number or name, baud rate, or parity bit mode. For example, pio device monitor -b 115200 -p USB3 --parity=E will use port USB3 with a speed of 115200 bauds and even parity bit mode.
How to search for and add libraries for your PlatformIO projects?
PlatformIO supports over twelve thousand different libraries used in embedded projects with the current version. In addition, it provides a couple of commands for libraries management like pio lib search, and pio lib install, or pio lib update.
You can query available libraries by the owner, author, name, keywords, framework, platform, or all. Let’s take as an example a library for the BME280 sensor. Searching for the BME280 related libraries is very easy. The command looks like that: pio lib search bme280. We will get tens of results in this instance, and we need to narrow them down. We are using an Arduino framework on the Atmel AVR microprocessor, so the following query to pio lib search bme280 -f arduino -p atmelavr will return more accurate results.
Every search result has an ID next to it. To get more details about the library provided by its authors, run the pio lib info command. When you decide that this is the one, run pio lib install, followed by ID, to add the library to your requirements. PlatformIO Core will take that into account during the next build. Our updated configuration file now looks like the following.
[env:nanoatmega328]
platform = atmelavr
board = nanoatmega328
framework = arduino
lib_deps = adafruit/Adafruit BME280 Library@^2.2.1
What next?
There much more options to manage your project requirements and configuration. I did not mention anything about environments and simultaneously building your project for multiple boards or frameworks. Those topics are big enough for their separate articles. Give PlatformIO a try now and discover its all features at your pace.