3.8 KiB

Raw Blame History

NodeMCU Documentation

NodeMCU is an open source Lua based firmware for the ESP32 and ESP8266 WiFi SOCs from Espressif. It uses an on-module flash-based SPIFFS file system. NodeMCU is implemented in C and the ESP8266 version 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 runs on any ESP module.

→ Getting Started

!!! important

The NodeMCU [`release`](https://github.com/nodemcu/nodemcu-firmware/tree/release) and [`dev`](https://github.com/nodemcu/nodemcu-firmware/tree/dev) branches target the ESP8266. The [`dev-esp32`](https://github.com/nodemcu/nodemcu-firmware/tree/dev-esp32) branch targets the ESP32.

Programming Model

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 (DO NOT save config to flash)
wifi.setmode(wifi.STATION)
station_cfg={}
station_cfg.ssid = "SSID"
station_cfg.pwd = "password"
station_cfg.save = false
wifi.sta.config(station_cfg)

-- register event callbacks for WiFi events
wifi.eventmon.register(wifi.eventmon.STA_CONNECTED, function(T)
  print("\n\tSTA - CONNECTED".."\n\tSSID: "..T.SSID.."\n\tBSSID: "..
  T.BSSID.."\n\tChannel: "..T.channel)
end)

-- manipulate hardware like with Arduino
pin = 1
gpio.mode(pin, gpio.OUTPUT)
gpio.write(pin, gpio.HIGH)
print(gpio.read(pin))

→ Getting Started

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!

Releases

This project uses two main branches, release and dev. dev is actively worked on and it's also where PRs should be created against. release thus can be considered "stable" even though there are no automated regression tests. The goal is to merge back to release 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 release branch. They are listed in the releases section on GitHub. Tag names follow the <SDK-version>-release_yyyymmdd pattern.

Up-To-Date Documentation

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.

3.8 KiB Raw Blame History