Wi-Fi is an essential bit of kit for any Internet of Things (IoT) DIY projects, but our favorite Arduino doesn't come with Wi-Fi, and adding in a Wi-Fi shield can bring the total cost to around $40. What if I told you a there's an Arduino-compatible dev board with built-in Wi-Fi for less than $10? Well, there is.

Meet the Arduino Killer: ESP8266. It was only a matter of time before the crown was stolen from the shiny head of our dear Arduino development board. Is it possible to fall in love with a circuit board?

Catchy names aside, the ESP8266 (also known as NodeMCU) was originally marketed as a low cost Wi-Fi add-on for Arduino boards, until the hacker community realized you could cut the Arduino out of the equation entirely.

In less than a year, the ESP8266 has rocketed in popularity, and is now so well supported and developed that if you're currently using Arduino, you need to stand up and take note. Buy one now, then follow along with this guide to get started programming your ESP8266 – all from within the familiar Arduino IDE.

You're not limited to using the Arduino IDE of course – they're compatible with Lua too (which looks like a slimmed down Python to my novice eyes), but since we're tackling this from the perspective of those us who have learnt on Arduino, that's what'll we cover exclusively today.

There's quite a few models of ESP8266 around now, but I'm going to go ahead and recommend this one: ESP-12E (also known as NodeMCU 1.0, or it's newest sibling NodeMCU 2.0).

It's a little more expensive than the others ($6.50 compared to $4!), but includes the serial driver needed to program the chip, and has a built-in power regulator, as well as lots of IO pins. It's widely supported and really doesn't need anything apart from a USB connection for programming or power, so it's the easiest to work with. If you buy any other kind of ESP8266 board, you may need a separate 3.3v power regulator, and a suitable FTDI connection for programming.

Getting Started with ESP8266-12E and Arduino

First, install the serial drivers [Broken URL Removed] for this board. You may need to disable KEXT signing if you're running El Capitan due to new security systems.

Next, we need to enable support for ESP8266 from the Arduino IDE's board manager. Open up Preferences, and enter the following URL where it says Additional Board Manager URLs:

arduino board manager URLS

Hit Ok, then open the Boards Manager from Tools -> Board menu, search for esp8266 and install the platform. You should now see a choice for NodeMCU 1.0.

select board

Leave the CPU and upload speed as is, and select your newly install serial port. On Mac, this appears as cu.SLAB_USBtoUART.

As a first program, I'd suggest the simple Wi-Fi scanner – find it from File -> Examples -> ESP8266WiFi -> WifiScan. Note that it's quite slow to upload, but eventually it'll say "done uploading" and at that point (not before, or you'll break the upload process), you can open the Serial monitor. You should see something similar to this:

wifi scan test esp8266

Success! Now, let's try connecting to one.

Here's an absolutely simple barebones code for connecting to a Wi-Fi network. It doesn't do anything other than just connect, but it's something you can add too later. Just remember to change the YOUR_SSID and YOUR_PASSWORD to your Wi-Fi details. Upload, open the Serial console and you should see it connecting.

        

#include 
const char* ssid = "YOUR_SSID";
const char* password = "YOUR_PASSWORD";

WiFiClient wifiClient;

void setup() {
  Serial.begin(115200);
  Serial.print("Connecting to ");
  Serial.println(ssid);
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(500);
    Serial.print(".");
  }
  Serial.println("");
  Serial.println("WiFi connected");
  Serial.println("IP address: ");
  Serial.println(WiFi.localIP());

  
}

void loop() {
  
}

Isn't it great how ridiculously simple that was?

Before we carry on, here's the pinout diagram – it might come in handy later. Note that the pin numbers referred to in code are the GPIO numbers, not the D0-16 probably written on your board PCB. If you absolutely, positively cannot figure out why a sensor isn't working, you've probably mixed the pin numbers up.

NodeMCU__v1.0_pinout

Quick Smart Home Sensor with MQTT and DHT11

Here's a practical example you can put to use straight away to monitor your home. We'll be adding a DHT11 temperature and humidity sensor, then reporting the values using the MQTT protocol over the Wi-Fi network, in my case to an OpenHAB DIY home automation system (if not, you might want to read our beginners guide to getting OpenHAB up and running on a Raspberry Pi, and part 2, which deals specifically with installing an MQTT server).

On the wiring side, connect the DHT sensor to GND, 3.3v, and ~D4 (or GPIO 2). That's all we need for now.

Download these MQTT and DHT libraries. Even if you already have them, download these ones anyway, backup what you have, and overwrite with these. The latest DHT11 library from Adafruit uses an automatic algorithm for determining the speed at which data is read from the sensor, but it's buggy on ESP8266 and 90% of the time results in failed readings.

With the old version 1.0 of the library I've included in the download, you can manually change the timing: 11 works best for these ESP2866 boards. I also went through many copies of the MQTT library trying to find one a good callback function, finally landing on the one included. You'll need to restart the Arduino IDE after replacing these.

Here's the complete code for the project. At the top are all the variables you need to change, including Wi-Fi details, MQTT server (a URL can be used instead if using a cloud server, though there's no authentication in place), and channels to publish data on.

Here's how it works and a few notes:

  • First we connect to the Wi-Fi, then to the MQTT server, then begin the main loop().
  • In the loop, we poll the DHT sensor every 60 seconds and publish readings to the relevant MQTT channels. Again, if you find most of the readings results in a failure message, you have the wrong version of the DHT library – downgrade to v1.0.
  • client.loop() passes control to the MQTT library, allowing it to react to incoming messages.
  • There's a messageReceived() function where we handle incoming messages – just do a simple if statement to compare the payload with the message you're expecting. You could use this to activate a relay, for instance.
  • After running these for a few days, I found they would randomly stop working – I assume this is some kind of memory leak, but given I don't have the coding skill to deal with that and it might be with the core libraries, I've opted for a simple soft reset every day. Exactly one day after the sensors nodes are first activated, they will restart themselves.
  • When powering these cheap DHT11 modules from 3.3v, the humidity values are far lower than they should be. I've solved this with a simple multiplication, and calibrated against a commercial sensor. I'd advise you to confirm against your own known source too, before relying on the readings. Alternatively, power them with 5V – but you must place a 5v-3.3v logic level shifter between the data pin and the ESP8266, or you will damage it.

If everything went well, you should now be receiving sensor readings in your MQTT broker, and can go ahead with connecting these to OpenHAB as detailed in part 2 of our beginner's guide, where I also showed you how to graph the data.

humdity graph from openhab

Farewell Arduino, we loved thee so. Just kidding: not everywhere in my house can even get Wi-Fi, so for those spots I'll still need a mesh network with Arduino and RF receivers.

For a fun project, check out how to make a Wi-Fi button with the ESP8266.

But what will you make with ESP8266? Any projects using ESP8266 you'd like to see written up at MakeUseOf? Let us know in the comments!