Arduino & ESP32 programming with PlatformIO and Visual Studio Code

The Arduino IDE can't do much, and that's a good thing. It was designed to keep the barrier to entry into microcontroller programming as low as possible and not to overwhelm beginners with too many features.

I admit, I'm a professional developer. And I miss a few features in the Arduino IDE that make programming more fun and my work easier. That's why the Arduino IDE isn't enough for me.

Instead, I use PlatformIO!

Note: This text is more of a transcript of the video. Without the video, the steps are hard to follow.

Key Facts

What Is PlatformIO?

PlatformIO is a free tool made specifically for programming microcontrollers.

PlatformIO is a plugin that you install in VS Code. VS Code is a free IDE by Microsoft.

PlatformIO supports hundreds of microcontrollers, such as various ESP32 and Arduino boards.

Because PlatformIO runs in VS Code, you get a powerful development environment with far more features than the Arduino IDE.

René Aye Head of Short Circuits @ raydiy

Keeps his herd of microcontrollers supplied with power and lovingly crafted code.

RAYDIY Newsletter

Subscribe now

and get a free eBook!

What Is PlatformIO

PlatformIO is a free tool made specifically for working with microcontrollers like the ESP32 or Arduino.

It is installed as a plugin in the Visual Studio Code editor (VS Code for short), which is also free.

Because we work with VS Code, we get a very powerful development environment with many more features than the Arduino IDE.

By the way: Visual Studio Code is not the same as Visual Studio (without Code), Microsoft's large software development platform. I find the very similar names a bit unfortunate.

Installing PlatformIO

Now let's install VS Code. Then I'll show you how to install the PlatformIO extension in VS Code. And following my video where I compare Arduinos and ESPs, I'll show you how to upload a program to an Arduino and to an ESP32 with PlatformIO.

First we need to download VS Code for your operating system. Use this link: Visual Studio Code

I recommend the stable version of VS Code.

To install PlatformIO, we go to the Extensions area, basically an app store for VS Code extensions. There we search for the official PlatformIO extension, click Install and wait for the installation to finish.

You may get pop-ups recommending additional plugins. These are plugins for the C/C++ programming language. Since the Arduino framework uses C++, installing these additional plugins makes perfect sense.

A First Project

Creating an Arduino Project in PlatformIO

Now we create a first project in PlatformIO for the Arduino UNO board.

To do this, we go to the PlatformIO Home page and click New Project.

In the form, we enter a project name, select the Arduino UNO as the board and Arduino as the framework.

I always leave Location on default, that's the easiest for now. If you hover over the question mark, the default location is shown. For me, that's my user folder/Documents/PlatformIO/Projects/.

Click OK, and the project is created.

PlatformIO projects are structured a bit differently than in the Arduino IDE. So let's first take a look at the folder structure of the empty project.

We can ignore the TEST folder for now. You only need it if you want to work with unit tests.

SRC contains all source code files. This is also where our main.cpp lives, basically our main program.

INCLUDE can be used to store header files.

And LIB is used for project-specific libraries.

The platformio.ini is the configuration file for PlatformIO projects. We'll take a look at it later.

For now, we're only interested in the SRC folder, because that's where the main.cpp is, which we now open with a double click.

PlatformIO already fills the main.cpp with the setup() and loop() methods.

Also, the Arduino.h library has to be included at the very top. The Arduino IDE does this automatically in the background.

I paste the same code here that I used in my video where I compare Arduino boards with ESP boards.

Now let's look at these inconspicuous but important buttons at the bottom of the window.

These are the buttons that belong to PlatformIO.

The house icon opens the PlatformIO Home page.
The checkmark icon checks the current code for errors.
The arrow icon also checks the code and, if no errors are found, uploads the current code to the board.
The trash can deletes all libraries that have already been compiled. They are then recompiled on the next check or upload. This way you can force a recompile.
The plug icon opens the serial monitor.
And the last icon opens a shell, for example if you want to run PlatformIO or shell commands manually.
The two areas on the far left are only relevant for Git and version control.
And the button in between lists errors and warnings and shows them in an overview when clicked. This lets you jump quickly to specific errors in the code.

The bottom right is also interesting:

It shows the cursor position.
And you can set the size and type of indentation in the code.
If you change this value, you should run Format Document afterwards. To do this, right-click in the source code and choose Format Document.

Now we can upload the code with the arrow icon. And we see our LED blinking. Hooray!

And Once More with the ESP32

