3 min read

Quick start guide to flashing ESP8266-based devices with PlatformIO

If you’re into IoT, you’ve probably heard of PlatformIO - an integrated development environment for IoT similar to the Arduino IDE.

A lot of the IoT devices run on the low-cost ESP8266 chip. It can be found on a range of applications, from power meters to switches, sensors and even LED controllers. They are very popular in the DIY community but also commercially available in the form of ready-to-use products and development kits from several manufacturers, such as IteadStudio, makers of the Sonoff product line, Wemos, known for its D1 Mini and MagicHome LED Controllers, to name a few.

The original firmware that these devices come with, besides being proprietary, hasn’t been satisfactory for most IoT tinkerers. They lack support for other sensors and also miss controls and features one would like when connecting them too home automation systems, such as support for MQTT, REST APIs, Over-The-Air (OTA) updates and so much more.

Three widely popular open-source ESP8266 firmware alternatives with a focus on Sonoff products (but not exclusive to) are ESPurna, Sonoff-Tasmota and ESPeasy. Besides using PlatformIO, they all have in common a passionate community which dedicate a lot of their time adding support for new sensors and features. Their documentation is also really good.

If you would like to try any of these firmwares, you will need to flash your device using a USB-to-UART programmer. You can get acquainted about which pins to connect to by reading ESPurna’s Wiki.

After connecting your device, install platformio using Homebrew:

❯ brew install platformio

Clone the ESPurna repo and checkout the most recent tag:

❯ git clone https://bitbucket.org/xoseperez/espurna.git
❯ git checkout $(git describe --tags)
❯ cd code

ESPurna comes with preconfigured device environments as listed under platformio.ini. It also offers some variants such as dht which bundle support for specific sensors (in this case, temperature and humidity).

For the first firmware flash, the regular variant should be used. Take the case of a Sonoff Basic.

Connect your device to your computer, put it in flash mode and run the pio command. It will download all dependencies, compile them, automatically detect the USB-to-UART programmer and upload the binary image to the device.

❯ pio run -t upload -e itead-sonoff-basic

The procedure is very simple and takes about a minute to complete.

Over-The-Air (OTA) Updates

Most of these firmwares offer some kind of OTA update. Some require uploading a binary image directly through their HTTP interface while others bundle built-in functionality for remote downloading firmware images which is pretty cool for automating updates.

ESPurna does it a little bit different by offering a special OTA environment for each device. For instance, if you would like to update your Sonoff Basic after flashing ESPurna once, then you could just do:

❯ pio run -t upload -e itead-sonoff-basic-ota

This, of course, assumes that you left all configurations values to their defaults - that is IP and authentication password. Since hopefully that isn’t the case, then there is a generic OTA environment which reads environment variables from your shell. This way you can dynamically configure your device information without having to change values directly on the platformio.ini file.

Export the shell variables:

❯ export ESPURNA_BOARD="ITEAD_SONOFF_BASIC"
❯ export ESPURNA_IP="192.168.10.1"
❯ export ESPURNA_AUTH="foobar"

Then run pio using the generic environment:

❯ pio run -t upload -e esp8266-1m-ota

On a last note, if you’re not into flashing through serial mode (required for the first flash), there is a new and exciting project that attempts to flash the Tasmota firmware using the original OTA mechanism of the Sonoff via WiFi - SonOTA. Something to explore in the future!