Quick Intro: a Beginner's Guide to ESP8266 NodeMCU Development Kit

I have been looking for a development board for quite a while that is:

easy to connect to sensors and actuators
can be accessed and controlled remotely
portable, inexpensive and readily available

Over the years, I tried Arduino, Raspberry Pi, BeagleBone Black, and most recently the $9 C.H.I.P. computer. These boards fit most of the requirements above but not all until about a month ago when I came across this ESP8266 NodeMCU development board. I am very excited about the capability of this board because it basically satisfied all the requirements above. I want to document what I learn when I am playing with it, and the best way to do it is to start my first Instructable!

I ordered a few of this NodeMCU Lua Wifi units (based on ESP8266 CP2102) for about RMB17 (~US$2.5) from Taobao a month ago. One can easily find one from other online stores like Aliexpress.com or Amazon.com that costs less than US$10 each.

When I first received my NodeMCU units about three weeks ago, I tried to connect it to my Macbook Pro with a micro USB cable but nothing showed up in /dev/tty.*. So, I know it is time to dig into the details.

In the following steps, I first ensure the unit is working by following the procedures given by some of the earliest NodeMCU development sites, then follow by playing with it through the ESP8266 Arduino Core.

Step 1: Download Drivers

First download and install a driver USB to UART Bridge Virtual COM Driver for the computer from the SiLab site. After the installation of the driver, connect the NodeMCU to the computer using a micro USB cable. Since I am using a Macbook Pro to do the testing, from a terminal, I see a device named /dev/tty.SLAB_USBtoUART.

Step 2: Install ESPlorer

The simplest way to program the NodeMCU is through an IDE. ESPlorer is the de facto IDE for ESP8266 development. It can be downloaded from https://esp8266.ru/esplorer/. However when I launched the ESPlorer to access the newly acquired NodeMCU at the corresponding port, legible response was obtained only when the baud rate is set to 115200. Pressing the Chip Info button from the IDE or trying to send (using Send to ESP button) a print("hello") Lua command from the left scripting panel both produced errors as shown in the image above. For this reason, I decided to flash the NodeMCU with a new firmware in the following steps.

Step 3: Create Customised Firmware

First of all, I need to get hold of a latest firmware. As pre-built firmware binaries are no longer available, one can get a new customised firmware for the NodeMCU from an online automatic build service at https://nodemcu-build.com/. Attached image shows the modules that I have chosen. It is simply based on the types of things that I might try when playing with the board. After submitting the online request, it took about 4-5 minutes to get an email notification to download the customised firmware.

Step 4: Refresh Firmware With Esptool

To flash the firmware to the NodeMCU, we need to install the esptool which is a python tool to communicate with the ROM Bootloader of the NodeMCU. In a terminal, issue the following command:

esptool.py --port /dev/tty.SLAB_USBtoUART --baud 115200 write_flash --flash_mode dio 0x00000 Downloads/nodemcu-master-25-modules-2017-06-17-06-06-55-float.bin

Adjust the port and the location of the firmware binary accordingly. It took about a minute or two to complete the flashing of the firmware. The system also shows some basic info about the NodeMCU as shown in the image above.

Step 5: Using the ESPlorer - Part 1

It is time to access the newly flashed NodeMCU using the ESPlorer. With the NodeMCU connected to the computer, launch the ESPlorer. Then do the followings:

Choose the port in the upper right dropdown menu. In my case, it is /dev/cu.SLAB_USBtoUART
Set the baud rate to 115200.
Press Open on the ESPlorer to connect to the NodeMCU
Press the RST switch on the NodeMCU.

The right panel in the ESPlorer displays the info about the firmware as shown in the image above. The last line should ended with a ">" prompt.

Note: The last line in the right terminal of the ESPlorer might ended with a "Timeout reached. Command aborted" message without a ">" prompt on a new line. To get a ">" prompt for new command, press the Chip Info button below the right panel to get a ">" prompt.

Step 6: Using the ESPlorer - Part 2

In the previous step, there is an error message complaining that init.lua is missing. In this step, we will follow the procedure in here to insert an init.lua. Basically, on the left scripting panel, input the following 3 lines:

file.open("init.lua", "w+")
file.writeline([[print("Hello World!")]])
file.close()

Then press the Send to ESPbutton at the bottom of the left scripting panel. The 3 lines of code will be executed in the NodeMCU as shown in the right panel. Press the Reset button at the bottom of the right panel to reset the NodeMCU. It should display the Hello World! before a newline with the ">" prompt.

Step 7: Using the ESPlorer - Part 3

It is time to try a few examples using the ESPlorer.

Example 1: setup wifi connection

Insert the following codes in the left scripting panel with the appropriate SSID and password of the wifi network, then press Send to ESP.

station_cfg={}
station_cfg.ssid="SSID_of_my_wifi_AP"
station_cfg.pwd="password_of_the_AP"
wifi.sta.config(station_cfg)
wifi.sta.connect()
print(wifi.sta.getip())

Take note that you might get a nil response because of the time it takes to get an IP address from the wifi access point. Simply issue another print(wifi.sta.getip()) command a couple seconds later to confirm the IP address.

Example 2: setup a simple HTTP Client to fetch a webpage

Once the NodeMCU is connect to the wifi network, inset the following codes in a new scripting panel and then press Send to ESP

