From Tuxamito
Jump to: navigation, search

The NodeMCU is an open-source firmware and development environment based on the Lua script language for the ESP8266 wifi-enabled microcontroller. For easy development there is available the NodeMCU devkit board that map the contacts of the ESP8266 chip to easy to use pins and contains extra hardware, such as a serial port to USB adapter to flash new firmwares, update the scripts or simply communicate with a PC.

Generating a new firmware

The easiest way to generate a new firmware is to use the online service: NodeMCU Build In it, you only need to select the modules you want to be build into the firmware and then download the generated firmware binary file.

Flashing the firmware

One of the options for flashing a new firmware into a ESP8266 under GNU/Linux is to use this tool: ESP Tool (GiHub) or (Tuxamito).

Under the directory where the tool you will execute the command:

$ ./ --port PORT  write_flash 0x00000 FIRMWARE.bin 

where PORT is the serial port to where the hardware is connected (and you need to have read and write permissions for the user) and FIRMWARE.bin is the binary file of the firmware to flash. An example:

$ ./ --port /dev/ttyUSB0  write_flash 0x00000 ~/Downloads/nodemcu-master-14-modules-2015-12-23-21-28-43-float.bin 

The process might take some minutes and it will show a similar message to this:

Erasing flash...
Writing at 0x0002cc00... (42 %) 

If the process finish successfully this message will appear:

Wrote 431104 bytes at 0x00000000 in 42.0 seconds (82.1 kbit/s)...


To test if the firmware is working correctly unplug and plug again the board and use a terminal program to connect to the board such as screen, picocom or the terminal window of the arduino SDK (in the latest version the tty speed was increased from 9600 to 115200 bauds, so use the appropriate speed when connecting):

screen /dev/ttyUSB0 9600

and then type:


A message similar to this should appear:

> ������D���
NodeMCU custom build by
        branch: master
        commit: 93421f2702fb02ce169f82f96be7f2a8865511e1
        SSL: false
        modules: node,file,gpio,wifi,net,pwm,i2c,spi,tmr,adc,uart,bit,cjson,crypto
 build  built on: 2015-12-23 21:27
 powered by Lua 5.1.4 on SDK 1.4.0
lua: cannot open init.lua

You should not need to worry about the message about the "init.lua" file, that file contains the starting point of the program that we want to be executed automatically at boot time. In the next sections you can find descriptions on how to upload this file, and others, to the board.

After flashing a new firmware it is recommended to format again the file system before using the device, for this give the command: file.format()

> file.format()
format done.

and check the file system:

> print(file.fsinfo())
3426401 0       3426401

where the first number is the total bytes available, followed by the bytes used and the bytes remaining.

Uploading files

A good option for uploading files into the ESP8266 with NodeMCU firmware under GNU/Linux is this tool: NodeMCU Uploader (GitHub) or (Tuxamito)

From the directory where the tool is places you can execute

$ ./ --port PORT --start_baud NODEMCU_BAUDRATE upload FILE

where PORT is the serial port to where the hardware is connected (and you need to have read and write permissions for the user) and FILE is the file that is going to be uploaded into the file system of the board. An example:

$ ./ --port /dev/ttyUSB0 upload init.lua

This tool can also upload a list of files or download them from the device, as described in its documentation.

NOTE: when using the latest versions of nodemcu you might need to set the flag --start_baud 115200.


Up to know there are two versions of the NodeMCU DevKit board.

DevKit v0.9

This one is based on the core ESP-12, it is usually a blue or yellow board and quite wide, so it does not fit well on common bread boards.


DevKit v1.0

This board is based on the core ESP-12-E, it is usually black and narrower than the previous model. It fixes some problems, fits better into common bread boards, and has more I/O pins.


Pin Mapping for Arduino IDE

 1 static const uint8_t D0   = 16;
 2 static const uint8_t D1   = 5;
 3 static const uint8_t D2   = 4;
 4 static const uint8_t D3   = 0;
 5 static const uint8_t D4   = 2;
 6 static const uint8_t D5   = 14;
 7 static const uint8_t D6   = 12;
 8 static const uint8_t D7   = 13;
 9 static const uint8_t D8   = 15;
10 static const uint8_t D9   = 3;
11 static const uint8_t D10  = 1;