[](https://gitter.im/nodemcu/nodemcu-firmware?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
[](https://gitter.im/nodemcu/nodemcu-firmware?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
- Build on [ESP8266 NONOS SDK 1.5.1](http://bbs.espressif.com/viewtopic.php?f=46&p=5315)
- Lua core based on [eLua project](http://www.eluaproject.net/)
- cjson based on [lua-cjson](https://github.com/mpx/lua-cjson)
- File system based on [spiffs](https://github.com/pellepl/spiffs)
- Open source development kit for NodeMCU [nodemcu-devkit-v0.9](https://github.com/nodemcu/nodemcu-devkit)[nodemcu-devkit-v1.0](https://github.com/nodemcu/nodemcu-devkit-v1.0)
### A Lua based firmware for ESP8266 WiFi SOC
# Summary
- Easy to program wireless node and/or Access Point
- Based on Lua 5.1.4 (without *debug, os* module.)
| NodeMCU Studio GUI | https://github.com/nodemcu/nodemcu-studio-csharp |
# Programming Examples
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!
## Connect to your AP
NodeMCU is an [eLua](http://www.eluaproject.net/) based firmware for the [ESP8266 WiFi SOC from Espressif](http://espressif.com/en/products/esp8266/). The firmware is based on the [Espressif NON-OS SDK 1.5.1](http://bbs.espressif.com/viewtopic.php?f=46&p=5315) and uses a file system based on [spiffs](https://github.com/pellepl/spiffs). The code repository consists of 98.1% C-code that glues the thin Lua veneer to the SDK.
```lua
ip=wifi.sta.getip()
print(ip)
--nil
wifi.setmode(wifi.STATION)
wifi.sta.config("SSID","password")
ip=wifi.sta.getip()
print(ip)
--192.168.18.110
```
## Manipulate hardware like an Arduino
```lua
pin=1
gpio.mode(pin,gpio.OUTPUT)
gpio.write(pin,gpio.HIGH)
print(gpio.read(pin))
```
The NodeMCU *firmware* is a companion project to the popular [NodeMCU dev kits](https://github.com/nodemcu/nodemcu-devkit-v1.0), ready-made open source development boards with ESP8266-12E chips.
- Firmware available with or without floating point support (integer-only uses less memory)
- Up-to-date documentation at [https://nodemcu.readthedocs.org](https://nodemcu.readthedocs.org)
```lua
-- A simple http server
srv=net.createServer(net.TCP)
srv:listen(80,function(conn)
conn:on("receive",function(conn,payload)
print(payload)
conn:send("<h1> Hello, NodeMCU.</h1>")
end)
conn:on("sent",function(conn)conn:close()end)
end)
```
# Programming Model
## Connect to MQTT broker
The NodeMCU programming model is similar to that of [Node.js](https://en.wikipedia.org/wiki/Node.js), only in Lua. It is asynchronous and event-driven. Many functions, therefore, have parameters for callback functions. To give you an idea what a NodeMCU program looks like study the short snippets below. For more extensive examples have a look at the [`/lua_examples`](lua_examples) folder in the repository on GitHub.
```lua
-- init mqtt client with keepalive timer 120sec
m=mqtt.Client("clientid",120,"user","password")
-- setup Last Will and Testament (optional)
-- Broker will publish a message with qos = 0, retain = 0, data = "offline"
-- to topic "/lwt" if client doesn't send keepalive packet
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
```lua
-- a udp server
s=net.createServer(net.UDP)
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:send("hello")
```
## Do something shiny with an RGB LED
```lua
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.start(1)
pwm.start(2)
pwm.start(3)
led(512,0,0)-- red
led(0,0,512)-- blue
-- connect to WiFi access point
wifi.setmode(wifi.STATION)
wifi.sta.config("SSID","password")
```
## And blink it
```lua
lighton=0
tmr.alarm(1,1000,1,function()
iflighton==0then
lighton=1
led(512,512,512)
else
lighton=0
led(0,0,0)
end
end)
```
# Documentation
## If you want to run something when the system boots
The entire [NodeMCU documentation](https://nodemcu.readthedocs.org) is maintained right in this repository at [/docs](docs). The fact that the API documentation is mainted in the same repository as the code that *provides* the API ensures consistency between the two. With every commit the documentation is rebuilt by Read the Docs and thus transformed from terse Markdown into a nicely browsable HTML site at [https://nodemcu.readthedocs.org](https://nodemcu.readthedocs.org).
```lua
--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.
```
## 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)
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 multiples separate lines
end)
c:on("disconnection",function(c)
node.output(nil)-- un-register the redirect output function, output goes to serial
end)
print("Welcome to NodeMCU world.")
end)
```
- How to [build the firmware](https://nodemcu.readthedocs.org/en/dev/en/build/)
- How to [flash the firmware](https://nodemcu.readthedocs.org/en/dev/en/flash/)
- How to [upload code and NodeMCU IDEs](https://nodemcu.readthedocs.org/en/dev/en/upload/)
- API documentation for every module
# Building the firmware
# Support
There are several options for building the NodeMCU firmware.
See [https://nodemcu.readthedocs.org/en/dev/en/support/](https://nodemcu.readthedocs.org/en/dev/en/support/).
## Online firmware custom build
# License
Please try Marcel's [NodeMCU custom build](http://nodemcu-build.com) cloud service and you can choose only the modules you need, and download the firmware once built.
The following sections explain some of the options you have if you want to [build your own NodeMCU firmware](http://nodemcu.readthedocs.org/en/dev/en/build/).
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.
### Select Modules
## Edit `app/include/user_modules.h`
Disable modules you won't be using to reduce firmware size and free up some RAM. The ESP8266 is quite limited in available RAM and running out of memory can cause a system panic.
Comment-out the #define statement for unused modules. Example:
Edit `app/include/user_modules.h` and comment-out the `#define` statement for modules you don't need. 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
#define LUA_USE_MODULES_HTTP
#endif /* LUA_USE_MODULES */
...
```
## Taggingyour build
### Tag Your Build
Identify your firmware builds by editing `app/include/user_version.h`
```c
#define NODE_VERSION "NodeMCU 1.5.1+myname"
#ifndef BUILD_DATE
#define BUILD_DATE "YYYYMMDD"
#define BUILD_DATE "YYYYMMDD"
#endif
```
## Setting the boot time serial interface rate
### Set UART Bit Rate
The initial baud rate at boot time is 9600bps, but you can change this by
editing `app/include/user_config.h` and change BIT_RATE_DEFAULT, e.g.:
The initial baud rate at boot time is 9600bps. You can change this by
editing `BIT_RATE_DEFAULT` in `app/include/user_config.h`:
```c
#define BIT_RATE_DEFAULT BIT_RATE_115200
```
## Debugging
### Debugging
To enable runtime debug messages to serial console, edit `app/include/user_config.h`
To enable runtime debug messages to serial console edit `app/include/user_config.h`
```c
#define DEVELOP_VERSION
```
`DEVELOP_VERSION` changes the startup baud rate to 74880.
# 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://nodemcu-build.com) 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 (particularly one with a much different size), you may need to run `file.format()` to re-format your flash filesystem.
You will know if you need to do this because your flash files disappeared, or they exist but seem empty, or data cannot be written to new files.
# 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.
# OPTIONAL MODULES
####Use DS18B20 module extends your esp8266
```lua
-- read temperature with DS18B20
node.compile("ds18b20.lua")-- run this only once to compile and save to "ds18b20.lc"