Using PlatformIO for your Arduino projects

Lately the default Arduino IDE has been bugging me more and more. So I decided it was time for an alternative. A couple of months ago I tried PlatformIO. It wasn’t the best back then. I think it was in it’s early stages of supporting the Arduino hardware and so on. So recently I decided to go nuts and install it again to see what has changed…

I was very surprised to see it actually made vast improvements over the last version (where I couldn’t even get a library integrated in a sketch…). My goal at this point is to have a cross-platform development solution where I don’t have to fiddle with too much libraries and such things and it needs to look fancy. Well, mission accomplished!

So, here are a few pointers for configuring the PlatforIO editor (based on Atom, b.t.w., incredibly powerful text editor) to get you started without too much of a hassle and thinking about libraries and such.

I assume you all know how to install software, so we’ll skip that. After you opened up Atom for the first time there will probably be a few updates (check the bottom right corner). If you install all the updates it will require several restarts of Atom, so don’t go updating in the middle of coding.

It may ask you to install a couple of side dishes like Clang, Python and maybe some more. You need to install those too! But every time it needs something it gives you a link to the download page, very user-friendly! Also, some are absolutely essential (like Python) and some (like Clang) are there for neat code completion and so on.

Anyway, after all updates you’ll be confronted with the start screen, it should look somewhat like this:

So, there you have it! There are a couple of key differences between the Arduino IDE and the PlatformIO IDE (actually, it’s a plugin for Atom). First of all, it’s so much more flexible in the way you setup your projects. You can have a different set of libraries for each project or global ones. This way you can easily test new versions of libraries.

Now, when you click “New Project” it has a couple of questions for you:

Now comes the really good stuff. You can choose several boards here! With this feature, you can cross compile for different platforms at once. If you are into serious Atmel programming (or ESP’s) this may come in handy. What’s more, you can specify different libraries for each board in the same project (more about that later).

So, we choose a board and a directory where to store it. The directory structure will be a bit different from what we are used to, but you’ll adapt (as the Borg say):

After you click “Process” it will download some files for the avr platform and you will see the created project on the left:

You’ll notice a couple of things, there is lib directory, a src directory and a couple files. Of course, this plugin has support for Git but I don’t know anything about that, so we’ll skip that for now ;-).

One of the nicest things about this is the “platformio.ini” file. This file stores all the settings for your project. If you click on it, it will open the file and you can see there is already something configured for you:

It’s the basic settings for configuring the avr compiler to actually know what to compile for. You can add more environments here (which would’ve been the case if we had selected more than one board), but for the purpose of this post it’s not really relevant.

Now, we all know the Arduino has a couple of default libraries on board like Wire. The PlatformIO IDE has those too, so we don’t need to worry about those. What we do need to worry about are the regular libraries we use for all our projects. What is also important to know, the PlatformIO IDE has a bad way of dealing with nested libraries (or maybe the developers of the libraries are bad, I don’t know, either way, we are gonna solve it).

There are several ways to go about this library thing:

  1. Add each library for only your current project
  2. Use the Arduino (or any other) library folder for all the projects
  3. Mix them up all together

Because I personally work on two platforms (Mac and Windows) I’ve decided to put all my Arduino libraries on my Google Drive and link them from there. The only way to achieve this is with environment variables. PlatformIO has a bunch of environment variables it listens too. You can use those to setup the whole thing as you like.

For the libraries, we only need to worry about one: PLATFORMIO_LIB_EXTRA_DIRS. This one will be pointed to the location of our libraries on, in this case, my Google Drive. In Windows it looks like this:

And on the Mac, well, it’s Linux, export etc.

After this has been done any old code with the libraries should be able to be build. So, we are gonna add a source file in the, how’d you guess, src folder. Right-click the src folder and choose New File. You can name it any way you like. If you want to retain compatibility with the Arduino IDE I’d suggest you just name it with the extension INO, like so:

Now press enter, ét voilá, a new file has been born! Now you can go about and produce your brilliant code for the thing you are trying to do. So, now we have some brilliant piece of code, something like this (mind you, D1 as an alias for pin Digital 1 doesn’t exist, so it’s just 1, A0 does exist of course):

Now you go to the platformio Menu and click “Build”. This compiles the code for you, but nothing more. You will notice in the bottom part some text will fly by, just like the Arduino IDE, with warnings and such. If you choose “Upload” it will upload it to the Board, if it’s attached to your computer. In most cases, it can decide for you on which port the Board is, but if not, don’t worry, you can change that in the platformio.ini file, like so:

Note though, that the names of the ports differ on Mac and Windows, so I guess I’m stuck on Automatic choosing, but so far it works great. If you need more libraries for this project, but just this one, you can add another line:

The lib_extra_dirs directive can be placed here too. So now it will know to look there too.

In my endeavors to make it cross platform, I ran into another library thing. If you deep link libraries (from one to the other, with #include and such) it’s possible that the compiler cannot find all the libraries it needs because the dependencies are “missing”. What it actually is, the compiler stops looking after it runs into one link. To fix this, change the platformio.ini as follows:

Unfortunately, there is no environment variable for this (lib_ldf_mode), so I think I’ll make it a habit to just add this line to whatever project I’m doing since creators of libraries often don’t care about this problem.

One more thing to know about environment variables versus the platformio.ini directives. The environment variables take precedence over the ini files!

Well, I do hope this has been informational and that you will give this a chance. It’s looking way better than the Arduino IDE and the support for the boards is also very advanced at this moment. Enjoy!