[](https://gitter.im/nodemcu/nodemcu-firmware?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
#### [*] D0(GPIO16) can only be used as gpio read/write. no interrupt supported. no pwm/i2c/ow supported.
#Build option
####file ./app/include/user_modules.h
```c
#define LUA_USE_BUILTIN_STRING // for string.xxx()
#define LUA_USE_BUILTIN_TABLE // for table.xxx()
#define LUA_USE_BUILTIN_COROUTINE // for coroutine.xxx()
#define LUA_USE_BUILTIN_MATH // for math.xxx(), partially work
// #define LUA_USE_BUILTIN_IO // for io.xxx(), partially work
// #define LUA_USE_BUILTIN_OS // for os.xxx(), not work
// #define LUA_USE_BUILTIN_DEBUG // for debug.xxx(), not work
#define LUA_USE_MODULES
#ifdef LUA_USE_MODULES
#define LUA_USE_MODULES_NODE
#define LUA_USE_MODULES_FILE
#define LUA_USE_MODULES_GPIO
#define LUA_USE_MODULES_WIFI
#define LUA_USE_MODULES_NET
#define LUA_USE_MODULES_PWM
#define LUA_USE_MODULES_I2C
#define LUA_USE_MODULES_SPI
#define LUA_USE_MODULES_TMR
#define LUA_USE_MODULES_ADC
#define LUA_USE_MODULES_UART
#define LUA_USE_MODULES_OW
#define LUA_USE_MODULES_BIT
#define LUA_USE_MODULES_MQTT
// #define LUA_USE_MODULES_COAP
#define LUA_USE_MODULES_U8G
#define LUA_USE_MODULES_WS2812
#define LUA_USE_MODULES_CJSON
#endif /* LUA_USE_MODULES */
```
#Online firmware custom build
For many application, some modules are not used, remove them can free many memory.<br/>
Please try Marcel's [NodeMCU custom builds](http://frightanic.com/nodemcu-custom-build) cloud service and you can get your own firmware.<br/>
#Flash the firmware
nodemcu_latest.bin: 0x00000<br/>
for most esp8266 modules, just pull GPIO0 down and restart.<br/>
You can use the [nodemcu-flasher](https://github.com/nodemcu/nodemcu-flasher) to burn the firmware.
Or, if you build your own bin from source code.<br/>
0x00000.bin: 0x00000<br/>
0x10000.bin: 0x10000<br/>
*Better run file.format() after flash*
# Programming Examples
#Connect the hardware in serial
baudrate:9600
Because Lua is a high level language and several modules are built into the firmware, you can very easily program your ESP8266. Here are some examples!
#Write Lua script to filesystem
####Esplorer
Victor Brutskiy's [Esplorer](https://github.com/4refr0nt/ESPlorer) support most platforms such as Linux, Windows, Mac OS, etc. This software is opensource and can write lua/lc files to filesystem.
####NodeMCU Studio
[NodeMCU Studio](https://github.com/nodemcu/nodemcu-studio-csharp) is written in C# and support Windows. This software is opensource and can write lua files to filesystem.
m:close();-- if auto-reconnect == 1, will disable auto-reconnect and then disconnect from host.
m:close();-- if auto-reconnect == 1, it will disable auto-reconnect and then disconnect from host.
-- you can call m:connect again
```
#### UDP client and server
## UDP client and server
```lua
-- a udp server
s=net.createServer(net.UDP)
s:on("receive",function(s,c)print(c)end)
s:on("receive",function(s,c)print(c)end)
s:listen(5683)
-- a udp client
cu=net.createConnection(net.UDP)
cu:on("receive",function(cu,c)print(c)end)
cu:connect(5683,"192.168.18.101")
cu:on("receive",function(cu,c)print(c)end)
cu:connect(5683,"192.168.18.101")
cu:send("hello")
```
####Do something shining
## Do something shiny with an RGB LED
```lua
functionled(r,g,b)
pwm.setduty(1,r)
pwm.setduty(2,g)
pwm.setduty(3,b)
functionled(r,g,b)
pwm.setduty(1,r)
pwm.setduty(2,g)
pwm.setduty(3,b)
end
pwm.setup(1,500,512)
pwm.setup(2,500,512)
pwm.setup(3,500,512)
pwm.setup(1,500,512)
pwm.setup(2,500,512)
pwm.setup(3,500,512)
pwm.start(1)
pwm.start(2)
pwm.start(3)
led(512,0,0)-- red
led(0,0,512)-- blue
led(512,0,0)-- red
led(0,0,512)-- blue
```
####And blink it
## And blink it
```lua
lighton=0
tmr.alarm(1,1000,1,function()
tmr.alarm(1,1000,1,function()
iflighton==0then
lighton=1
led(512,512,512)
led(512,512,512)
else
lighton=0
led(0,0,0)
led(0,0,0)
end
end)
```
####If you want to run something when system started
## If you want to run something when the system boots
```lua
--init.lua will be excuted
file.open("init.lua","w")
--init.lua will be executed
file.open("init.lua","w")
file.writeline([[print("Hello, do this at the beginning.")]])
file.close()
node.restart()-- this will restart the module.
```
####With below code, you can telnet to your esp8266 now
## Add a simple telnet server to the Lua interpreter
```lua
-- a simple telnet server
s=net.createServer(net.TCP,180)
s:listen(2323,function(c)
s=net.createServer(net.TCP,180)
s:listen(2323,function(c)
functions_output(str)
if(c~=nil)
thenc:send(str)
end
end
node.output(s_output,0)-- re-direct output to function s_ouput.
c:on("receive",function(c,l)
node.input(l)-- works like pcall(loadstring(l)) but support multiple separate line
c:on("receive",function(c,l)
node.input(l)-- works like pcall(loadstring(l)) but support multiples separate lines
end)
c:on("disconnection",function(c)
node.output(nil)-- un-regist the redirect output function, output goes to serial
c:on("disconnection",function(c)
node.output(nil)-- un-register the redirect output function, output goes to serial
end)
print("Welcome to NodeMcu world.")
print("Welcome to NodeMCU world.")
end)
```
# Building the firmware
There are several options for building the NodeMCU firmware.
## Online firmware custom build
Please try Marcel's [NodeMCU custom builds](http://frightanic.com/nodemcu-custom-build) cloud service and you can choose only the modules you need, and download the firmware once built.
NodeMCU custom builds can build from the master branch (0.9.6; deprecated) and dev
branch (1.4.0).
## Docker containerised build
See https://hub.docker.com/r/asmaps/nodemcu-builder/
This docker image includes the build toolchain and SDK. You just run the docker
image with your checked-out NodeMCU firmware repository (this one). The docker
image can also flash the firmware to your device.
You will need to see BUILD OPTIONS below, to configure the firmware before building.
## Build it yourself
See BUILD OPTIONS below, to configure the firmware before building.
### Minimum requirements:
- unrar
- GNU autoconf, automake, libtool
- GNU gcc, g++, make
- GNU flex, bison, gawk, sed
- python, python-serial, libexpat-dev
- srecord
- The esp-open-sdk from https://github.com/pfalcon/esp-open-sdk
### Build instructions:
Assuming NodeMCU firmware is checked-out to `/opt/nodemcu-firmware`:
Disable modules you won't be using, to reduce firmware size on flash and
free more RAM. The ESP8266 is quite limited in available RAM, and running
out can cause a system panic.
## Edit `app/include/user_modules.h`
Comment-out the #define statement for unused modules. Example:
```c
#ifdef LUA_USE_MODULES
#define LUA_USE_MODULES_NODE
#define LUA_USE_MODULES_FILE
#define LUA_USE_MODULES_GPIO
#define LUA_USE_MODULES_WIFI
#define LUA_USE_MODULES_NET
#define LUA_USE_MODULES_PWM
#define LUA_USE_MODULES_I2C
#define LUA_USE_MODULES_SPI
#define LUA_USE_MODULES_TMR
#define LUA_USE_MODULES_ADC
#define LUA_USE_MODULES_UART
#define LUA_USE_MODULES_OW
#define LUA_USE_MODULES_BIT
#define LUA_USE_MODULES_MQTT
// #define LUA_USE_MODULES_COAP
// #define LUA_USE_MODULES_U8G
// #define LUA_USE_MODULES_WS2801
// #define LUA_USE_MODULES_WS2812
// #define LUA_USE_MODULES_CJSON
#define LUA_USE_MODULES_CRYPTO
#define LUA_USE_MODULES_RC
#define LUA_USE_MODULES_DHT
#define LUA_USE_MODULES_RTCMEM
#define LUA_USE_MODULES_RTCTIME
#define LUA_USE_MODULES_RTCFIFO
#define LUA_USE_MODULES_SNTP
// #define LUA_USE_MODULES_BMP085
#define LUA_USE_MODULES_TSL2561
// #define LUA_USE_MODULES_HX711
#endif /* LUA_USE_MODULES */
```
## Tagging your build
Identify your firmware builds by editing `app/include/user_version.h`
```c
#define NODE_VERSION "NodeMCU 1.4.0+myname"
#ifndef BUILD_DATE
#define BUILD_DATE "YYYYMMDD"
#endif
```
## Setting the boot time serial interface rate
The initial baud rate at boot time is 9600 bps, but you can change this by
editing `app/include/user_config.h` and change BIT_RATE_DEFAULT, e.g.:
```c
#define BIT_RATE_DEFAULT BIT_RATE_115200
```
# Flash the firmware
## Flash tools for Windows
You can use the [nodemcu-flasher](https://github.com/nodemcu/nodemcu-flasher) to burn the firmware.
## Flash tools for Linux
Esptool is a python utility which can read and write the flash in an ESP8266 device. See https://github.com/themadinventor/esptool
## Preparing the hardware for firmware upgrade
To enable ESP8266 firmware flashing, the GPIO0 pin must be pulled low before
the device is reset. Conversely, for a normal boot, GPIO0 must be pulled high
or floating.
If you have a [NodeMCU Development Kit](http://www.nodemcu.com/index_en.html) then
you don't need to do anything, as the USB connection can pull GPIO0
low by asserting DTR, and reset your board by asserting RTS.
If you have an ESP-01 or other device without inbuilt USB, you will need to
enable flashing yourself by pulling GPIO0 low or pressing a "flash" switch.
## Files to burn to the flash
If you got your firmware from [NodeMCU custom builds](http://frightanic.com/nodemcu-custom-build) then you can flash that file directly to address 0x00000.
Otherwise, if you built your own firmware from source code:
- bin/0x00000.bin to 0x00000
- bin/0x10000.bin to 0x10000
Also, in some special circumstances, you may need to flash `blank.bin` or `esp_init_data_default.bin` to various addresses on the flash (depending on flash size and type).
If upgrading from `spiffs` version 0.3.2 to 0.3.3 or later, or after flashing any new firmware, you should run `file.format()` to re-format your flash filesystem.
# Connecting to your NodeMCU device
NodeMCU serial interface uses 9600 baud at boot time. To increase the speed after booting, issue `uart.setup(0,115200,8,0,1,1)` (ESPlorer will do this automatically when changing the speed in the dropdown list).
If the device panics and resets at any time, errors will be written to the serial interface at 115200 bps.
# User Interface tools
## Esplorer
Victor Brutskiy's [ESPlorer](https://github.com/4refr0nt/ESPlorer) is written in Java, is open source and runs on most platforms such as Linux, Windows, Mac OS, etc.
#### Features
- Edit Lua scripts and run on the ESP8266 and save to its flash
- Serial console log
- Also supports original AT firmware (reading and setting WiFi modes, etc)
## NodeMCU Studio
[NodeMCU Studio](https://github.com/nodemcu/nodemcu-studio-csharp) is written in C# and supports Windows. This software is open source and can write lua files to filesystem.