Creating an ESP32 Project in PlatformIO

Now we repeat the whole thing with an ESP32. Before I disconnect the Arduino, let's take a quick look at the Devices area of PlatformIO.

It shows all boards PlatformIO has detected. It always shows me the Arduino UNO as /dev/cu.usbmodem14101. On Windows, you'll see COM ports here instead.

Now we connect the ESP32 and click Refresh.

Two more USB ports now show up in the device list. Don't ask me why there are two. But I know that /dev/cu.SLAB_USBtoUART is the right port for the ESP32.

The two ports will cause a problem in a moment. So I'll show you how to deal with that.

First, let's create a new project.

We enter a project name, and as the board I pick the generic Espressif ESP32 Dev Module. If your exact board is listed here, I would choose that one.

As the framework we choose Arduino again, of course.

We open the main.cpp and paste our Blinky code into it.

Click Upload, and ... we get an error.

The error message also shows what happened: PlatformIO tried to upload the code to the wrong USB port. PlatformIO doesn't know which of the two ports is the right one and picked the wrong one.

But we can solve this problem with the project settings.

Go to Projects in PlatformIO, find the right project in the list and click Configure.

You should see a tab called esp32dev.

We need to add an option named upload_port.

To do this, I type the word port into the New Option field.

PlatformIO then shows a list of all options containing the term port.

I choose upload_port.

A new field upload_port is added, and the cursor should automatically blink in that field.

Now we can simply click into this new field and get a list of all USB ports that were already shown in the Devices area.

Here we select the /dev/cu.SLAB_USBtoUART port and, very important, click Save at the top right.

On Windows, this will be a COM port. There you have to watch the Devices list before and after connecting the boards.

If we upload our code now, everything should work.

Declaring and Defining C/C++ Functions

PlatformIO sticks to proper coding standards, while the Arduino IDE does some things for us. Adding the Arduino.h header file is one example.

Another important point is declaring functions.

Let's take the code from the loop(), put it into a function and call this new function in the loop() instead.

If we now run the Code Check, we get an error. The problem is that our new function has not been declared yet.

In C/C++ you have to declare functions, that is, announce that this function exists at all.

In the Arduino IDE this was no problem, because it automatically searched the main file for functions and declared them for us under the hood.

If you keep working with just one main.cpp, there are two simple options: either declare the functions correctly before they are used.

To do this, you simply take the function name including the return type and write it once near the top, before the function is used.

Or you put setup() and loop() last in the code, below all function definitions.

The code of the function itself is the function definition.

Announcing a function before its first use is the function declaration.

Helpful Features and Advantages of VS Code

Now of course the fair question: Why do we do all this if the Arduino IDE makes things more convenient for us?

I'd say once a project reaches a certain size, the Arduino IDE gets confusing. As soon as you have several functions or even your own classes spread over several files, the Arduino IDE is no fun anymore.

Here are a few helpful features the Arduino IDE currently doesn't have (as of February 2021):

Intellisense

Where exactly Intellisense starts and ends is still not entirely clear to me. For me, it's the helpful suggestions when I start typing a command or function name. And also the parameter suggestions that are shown. Or the function descriptions.

Go to Declaration/Definition

You can right-click a function and jump straight to it with Go to Definition or Go to Declaration. This works with variables too, by the way.

And Go to References lists all occurrences of a function or variable.

Peek basically does the same, but doesn't leave the current file. Instead, it shows a preview at the current cursor position.

Rename Symbol

Rename Symbol is very handy if at some point you're unhappy with a variable or function name. It changes all declarations, definitions and calls in one go. In other development environments this is also called refactoring.

Comments for function descriptions in Intellisense

One last tip: how to get your function descriptions into Intellisense.

If you write the documentation of a function with certain keywords and a certain syntax, it is shown in Intellisense, for example when you hover over a function name.

This works according to a standard called Doxygen. I'll put a link to more keywords in the link list at the end of the article.

Outro

That brings us to the end of this PlatformIO intro. We installed Visual Studio Code and the PlatformIO extension.

We looked at the project structure and covered a few important differences compared to the Arduino IDE.

We saw how to use PlatformIO's project settings to fix upload problems with the USB ports.

We did a short Blinky test with an Arduino and an ESP32 board. And finally we learned about some helpful PlatformIO features that make programming easier.

I hope I could convince one or two of you to give PlatformIO a try. Have fun and stay healthy!

ESP32 DevKit C by AZ-Delivery^*