conn=net.createConnection(net.TCP, 0)
conn:on("receive", function(conn, pl) print(pl) end)
conn:connect(80,"121.41.33.127")
conn:send("GET / HTTP/1.1\r\nHost: <a href="http://www.nodemcu.com\r\n"
    .."Connection: keep-alive\r\nAccept: */*\r\n\r\n")

The response will be shown in the terminal as shown in the image above.

Example 3: setup a simple HTTP Server

In another new scripting panel, insert the following codes and then press Send to ESP

srv=net.createServer(net.TCP)
srv:listen(80,function(conn) 
  conn:on("receive",function(conn,payload) 
    print(payload) 
    conn:send("<h1> Hello, NodeMcu. </h1>")
  end) 
end)

From a web browser, go to the IP address (which you got from Example 1) of the NodeMCU to see the output. You should see "Hello, NodeMcu" on the browser as shown in the image above.

These examples just explore a very small part of the wifi capacities of the NodeMCU. There are many other Lua based examples at

However, due to the limited resources on the Internet on using Lua based programming to program the NodeMCU, the rest of this instructable will focus on the ESP8266 Arduino Core.

Step 8: ESP8266 Arduino Core

One of the most interesting part about the NodeMCU is it can be accessed and controlled through the ESP8266 Arduino Core. That means we can program the NodeMCU similar to standard Arduino using the Arduino IDE. Furthermore, the ESP8266 Arduino Core is very well documented with many examples and libraries. More details can be found at https://github.com/esp8266/Arduino

However, take note that once started using the Arduino IDE to program the NodeMCU, it is necessary to flash the firmware again in order to program the NodeMCU through the ESPlorer.

Preparing the Arduino IDE

The easiest way to prepare the Arduino IDE is through the Arduino Boards Manger. Details can be found from the above URL. Basically, just do the following:

install the latest version of Arduino IDE from the Arduino website
enter http://arduino.esp8266.com/stable/package_esp8266com_index.json into the Additional Board Manager URLs field in Arduino->Preferences
choose Boards Manager from the Tools->Board menu. Then find and install the esp8266 board
restart the Arduino
connect the NodeMCU to the computer, then from Arduino, set the Board, Upload Speed, and Port similar to the image above

From then on, one can program the NodeMCU similar to standard Arduino. The easiest way to get started is to load a few examples from File->Examples->ESP8266.

Before I end this instrutable, let's go through a simple procedure that explore the file system of the NodeMCU in the following steps as it involves special setup to be done on the Arduino IDE.

Step 9: Uploading Files to NodeMCU File System

The NodeMCU has a file system that allow us to store sketch data, configure files, or even content for web server. Programming new sketch will not modify the file system content.

An uploading tool is required to be installed in the Arduino IDE. Detailed explanations and procedures can be found at http://esp8266.github.io/Arduino/versions/2.3.0/doc/filesystem.html. Basically, just do the followings:

download the tool: https://github.com/esp8266/arduino-esp8266fs-plugi...
unzip the file and put the contents inside the Arduino/tools directory. The path to the Arduino directory is listed under Arduino->Preferences->Sketchbook location
restart Arduino

Under the Tools menu, there should be a ESP8266 Sketch Data Upload item as shown in the image above. Take note that to use the ESP8266 Sketch Data Upload tool, data need to be placed inside a data directory of a sketch.

Let's create a simple sketch that list the contents in the NodeMCU file system. Start a new sketch named esp8266CheckDir with the following code:

/*
 * Check the directory inside the ESP8266 NodeMCU
 */

#include "FS.h"
void setup() {
  Serial.begin(115200);
  Serial.println("");
  delay(1000);
  Serial.println("Mounting FS...");

  if(!SPIFFS.begin()) {
    Serial.println("Failed to mount file system");
    return;
  }

  Dir root = SPIFFS.openDir("/");
  Serial.println("Checking the root file system.");
  while (root.next()) {
    Serial.print(root.fileName());
    Serial.print(" - ");
    File f = root.openFile("r");
    Serial.print(f.size());
    Serial.println("bytes");
  }
  Serial.println("Finish checking the root file system.");
}

void loop() {
  SPIFFS.end();
}

Compile and upload the sketch as per the usual Arduino way.

To upload data for the sketch, do the followings:

make sure the Serial Monitor is NOT running
go to the sketch directory from Sketch->Show Sketch Folder
create a data directory
put all the upload contents (including sub directories) inside the data directory
choose Tools->ESP8266 Sketch Data Upload

This should start uploading the files to the NodeMCU file system. The upload would take a few minutes to complete. When it is done, the IDE status bar will display SPIFFS Image Uploaded.

To check if the data is uploaded properly, re-run the uploaded esp8266CheckDir as follow:

start the Serial Monitor of the Arduino
choose 115200 baud
press the RST switch on the NodeMCU

The result will show on the Serial Monitor similar to the image above.

So far, we have just covered the very basic things of the ESP8266 NodeMCU. There are many other interesting features for us to explore. For examples, connecting it to various sensors and actuators, communicate with it using MQTT etc. However, if more powerful device is required, one should explore the ESP32, a newer big brother of ESP8266, which comes with faster WiFi, with Bluetooth functionality and dual processor. As for me, I'm happy with ESP8266 for now.