/ Follow the trail

Flash NodeMCU

After various messy and mostly faulty breadboard setups with my ESP8266, I came across a fantastic solution: NodeMCU. This little board fits perfectly on my breadboard and exponentially simplifies the wiring. This post describes the steps to flash the ESP8266 with a custom(!) made NodeMCU firmware using Linux -- I use a GalliumOS distro on my Google chromebook Pixel. Once the ESP is flashed correctly it's ready for programming using Lua scripts or Arduino sketches.[1]

Building the toolchain

Before we can begin we must have the tools in place which enable you to write firmware to the ESP. EspressIf, the manufacturer of the ESP chips has a proprietary toolchain which is difficult to build and keep updated. As often the case an open source alternative exists: esp-open-sdk.

The open SDK is not only easier to build, the toolchain can also can be updated with minimal effort. In order to install these tools I've put together the Linux script below. Beware the generation of the toolchain can take up to several hours depending your hardware configuration.

#Install needed dependencies (as root)
sudo apt-get install make unrar autoconf automake libtool gcc g++ gperf flex bison texinfo gawk ncurses-dev libexpat-dev python python-serial sed git unzip bash help2man wget bzip2
#BUG: Build error GNU libtool >= 1.5.26
sudo apt-get -y install libtool-bin
#ERROR: Installing cross-gbd - python is missing or unusable
sudo apt-get install python2.7-dev

#Install the esp-open-sdk based toolchain (as local)
mkdir ~/opt && cd ~/opt
git clone --recursive https://github.com/pfalcon/esp-open-sdk.git
cd esp-open-sdk
echo 'PATH=$PATH:/opt/esp-open-sdk/xtensa-lx106-elf/bin' >> ~/.profile
export PATH=$PATH:~/opt/esp-open-sdk/xtensa-lx106-elf/bin

Building custom firmware

Before any firmware can be downloaded, generated or build the NodeMCU devkit must be installed.

cd ~/opt
git clone https://github.com/nodemcu/nodemcu-firmware.git
cd nodemcu-firmware

The NodeMCU firmware can be created in a couple of different ways - each increasingly more tailored to the individual needs and thus reducing its footprint on the micro controller.

Download NodeMCU firmware

Due to the ever-growing number of modules available within NodeMCU, pre-built binaries are no longer made available. Instead use the automated custom firmware build service to get the specific firmware configuration you need, or build your own firmware. Both alternatives are discussed in more detail below.

Custom firmware build service

As for my personal favorite, try the NodeMCU custom firmware build service where you can choose those Lua modules you need. Once selected the tool compiles the firmware for you - integer as well as float versions. For the intend and purposes of this blog, select the node, dht, mqtt, http, rtcmem, file, gpio, wifi, net, pwm, tmr, adc, and uart modules.

Once generated you receive an email which contains two url's (float and integer versions) where you can download the custom firmware. Move the custom build firmware into the ~opt/nodemcu-firmware/bin directory. Big thanks to Marcel Stör for running this service.

Custom building the firmware

A last, more adventurous option is to build custom firmware from scratch. In order to do this navigate to the ~opt/nodemcu-firmware/app directory and locate a file called user_modules.h. Open this file with your preferred code editor and comment out the modules not needed by adding and/or removing using the //.

Alternatively additional custom declaration and/or modules can be added in the file called user_config.h. Once completed navigate back to the ~opt/nodemcu-firmware and execute the command make - this process initiates the generation of the firmware and can take a while. Once completed two firmware files should have been generated and deposited in the ~opt/nodemcu-firmware/bin directory: 0x00000.bin and 0x10000.bin.

Flashing the ESP8266

As a prerequisite for flashing the ESP8266 SoC we need to ensure we have permission to access the serial port. In terminal enter the command: sudo adduser xyz-user dialout. Replace xyz-user with your username. Next we need to know what serial port the micro controller uses to connect with the development environment.

  1. Connect NodeMCU and computer with mini USB
  2. In terminal enter command: dmesg | grep tty
  3. Result should read something like this: 1955.456170] usb 2-1.3: cp210x converter now attached to ttyUSB4

Upload firmware (Updated August 2016)

During the validation and republishing of this blog post I came across some issues with my NodeMCU devkit 1.0. NodeMCU documentation provided good insight in the cause for my issues, biggest being Espressif changing the init data block esp_init_data_default.bin for their devices.

The folks at NodeMCU also provided a resolution for the problem which starts with downloading the SDK patch and extract the file esp_init_data_default.bin into the ~opt/nodemcu-firmware/bin directory. Upload the firmware with the following instructions:

cd ~/opt/esp-open-sdk/esptool/
sudo python esptool.py --port /dev/ttyUSB4 erase_flash
sudo python esptool.py --port /dev/ttyUSB4 --baud 115200 write_flash -fm dio -fs 32m 0x000000 ~/opt/nodemcu-firmware/bin/nodemcu-master-11-modules-2016-08-14-00-04-32-integer.bin 0x3fc000 ~/opt/nodemcu-firmware/bin/esp_init_data_default.bin

For custom firmware builds use the following:

cd ~/opt/esp-open-sdk/esptool/
sudo python esptool.py --port /dev/ttyUSB4 erase_flash
sudo python esptool.py --port /dev/ttyUSB4 --baud 115200 write_flash -fm dio -fs 32m 0x00000 ~/opt/nodemcu-firmware/bin/0x00000.bin 0x10000 ~/opt/nodemcu-firmware/bin/0x10000.bin 0x3fc000 ~/opt/nodemcu-firmware/bin/esp_init_data_default.bin

If everything went well you should see a similar screen as below - congratulations! You have just uploaded your customized firmware onto your ESP8266 equipped NodeMCU.

Upon completion of the step the ESP8266 SoC has become a whole lot smarter - it's ready to interpret Lua based scripts! My next project will focus on enabling a DHT22 temperature and humidity sensor leveraging the embedded DHT and MQTT modules we included in our NodeMCU firmware.

  1. Republished from my original blog post created on January 2016. Several updates made based on recent changes in SDK's. ↩︎

If you use Disqus comments, just uncomment this block. The only thing you need to change is "test-apkdzgmqhj" - which should be replaced with your own Disqus site-id.