A couple of the sites which I list in the links section (see the menu to the right) have been singing the praises of PlatformIO in connection with ESP8266 development recently. Squix actually goes as far as propose using PlatformIO as part of a “Continuous Delivery” workflow for the ESP8266 (no, I didn’t know what it was either, but apparently it entails adding automatic testing to verify that a given release meets certain criteria before being released to the target device), while Jan Penninkhof was so impressed with PlatformIO that he put together a very nice “How To” video on getting started with it on the Mac.
But hold on, just what is PlatformIO and why would I want it? PlatformIO is a build system; it’s like “make” on steroids, as implemented by Superman, with help from Jethro Tull†. If you want to build a project for the ESP8266, PlatformIO will help you to do it by (for instance) downloading the toolchain automatically for you. If you decide you’d like to build for two disparate architectures (lets say ESP8266 and TeensyLC) you can just let PlatformIO know that at initialization time and it will magically download and install both toolchains and support when you first attempt to build the project. If you include libraries (via the normal “#include <whatever.h>” method) in your code, PlatformIO will help you find the latest version and automatically download any dependencies which your chosen library may have. Basically, if you’re a newcomer to the ESP8266 world, this is the easiest way to get started compiling and flashing. Don’t bother trying to follow the (mostly conflicting) instructions on the 50 odd (out-of-date) web sites on how to install the toolchain, or how to configure esptool for flashing, or how to set-up the Arduino-ESP environment… just install PlatformIO and let it do it all for you.
All in all, it looked like something worth trying to me, especially after Squix and Jan had explained some of the features in plain language (which is wonderful, because buzzword-laden sentences containing “framework”, “integration”, “extensible” and friends put my brain into deep-freeze mode). My main issue with anything “new” like this though, is usually my ageing primary work machine. I’m running a fairly ancient version of Elementary OS, which is based on Ubunt 12.04. Attempting to install anything written after the Magna Carta on this steady old workhorse usually results in a raspberry from the speaker as well as the normal, copious error messages about the kernel, libraries, disk spindle bearing and user all being past their “sell by” date. I’ve given up even trying to install anything which mentions “Java” anywhere in the description. PlatformIO though, is written in Python and although I’m not a Python programmer, I do know that the version installed on my system is quite a recent one, as the ESP8266 loader program required it. A quick check with “python –version” showed that it was actually 2.7.3. Almost all versions of Linux have some type of updater attached to the package-manager, so you should be able to update your system (no matter how ancient) to a recent revision of Python without too much effort.
Moving on to getting PlatformIO working, the next step is even easier. We now need to use the Python package installer, “pip”, to do the grunt work of adding PlatformIO itself. You can check to see whether “pip” is already available on your machine using a command such as “which pip” or “whereis pip“. If “pip” exists, they should return the fully-qualified location; something like “/usr/bin/pip“. If it doesn’t exist, you’ll need to use the system package-manager to add it (which might be as simple as “sudo apt-get install pip“) to install it. Assuming that “pip” is now available to you, simply do:-
pip install -U platformio
Note that the “-U” option comes after the “install” command. It forces pip to update the install target to the latest available version. And that, basically, is that! You now have platformIO installed on your ancient Linux system and it’s going to do all of the rest of the heavy lifting for you.
Now that you have it installed, you can create a work directory for your projects. I just made a PlatformIO directory directly under my home directory as an easy way to get started, but basically you can call it whatever you like (“work”, “projects”, “Eric-woz-ere” will all work equally well). What we’re going to do now is to create sub-directories in the work directory for each different project that you build. This is good practice anyway, but PlatformIO makes it almost essential, as it supports a metric ton of embedded processors (as well as their different toolchains), so one project might be built for the ESP8266, while the next might be for the STM32-Discovery and the one after that for the TI MPS430. PlatformIO will quite happily build each of your projects for a different processor (or even for multiple, different processors) if you want it to.
Okay, so to start off, we’re going to build a simple door-bell project for the ESP8266. Basically, this is going to be a battery powered project and, because it’s housed inside an enclosure attached to a wall, we want to enable OTA programming to allow us to update it without ripping the enclosure apart each time. We have some basic code already available which has been developed (to date) in the Arduino-ESP environment. Lets start…
mkdir DoorBell && cd DoorBell
mkdir ./src
cp ~/Arduino/DoorBell/DoorBell.ino ./src
cp ~/Arduino/DoorBell/user_config.h ./src
So, we’ve created the “DoorBell” sub-directory, changed into it and created a “src” directory, then copied over our code (and an include file) from the existing Arduino build tree into the new “src” directory. Now we need to tell PlatformIO which target processor we want to build this project for. You can get a (very long) list of the available targets using the “platformio boards” command. You’ll need to scroll up through the output to find the “Espressif” section. Most of the common ESP boards are in the target listing, including things like the Huzzah and NodeMCUv2; there are also some that I’d never heard of, such as the Phoenix and WifInfo (which seems to be this). I’m actually using the “esp12e” setting for my project (even though it’s just a generic ESP12 processor), with no ill effects. To implement your board choice and have platformio write it’s own, minimal configuration file for this new project, use the “platformio init --board=phoenix_v2” command (which, in this example, is setting the board type to “Phoenix V2” …replace this with your own choice).
The init command (above) will create a bunch of files and directories under your newly created project directory. The main ones are:-
- platformio.ini – The configuration file for this project instance.
- src – The directory where PlatformIO looks for the source code for this project.
- lib – The directory where PlatformIO will look for custom, local libraries which you might add.
We already created the “src” directory in our initial steps, above; that’s okay though, the “init” command will not overwrite an existing directory. The other contents of this newly initialized project directory can change, depending upon (for instance) which IDE you choose to use. As an example, if we tell PlatformIO that we want to use the “Eclipse” IDE, using “platformio init --board=phoenix_v2 --ide=eclipse“, we will end up with an extra “.settings” directory and “.project” file, both of which contain template information specific to the Eclipse IDE.
The platformio.ini file is fairly sparse at initialization time, but it is important. For instance, the default framework environment for the Espressif processor is “arduino”, but by editing your platformio.ini file you could change this to “simba” (that’s actually the only other valid framework available for Espressif targets). If you now start a compile with “platformio run”, PlatformIO will immediately go off and automatically download and install the Simba framework package for you, before kicking off the build of your project with a totally different framework (if you try this, please be aware that not all of the Espressif boards are supported by Simba, whereas most of them seem to be fine with the default Arduino setting).
This semi-automatic mode of operation is an intrinsic part of PlatformIO and does make life easier for the novice user. Another good example is when it comes to uploading your newly built code to the target board. When we start off, we don’t generally have any other option than uploading via serial. To kick-off the upload process, plug your ESP board into your computer, as normal and then use the command:-
platformio run -t upload
PlatformIO will go off and automatically detect your serial device (this works very well if you’ve already been using your system for programming an ESP board …if you’re starting from scratch in a clean environment, you might have to check the 99-platformio-udev.rules file settings – this is Linux-specific BTW), and upload to the ESP.
That’s it. You’ve just built and uploaded your project using PlatformIO.
Once your ESP board is up and running and connecting to the network, you can very easily change to using the Arduino-style OTA upload method by going back and editing the platformio.ini configuration file. Just add the line:-
upload_port=192.168.1.212
(where “192.168.1.212” is replaced by the actual IP address of your ESP board) to have PlatformIO alter its behaviour to the “upload” command to use OTA instead of serial. Of course, you need to add the Arduino OTA support code to your project file too, before this will work (see the example file BasicOTA.ino for the lines of code you need to add …the basic OTA functionality is already incorporated into the PlatformIO/Arduino libraries).
A word here on libraries. Normally we use libraries created by others to add functionality to our projects. A good example of this would be the PubSubClient library for MQTT. As you might expect, PlatformIO provides a method for handling third-party libraries like this and, naturally enough, one of the first things a new user needs to do is find the libraries needed for a given project. We can query PlatformIO for the MQTT libraries it knows about using:-
platformio lib search MQTT
This will return a numerically indexed list of libraries matching the keyword “MQTT”. Currently this returns 13 hits on my system. As it turns out, Nick O’Leary’s PubSubClient library is the first one in the list, with the reference number “89”. Okay, lets get PlatformIO to download and install it:-
platformio lib install 89
Note that we use the reference number, not the name. PlatformIO downloads and installs the library and adds it to it’s own database. What’s nice about this is that it will check every week or so to see whether the library has been updated recently and prompt you to refresh your installation if it finds that you’re not running the latest revision.
As you might expect, PlatformIO also runs the “latest and greatest” revision check on itself and will also prompt you to upgrade if you’re not at the latest rev.
I’m impressed! Since trying PlatformIO for the first time a couple of weeks back, I’ve been moving everything over to it. No more messing around with the horridible Arduino IDE. Yay!
† – The man, not the group. Implying that it does some basic, but essential stuff for you, not that you’re as thick as a brick.
esp8266hints 