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 make STANDALONE=y 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:
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.
- Connect NodeMCU and computer with mini USB
- In terminal enter command:
dmesg | grep tty
- 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 espinitdata_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 espinitdata_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.
Republished from my original blog post created on January 2016. Several updates made based on recent changes in SDK's. ↩