esp8266 with Homie and PlatformIO

As I talked about in previous posts, I got some ESP8266 devices I wanted to play with, one has been setup on a breadboard for testing for a while, able to boot, but never got to try anything more on it yet.

Protocol and firmware base choice

As my goal is to do some connected devices for home automation, I wanted to make firmwares for these that could talk to Home-Assistant. Even through HA supports quite a lot of way to talk to devices, there were 2 main options I considered:

  • http: simply having a http on the esp which exposes status, and can get commands via POST for example
  • mqtt: it is meant for IoT, the main drawback was I actually didn't want to run a broker

That's when I realized HA MQTT component has an embedded broker. Which apparently is not getting much love as everyone is using mqtt with HA for owntracks, and the embedded broken is incompatible with it. But given I don't plan on using owntracks myself for now, that should be sufficient for my need.

A large part of my fiddling for home automation has been triggered by Jan-Piet Mens and he actually loves MQTT, and played around with clients and told a few times (on twitter if my memory is any good) that Homie for esp8266 was well thought and stable, as I generally find his choices, advices and tastes to match pretty well mine, I decided to go for this.

So here we are, if all goes well, my esp8266 will be running a Homie based firmware to talk to home-assistant via MQTT.


Then the question of the tools arised, most of the things I read about esps were all talking about Arduino IDE, which I found comments before even trying it, saying to sum it up, as working, but not great. For those who know me, you know I don't like UI, graphical interfaces, and mouse compliant interfaces. I was not trilled to have to use this.

There is quite some talk about esptool which apparently is a great command line tool written in python to flash you esps. That could have done it, but as a complete beginner in all this, I had no clue how to build a project to create the firmware before flashing it with esptool.

Homie github README talks about PlatformIO. I had no clue what this was, and one of the first thing you notice on their webpage is the IDE word, and screenshot of Atom sporting a toolbar to interact with PlatformIO. But after discading it in the first place, and coming back to their website and taking some time to actually read things, I noticed: PlatformIO is an open source ecosystem for IoT development. There is an IDE, but it is more an ecosystem, and everything can be done from the command line, and that was a lot more appealing to me, so I went for it.


Being a python project, you can install it via pip, some python -c directly from curl as suggested in the Super-Quick Installation Guide.

I went with archlinux's AUR package, there also is a -git one, if need arises later on.

Once installed I went through this page and followed their example:

platformio init --board nodemcu

The nodemcu are based on ESP12s, as I own an esp12f, and I read somewhere it was generally working pretty fine with nocemcu as a board, I decided to go for it.

The previous command create an .ini and a lib and src folders. There also is a .pioenvs folder that contains everything PlatformIO will need to build your project, libs, the output binaries etc.

Then as explained on Homie's getting started guide I installed the lib, given I'm a bit curious I looked it up before typing what the doc suggests.

platformio lib search homie
platformio lib install 555

I then dropped the so called Bare mininum sketch

#include <Homie.h>

void setup() {

void loop() {

in src/test.c, and tried to compile using the command:

platformio run

But that failed because of missing PubSubClient.h in Homie includes, as PlatformIO is said to handle depedancies, that surprised me but well, whatever:

platformio lib search pubsubclient
platformio lib install 89

Then tried to compile again... this time a real compilation error arised:

In file included from .pioenvs/nodemcu/Homie_ID555/Homie/MqttClient.hpp:3:0,
from .pioenvs/nodemcu/Homie_ID555/Homie.hpp:3,
from .pioenvs/nodemcu/Homie_ID555/Homie.h:4,
from src/test.c:1:
.pioenvs/nodemcu/ESP8266WiFi/ESP8266WiFi.h:27:8: error: expected identifier
or '(' before string constant
extern "C" {

Given the presence of .hpp in the error, and the extern "C" section I guess I should not be assume I'm writing C, so I move src/test.c to src/test.cpp, launched the compilation, and this time it built fine.

If you have your FTDI adapter plugged in, and your ESP in flash mode, you can add --target upload to the run command line, and PlatformIO will flash your device for you.

I simply wired GPIO0 to GND and rebooted the esp, launch the run with upload flag, and my esp was flashed. I then rewired GPIO to VCC and rebooted, and the AP from Homie's configuration mode showed up in my phone wifi... I didn't yet took the time to configure it via json and test it further.

But that's already a good starting point, and that's it for now!