Getting started on NodeMCU with your own Firmware
Several times a year we have our Rabbiteer sessions at Retro Rabbit where we present cool stuff related to all areas of software development. This year I’m going to be presenting the IoT (internet of things) session, with the topic “IoT on the cheap”.
Furthermore, to make things go as smooth as possible I opted to build our own firmware. There is an online build service, but I wanted to build my own for two main reasons. Firstly, I wanted to understand the firmware and select exactly the modules I wanted, and be able to inspect the source code easily if needed. Secondly, I was afraid that some part of the chinesium open source software would be broken and I at least wanted the opportunity to fix it if possible (and lo I did find bugs in the TLS/HTTP code. I did not end up fixing it though).
In this article I’ll run through the steps to compiling your own firmware and uploading it.
Firstly, you’ll need Linux, and my instructions will use Ubuntu. If you’re a Windows person I recommend the Linux Subsystem for Windows, which is actually what I’ll be using.
sudo apt-get install -y git autoconf build-essential gperf bison \
flex texinfo libtool libncurses5-dev wget gawk \
libc6-devpython-dev python python-serial libexpat-dev unzip \
zip gdb make unrar-free automake gcc g++ libc-dbg \
ncurses-dev expat lua5.1 lua5.1-doc luarocks sed git bash \
You’ll also need a bunch of Lua dependencies:
sudo luarocks install bitlib
sudo luarocks install luafilesystem
sudo luarocks install md5
sudo luarocks install luaposix
sudo luarocks install luasocket
Compiling the Compiler
We’re going to need Xtensa toolchain to compile for the Tensilica processor inside the ESP2866 which is the brain of the NodeMCU. In order to do this we need to clone the repo:
git clone --recursive https://github.com/pfalcon/esp-open-sdk
And build it:
This is going to take a long time (and download a ton of stuff along the way). On my laptop it takes about an hour.
In the Meanwhile: Drivers (Windows only)
While the compiler is compiling we can use the time to install the drivers. If you’re a Linux user check out what’s what over here, but good luck, I hear people have problems (I’m guessing because drivers+linux=😭).
On Windows it was pretty easy for (and I’ve done this with two different NodeMCUs with different USB Serial interfaces).
So plug in your NodeMCU, and head over to the Device Manager. Easy way is to right click on the windows button or press windows key+X.
You’ll see that the device is there but windows doesn’t know what it is.
Double click on it and head over to the Drivers tab. Click on Update Driver:
The be sure to select the top button to search windows update:
It should search for a while and then install the drivers. No downloading dodgy drivers from some weird website.
In the Meanwhile: Connecting with PuTTY (Again, Only Windows Users will Care)
Another bonus item while the compiler is building: connecting with PuTTY:
Note in your device manager what the port is (mine is COM8 like you see above). And open up PuTTY. Select Serial and enter the port:
Enter the baud rate of 115200 (may not work for you, but it worked for the two different kinds of NodeMCUs I have).
Next go to the serial category on the side and set the settings like this (btw I did this by trial and error):
Now you should be able to open the terminal and send commands:
Note: If nothing happens it’s likely that your controller does not have the NodeMCU firmware on it (again, both of mine were like this). Press the reset button while PuTTY is open and see what it spits out.
Compiling the Firmware
Once the toolchain is done compiling we need to add it to the path by adding these lines to your
(run these commands in the console as well so we can move on without logging out and in again)
now we can move on to compiling the firmware (with the toolchain).
Clone the firmware:
git clone https://github.com/nodemcu/nodemcu-firmware.git
This should only take a minute or two. Verify that the firmware is built by checking the bin folder:
If it worked it will create those two files.
Customizing the Firmware
The above should prove whether or not the firmware builds without any modification. Typically we will want to specify the modules we need. To change this, edit the file
app/config/user_modules.h. For example, if we want to enable support for a DHT11 temprature/humidity sensor, we comment out this line:
And then run
We can also modify the firmware name and build date by editing
user_version.h in the same directory:
#define NODE_VERSION "NodeMCU 2.1.0 Rabbiteer Edition"
#define BUILD_DATE __DATE__ __TIME__
This is what I set my version to.
Uploading the Firmware
To upload the firmware we’ll use esptool. This can easily be obtained by running
sudo pip install esptool (LSW Windows users: you’ll have to run this from outside Linux since it does not (currently) have access to serial ports).
To upload the firmware, run (linux):
esptool.py --port <port> write_flash -fm qio \
0x00000 0x00000.bin \
<port> is the serial port device (e.g.
/dev/ttyUSB0 or something). On windows CMD it will typically be something like:
esptool --port COM8 write_flash -fm qio ^
0x00000 0x00000.bin ^
And then your firmware will be updated!
esptool --port blah blah blah
Detecting chip type... ESP8266
Chip is ESP8266
Configuring flash size...
Auto-detected Flash size: 4MB
Flash params set to 0x0040
Compressed 30912 bytes to 22217...
Wrote 30912 bytes (22217 compressed) at 0x00000000 in 2.0 seconds (effective 126.2 kbit/s)...
Hash of data verified.
Compressed 575040 bytes to 391216...
Wrote 575040 bytes (391216 compressed) at 0x00010000 in 34.4 seconds (effective 133.6 kbit/s)...
Hash of data verified.
And if we PuTTY into it and press the reset button:
And that’s all there is to it! Now you can hack your way through the firmware to your heart’s content.