NodeMCU Firmware for the ESP8266

By December 4, 2015ESP8266, IoT

Introducing NodeMCU

The NodeMCU Firmware is an open source project that provides an abstraction layer on top of the Expressif SDK for the ESP8266. While the SDK itself provides low-level access to the peripherals of the ESP8266EX chip, NodeMCU provides a high level API that hides a lot of the implementation details of how the chip works.

NodeMCU includes a version of the Lua programming language that is based on eLua. Like many developers, I was personally first introduced to the Lua language by means of a widely popular game called The World of Warcraft. The Lua engine itself is embedded into an application’s source code at compile time, and then Lua scripts (in the form of text files) are loaded and executed at runtime in order to automate that application. This is exactly how The World of Warcraft’s add-ons work.

When an ESP8266 loaded with NodeMCU is powered on, the device will provide a REPL via the UART. This means that you can connect to the device over USB, open a terminal, and start issuing Lua commands which are immediately executed.

NodeMCU also includes a filesystem to take advantage of the rest of the flash memory that the firmware itself does not need. Lua scripts can be added and deleted by the user, and executed from that filesystem. A special script named “init.lua” will automatically run upon reset if it exists.

Functionality is provided within the firmware as modules written in C, and there has been a lot of effort spent by the community in creating many different modules. One downside about the ESP8266 is that it doesn’t provide a lot of RAM to work with (it is a microcontroller, after all), so you should strive to use a firmware that contains only the features that you need for your project. By partitioning the firmware’s functionality into modules, it is possible to create custom builds to include or exclude modules individually.

Some of the current modules that are available include:

  • CJSON (JSON support for Lua)
  • CoAP (Constrained Application Protocol)
  • Crypto (for calculating SHA hashes, primarily)
  • A library for integrating with the DHT family of Humidity/Temperature sensors
  • LWIP (Lightweight IP stack)
  • MQTT (a MQTT client)
  • SPIFFS-based filesystem
  • I2C
  • GPIO (for working with GPIO in an Arduino-like fashion)
  • Timer (think: setTimeout and setInterval in JavaScript)
  • WiFi (to configure and start the WiFi station and/or access point)
  • ADC (for reading analog data)
  • SPI (for communicating with other devices via SPI)
  • 1-Wire
  • … and more!


Loading Firmware onto the ESP8266

Before you can flash your ESP8266 with the NodeMCU firmware, you must first obtain the firmware image itself. The recommended way is to either build it from source, or even easier, let someone else build it from source for you.

Marcel Stör from has set up a NodeMCU Custom Build server that will allow you to pick features from one of the official GitHub branches for the project, and generate the firmware for you from the latest source committed to that branch.


It should be noted that at this time, the Master branch is based on SDK 0.96 SDK 1.4, while the Dev branch is the edge development that is based on SDK 1.4. Be sure to check with the official descriptions on GitHub, because the project changes all of the time and this blog post will eventually become stale. Personally, I recommend using the Dev branch because while Master is considered to be stable, there are some things that don’t exactly work as they should in that branch (SPI comes to mind).

UPDATE (5-Dec-2015): It looks like the organizers of the NodeMCU Firmware project have already started to reorganize branches. Main now appears to be based on SDK 1.4. So, the advice above remains: read the current documentation in GitHub, because this blog post will likely be stale once you have read it.

Choose your branch, choose your features, enter your email address (so that you are notified when the build completes), and then click “Start your build” at the bottom.

When the build is complete, you will receive an email with links to two binary files (one for an Integer build, which will be smaller in size and require less memory, and one for support of floating-point numbers). Be sure to download the files to your machine, because they will be purged from the build server after a day.


Flashing the firmware image will depend on your platform. If you use Windows, then the easiest way that I’ve found is to use the NodeMCU-Flasher (

Connect the ESP8266 device to your USB port. If you are using a NodeMCU Dev Kit, then just plug the micro-USB cable into the device. If you are using an Adafruit Huzzah, then follow instructions from their website for connecting a FTDI programmer or USB-to-TTL cable to the header pins.

Navigate to the Config tab and select your firmware image by clicking on the gear icon next to the first line (this will open a file browser dialog to help you locate the .bin file).


Return to the Operation tab, choose the correct COM port for your serial connection, and then click “Flash”. If everything is correctly communicating, then the AP MAC and STA MAC addresses will be displayed and the progress bar will advance as the firmware image is uploaded to the ESP8266 module.


Note that if you are using a different kind of device, then you may need to manually enable Flash mode by holding GPIO0 low during the reset. Both the Adafruit Huzzah and the NodeMCU Dev Kit will do this automatically using the RTS signal of the serial port, but if RTS is not connected (possible for Huzzah if you use a USB-to-TTL cable) or if the circuitry is not in place, then you will need to do this yourself to prevent the device from booting into the normal operating mode.

For Linux users, the preferred flashing tool is esptool ( Typical usage:

sudo python --port /dev/ttyUSB0 write_flash 0x00000 your_nodemcufirmware.bin

If everything is communicating (i.e., your port is /dev/ttyUSB0, etc), then should see output similar to:

Erasing flash...
Writing at 0x00000000... (0 %)

Like the Windows ESP8266Flasher.exe program, esptool will attempt to use the RTS signal to put the ESP8266 into flash mode upon reset. If your device and/or serial connection does not support this, then you will need to manually hold GPIO0 low during reset, and then run esptool.

Now that we have NodeMCU running, the next post in this series will explore the basics of how to use the firmware.

The following two tabs change content below.