Like many people I have been playing with the Espressif ESP8266 WiFi modules over the last few months. I’ve had a couple of modules running for a while now, one connected to an Arduino pro mini clone with a 2×16 OLED display and one running directly on the ESP8266 using the NodeMcu Lua interpreter controlling a relay over an HTTP REST-like API.
One thing I was really hoping for was a native MQTT implementation as it is the protocol I use for my home automation and sensor network. Luckily tuanpm on the esp8266.com forums gave us a boxing day present in the form of a native MQTT client. MQTT on the ESP8266 means it will be easy to integrate input and output nodes in to my existing home automation and sensor network.
For a first test I just changed the MQTT and WiFi settings in user_config.h, tweaked the Makefile for my environment and compiled with the esp-open-sdk toolchain (currently with the 0.9.3 Espressif SDK, I need to update) and it compiled fine, I flashed it to the ESP8266 and gave it a test run on a busy MQTT topic (all my environmental sensors) for a day or so and it handled it without a problem.
The following day I hooked up a spare 0.96″ I2C OLED display and soon had it showing data from my sensors.
This demo is using the common ESP-01 variant of the ESP8266 board, available on eBay from Chinese sellers for around £2 each or a bit over double that from UK sellers. The downside of this module is that it only has two GPIO pins and we need both of those for the I2C and GPIO0 also to be grounded when we want to get into programming mode, a minor inconvenience but I also have some ESP-03 boards that I am working on a PCB for, as well as an ESP-12 and some ESP-WROOM modules that I got as a freebie from Espressif, all these have a lot more available GPIO pins.
The demo C code is available here, it’s hardcoded to my setup but it should get you going if you want to give it a try.
This code combines Tuan PM’s port of the MQTT client library for ESP8266 (itself ported from the library for Contiki), zarya’s ESP8266 I2C driver and the OLED driver found here.
It subscribes to three MQTT topics and displays them on the OLED (two temperature feeds and an info message on the bottom of the screen), the display I am using is this 0.96″ 128×64 White OLED but similar displays are widely available (plenty on eBay).
Configuration
I2C address for the OLED is in include/driver/i2c_oled.h
MQTT broker and WiFi settings are in include/user_config.h
GPIO pins to use for I2C are in driver/i2c.h
MQTT topics to subscribe to are in the MQTT_Start() function in user/mqtt.c
What to do with the incoming messages is defined in deliver_publish() in user/mqtt.c
If you want to add more than 3 topics you will need to change MQTT_SUB_TOPIC_NUM in user_config.h and the mqtt_topic variable declaration near the top of mqtt.c
I use Linux so I haven’t tested the Windows Makefile, it is as it comes with the MQTT demo but should work provided the SDK & tool paths are correct for your build environment.
Hardware wise it is just 3v3 to VCC and CH_PD on the ESP8266 and VCC on the OLED, ground on both and SDA on the OLED to GPIO2 and SCK to GPIO0.
This is just a quick demo for now but I’ve got a few ideas where it could be useful, I might do a custom PCB using the ESP-03 plus a regulator and maybe a DS18B20 sensor and a button or two.
Update 31/12/14: I was asked to add some more info on how to get this onto the ESP8266 for someone new to it so here is the complete process from installing the toolchain/SDK through to compiling and flashing to the ESP8266. I’ve done this from memory but I don’t think I’ve missed anything.
Make sure you have all the prerequisites installed, on Ubuntu 14.04 this can be done with:
sudo apt-get install make unrar autoconf automake libtool gcc g++ gperf flex bison texinfo gawk ncurses-dev libexpat-dev python sed
Grab the esp-open-sdk from the Github, either with git:
git clone https://github.com/pfalcon/esp-open-sdk
or download and unpack the zip
cd to the esp-open-sdk directory and do:
make STANDALONE=n
This will download all the necessary toolchain and SDK files and compile them.
Install the other esptool– There are two different tools called esptool and with the current Makefile you need both. esptool.py is a python tool that is used to flash the .bin files to the ESP8266 and is installed with the esp-open-sdk process above.
With the current Makefile you will also need the binary esptool from here, this one creates the firmware .bin files (esptool.py can create .bin files too, it just needs some changes to the Makefile).
Now back in the esp_mqtt_oled directory find the following lines in the Makefile to make sure they point to the location of the files you just installed:
XTENSA_TOOLS_ROOT ?= ../esp-open-sdk/xtensa-lx106-elf/bin
SDK_BASE ?= ../esp-open-sdk/sdk/
ESPTOOL ?= esptool.py
FW_TOOL ?= ../esptool/esptool
Also make sure the ESPPORT is pointing to the location of your serial adapter, eg:
ESPPORT ?= /dev/ttyUSB2
Connect the ESP8266 to your 3.3v serial adapter, RX on the ESP8266 to TXD of the adapter and TX to RXD
You need 3.3v to the VCC and CH_PD pins on the ESP8266 and ground to GND.
you also need to connect GPIO0 to GND during power on to get it into programming mode.
You will probably find that your serial adapter cannot supply enough power for the ESP8266, in that case you will need to power it from an external 3.3v source, disconnect the 3.3v from the serial adapter but make sure the ground from the power source and the serial adapter are both connected.
Now from esp_mqtt_oled directory do:
make
This will compile and build the firmware, you should get no errors but the Warning messages are normal (actually just info). You should now have a firmware directory with two files: 0x00000.bin 0x40000.bin
Then to flash these firmware files to the ESP8266 do:
make flash
Now disconnect GPIO from ground and back to SCL on the OLED and restart the ESP8266 (power off/on). Hopefully you should see some startup messages on the OLED now: “ESP8266 MQTT OLED” then “WiFi connected” then “MQTT connected” and finally data from the MQTT topics you defined in mqtt.c should start to appear.
You can also do “make test” to connect to the serial output with screen or use another serial app at 115200 baud, eg. minicom with “minicom -b 115200 -D /dev/ttyUSB2”
If you want to change anything and reflash it is just a case of doing:
make clean
make
make flash
Hopefully that will save anyone new to this some time.