NodeMCU is an open source Lua based firmware for the ESP8266 WiFi SOC from Espressif and uses an on-module flash-based SPIFFS file system. NodeMCU is implemented in C and is layered on the Espressif NON-OS SDK.
The firmware was initially developed as is a companion project to the popular ESP8266-based NodeMCU development modules, but the project is now community-supported, and the firmware can now be run on any ESP module.
The NodeMCU programming model is similar to that of 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 folder in the repository on GitHub.
-- a simple HTTP server srv = net.createServer(net.TCP) srv:listen(80, function(conn) conn:on("receive", function(sck, payload) print(payload) sck:send("HTTP/1.0 200 OK\r\nContent-Type: text/html\r\n\r\n<h1> Hello, NodeMCU.</h1>") end) conn:on("sent", function(sck) sck:close() end) end)
-- connect to WiFi access point wifi.setmode(wifi.STATION) wifi.sta.config("SSID", "password")
-- register event callbacks for WiFi events wifi.sta.eventMonReg(wifi.STA_CONNECTING, function(previous_state) if(previous_state==wifi.STA_GOTIP) then print("Station lost connection with access point. Attempting to reconnect...") else print("STATION_CONNECTING") end end)
-- manipulate hardware like with Arduino pin = 1 gpio.mode(pin, gpio.OUTPUT) gpio.write(pin, gpio.HIGH) print(gpio.read(pin))
Lua Flash Store (LFS)¶
In September 2018 support for a Lua Flash Store (LFS) was introduced. LFS allows Lua code and its associated constant data to be executed directly out of flash-memory; just as the firmware itself is executed. This now enables NodeMCU developers to create Lua applications with up to 256Kb Lua code and read-only constants executing out of flash. All of the RAM is available for read-write data!
This project uses two main branches,
dev is actively worked on and it's also where PRs should be created against.
master thus can be considered "stable" even though there are no automated regression tests. The goal is to merge back to
master roughly every 2 months. Depending on the current "heat" (issues, PRs) we accept changes to
dev for 5-6 weeks and then hold back for 2-3 weeks before the next snap is completed.
A new tag is created every time
dev is merged back to
master. They are listed in the releases section on GitHub. Tag names follow the
At the moment the only up-to-date documentation maintained by the current NodeMCU team is in English. It is part of the source code repository (
/docs subfolder) and kept in sync with the code.