nodemcu / nodemcu-firmware

Lua based interactive firmware for ESP8266, ESP8285 and ESP32

NodeMCU 3.0.0

Lua-based firmware for ESP8266 WiFi SOC

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.

Summary

• Easy to program wireless node and/or access point
• Based on Lua 5.1.4 or Lua 5.3 but without debug, io, os and (most of the) math modules
• Asynchronous event-driven programming model
• More than 70 built-in C modules and close to 20 Lua modules
• Firmware available with or without floating point support (integer-only uses less memory)
• Up-to-date documentation at https://nodemcu.readthedocs.io

LFS support

In July 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!

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
wifi.setmode(wifi.STATION)
wifi.sta.config{ssid="SSID", pwd="password"}

Documentation

The entire NodeMCU documentation is maintained right in this repository at /docs. The fact that the API documentation is maintained 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.io.

Pages:

• How to build the firmware
• How to flash the firmware
• How to upload code and NodeMCU IDEs
• API documentation for every module

Releases

Due to the ever-growing number of modules available within NodeMCU, pre-built binaries are no longer made available. Use the automated custom firmware build service to get the specific firmware configuration you need, or consult the documentation for other options to build your own firmware.

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 the dev branch is merged back to release. They are listed in this repo's releases.

Tag names follow the <SDK-version>-release_yyyymmdd pattern.

Support

See https://nodemcu.readthedocs.io/en/release/support/.

License

MIT © zeroday/nodemcu.com

nodemcu-firmware's Issues

Current issues

Current issues I'm aware of.. the latest http: server demo, every time it is used, the heap drops - starting at 6k and dropping eventually to 3k at which point the board reboots. The heap management needs sorting other wise any kind of fast polling (remote phone monitoring of output state or similar) would be impossible.

Secondly - - the Telnet demo just fails. Two of us have tested both of these on different installations, same response. REALLY would appreciate any fixes.

Are you planning to use the new SDK?

Initial noise

Is there any way you can turn off the garbled characters that appear when you first switch on..
Also the wifi.sta.getip() - instead of being NULL could it return TRUE if a valid IP address is there or FALSE if not. Right now I have to check for "0.0.0.0" and I don't even know if that's reliable.

Thanks (sorry, not really BUGS as such) - thanks for latest update

Compiling issue

Hi,

first of all: great work! The pre-build binary works out of the box.
I'm trying to recompile the project in order to slightly extend some (fast) C functionality. However, I can't get it to work.

The GNU toolchain (https://github.com/esp8266/esp8266-wiki/wiki) reports the following errors:

1. xtensa/simcall-fcntl.h can not be found, I side loaded it from a forum post (no Idea whether it is the correct one)
2. XTENSA_WINDOWED_ABI seems not be defined in my environment. So, what is the correct value for _JBLEN?

It was also required to side load some more stuff:
wget -O lib/libc.a https://github.com/esp8266/esp8266-wiki/raw/master/libs/libc.a
wget -O lib/libhal.a https://github.com/esp8266/esp8266-wiki/raw/master/libs/libhal.a
wget -O include.tgz https://github.com/esp8266/esp8266-wiki/raw/master/include.tgz
tar -xvzf include.tgz

I managed to circumvent the errors and compile it. However, I had no luck running it. Trying both values for _JBLEN results always in the same issue:
The serial console displays "NodeMcu 0.9.4 build 20141222 powered by Lua 5.1.4" and a second or two later the ESP restarts.

Do you have experienced a similar behavior or do you have a hint for me?
Regards
Juergen

Readme.md

One sample seems to be wrong!

Write network application in nodejs style

-- A simple http client
conn=net.createConnection(net.TCP, 0) 
conn:on("receive", function(conn, payload) print(c) end )
conn:connect(80,"115.239.210.27")
conn:send("GET / HTTP/1.1\r\nHost: www.baidu.com\r\n"
    .."Connection: keep-alive\r\nAccept: */*\r\n\r\n")

SHOULD BE???

conn:on("receive", function(conn, payload) print(payload) end )

AP list isn't work correct

Hi. Subj.
Hardware: ESP-01 module.
firmfare: 0.9.2, 0.9.4 versions
When I trying apply it, module rebooting.

Possible, it rebooting because WDT not resetting, but I couldn't find how to stop WDT or get list AP.

set fixed IP adress

is it posible to set fixed ip, gateway and dns or only DHCP is option?

AP + captive portal?

Hi there,

I do not know is it a good place to ask this, but i wonder if there is any simple way of implementing captive portal on ESP? I mean something like the login page opened automatically after connecting to wifi hotspot in a hotel room.
I am not very experienced in network stuff like this...

Thanks in advance.

tmr.delay() is synchronous and blocks the network stack

It would be nice if this suspended the Lua interpreter for the duration of the delay and allowed the network stack to run. It appears to busy wait?

I think I can avoid this by recasting the code to be event driven and using the tmr.alarm() function with timers instead. Minimally, the current behavior ought to be documented and perhaps its use discouraged for all but very short delays.

sleep_type support

Hi,
Is sleep_type something new in the SDK from espressif ? If so is that something you will support ?

/Mihai

Myfile.lua example crashing on the long file.

example working fine with 20-30 line files but its crashing and module restarting without any message when reading long file(more than 55-60 lines)

uart to GPIO

Is it possible to disable the uart(Rx/Tx) ?

HTTP payload in chunks

Hi!

Wonder if HTTP payload could be delivered not in one concatted string but in set of smaller chunks (nil to denote end of data)? That would open the way to handle more data input and write more advanced servers.

TIA,
--Vladimir

tmr.delay() doesn't work with delays below 1s

In an attempt to work around the PWM issue, I tried to just bit-bang the signal I needed. Unfortunately, any call to tmr.delay() with value 999999 or less is simply ignored -- the method returns immediately, without any blocking or delay.

That means that currently the only way to get a delay smaller than one second is by doing an active wait loop.

Connect ds18b20 temprature sensor to nodemcu

It is possible to connect ds18b20 temprature sensor to nodemcu?

node.restart() - hangs

NodeMcu 0.9.2 build 20141209  powered by Lua 5.1.4

> node.restart();
> bB

MCU hangs, power off/on helps.

Can`t connect to open access point

Is there a way to connect to an open access point?
I get an error if i use wifi.sta.config("myssid","").

NTP

Hi!
ntp client in lua available?
Thank You

It seems not working http client

I flash this example :
sk=net.createConnection(net.TCP, 0)
sk:on("receive", function(sck, c) print(c) end )
sk:connect(80,"174.129.243.245")
sk:send("GET / HTTP/1.1\r\nHost: www.arduino.cc\r\nConnection: keep-alive\r\nAccept: /\r\n\r\n")

Do not get a response.
Сonnected to the point.
Is this true?

MQTT support

I think an MQTT library makes sense for this firmware and IoT stuff. I found this library, what would it take to port it? Unfortunately I don't know any LUA.

No source code available

Why is there no source code available? This is GitHub, designed for version control of software via it's source code. If there are any reasons why you don't put the code on GitHub please mention those in the readme. Thanks.

What is the difference in versions 1Mbytes, 2Mbytes, 4Mbytes?

What is the difference in versions 1Mbytes, 2Mbytes, 4Mbytes except size?
There's something not included, or what?

Driving Triac with ESP8266

Hello,
First of all thank you for your great work.

I want to ask if it is possible to drive a Triac and dim 220v lamp directly with ESP8266 without using MCU
Can I use the PWN functionality to achieve this?
Can you please provide me with some hints on how to do it?

wifi.startsmart not working.

this is due to the sdk 0.9.4
the sniffer api has changed, and no doc right now.

TCP server memory leak

TCP server currently quite unusable. Looses roughly 200 byte of heap memory for each request served.
Testcode:

srv=net.createServer(net.TCP)
srv:listen(80,function(conn)
    conn:on("receive",function(conn,payload)
        conn:send("<h1>Heap: "..node.heap().."</h1>\n")
        conn:close()
    end)
end)

If the time between request is in the order of seconds, heap constantly drops by 200 bytes per request until connection refused. If there is a long delay between two requests the all the missing heap gets freed and ther server is usable for some more requests.

Implementing Web Sockets

Hi Zeroday,

You think its possible to implement web sockets on ESP?

Think of it as we will be able to control all ESPs using a cloud server & there will be 2 way communication between all ESPs and the server!

Also this can provide a cloud based flashing tool for ESP, we will be able to flash the ESPs from anywhere!

Make Files

I'd like to have a play with this - having tried just about every binary up to now - it's great that you've made it open source. For the sake of us poor mortals on Windows who are just picking this up - I note on many of these projects they include 3 make files ... "makefile", "makefile.linux" and "makefile.windows" so that those in the Windows environment don't have to re-invent the wheel.. the MQTT project is one..

Any chance you could include those other makefiles?? I'm not sure I'd know where to start.

Saving current UART0 baud rate to EEPROM as default baud rate

If we set new baud rate with command "uart.setup()" - it's for current session only and after module reboot we must use default baud rate 9600 again.
New version of uart.setup:
uart.setup( id, baud, databits, parity, stopbits, echo, PERMANENT )
if permanent=1, then uart used new baud rate permanently, also after module restarted
(exactly AT-based firmware v0.20 SDK 0.9.4 command "AT+IPR")
Its feature very important for using ESP8266 with additional external MCU (Arduino, RaspberryPi, and so on)

Long Wifi Passwords

Unable to use wifi.sta.config() to connect to network if the password is too long.

Receiving this error:
lua: stdin:1: pwd:<64

GPIO set both direction and value at once

Hi!

Wonder if both GPIO direction and value could be set at once? The rationale is to avoid the time gap (btw, how long is it) between consequent calls gpio.mode and gpio.write, when pin goes through maybe unwanted state.

As an example, in linux they have "direction" and "value" sysfs files, direction may take either "in" or "out", value may take either "1" or "0". Plus direction may take either "high" or "low" which results in atomic transition to "output 1" and "output 0".

TIA,
--Vladimir

PWM > 500 Hz

Will a PWM-frequency > 500 Hz be supported in future, or are there hardware-limits?
Btw: how fast can be bit-banging?

new nodemcu bin based on 0.9.4

Hi,
Will you be making an new bin for the latest version ?

Decreasing Heap size

Hi,

Firstly, thanks for the great work, not only in creating this project, but also for your responsive updates and fixes. The modules, together with this project, are very exciting indeed.

However, one thing concerns me; I've noticed that as the updates keep coming and the API grows, the heap available to our Lua scripts is decreasing. I noted that, in the first two weeks in December, the available heap dropped by 6% and the updates have kept coming since. Am I correct in assuming that this is a result of the firmware expanding?

If so, is there any way that the API namespaces (for example ow, gpio, i2c) can start unloaded and are only loaded when require() is called? That way, libraries that I'm not using won't take up valuable heap space that my scripts could be using.

For example:

print(gpio)   --> nil
local gpio = require 'gpio'
print(gpio)   --> table
gpio.mode(9, gpio.OUTPUT)
-- etc

PWM doesn't work with frequencies below 77Hz

If you try to set the PWM frequency to anything below 77Hz (either with pwm.setup() or pwm.setclock()), then the resulting signal is the same as if the pin was in INPUT mode -- basically high all the time, with some noise.

It is maybe not an issue when you want to use the PWM for driving LEDs or motors, but RC servos usually require 50Hz signal, and you might also want to use that for generating sound using a speaker or buzzer (that's actually what I'm doing).

remote upgrade firmware...

will be nice posibility "remote upgrade firmware via wifi or from cloud..."
of course - from nodemcu.previous to nodemcu.next... :-)

Please add eeprom memory.

Add to firmware support eeprom memory(array).
Do it?.
thank you.

P.S: there are a few ideas and suggestions. Interested?

net.server.listen does not closes after server closed

a=net.createServer(net.TCP)
a:listen(8080,function(fc) ... end)
...
a:close()
b=net.createServer(net.TCP)
b:listen(80,function(fc) ... end)

Then NodeMCU answers at ports 8080 and 80, but should only 80

Crashing / reboot when connecting in crowded wifi environment

I am in a crowded wifi environment and LUA crashes and hence reboots when it doesn't manage to connect on first attempt ...

This doesn't happen with original firmware.

This either happens when executing wifi.sta.config or when booting if a previous connection was configured. Sometimes boot/crash loop happens 20 times then finally it connects and boots/runs fine ...

When running wifi.sta.disconnect it will boot fine again on first attempt ...

Maybe timeout issue ??

SPI support?

I see lots of references to this in the C headers, but is SPI support exposed in Lua?

Long connect to wifi network

Long connect to wifi network compared to the 014-12-08 version

How to get the remote IP address and port number on a server TCP connection?

If I create a local socket listening for connections, how do I get the remote host's IP address and port number?

Likewise, it would be nice to be able to do the same with UDP, though probably necessary on a packet-by-packet basis for an unconnected socket that might receive packets from multiple sources.

reboot loop when compiled from GNU toolchain, trying to do file operation.

don't know why yet.
probably file open mode conflict.
need more debug and test.

writing to socket from functions does not work

Hi,
this works:
sk=net.createConnection(net.TCP, 0)
sk:on("receive", function(sck, c) print(c) end )
sk:connect(5555,"192.168.1.8")
sk:send("HELLO")
sk:close()
print("sent to server")

but this does not:

function test()
sk=net.createConnection(net.TCP, 0)
sk:on("receive", function(sck, c) print(c) end )
sk:connect(5555,"192.168.1.8")
sk:send("HELLO")
sk:close()
print("sent to server")
end

Set serial baud rate

Hello,

It would be great to be able to set the serial baud rate higher than 9600bauds. I would like to use the module for audio streaming and that is why i'd need something like 115200bauds.

Is that possible?

Thank you,
Alex N

Open Source

@nodemcu: You stand nothing to lose by open-sourcing the code for this firmware.
I love this firmware. I don't like that we have to ask @nodemcu to fix bugs. If this were open source, the community could fix bugs.
I also have a problem with attaching a device with unknown firmware to my network.

get free memory

How to get count free memory and all memory.

User all memory 4 kb? Select in readme.

Example Web

Pls add more one example of web with parsing request

wifi.setmode(wifi.SOFTAP);
wifi.ap.config({ssid="test",pwd="12345678"});
gpio.mode(4, gpio.OUTPUT)
srv=net.createServer(net.TCP) 
srv:listen(80,function(conn) 
    conn:on("receive", function(client,request)
        local buf = "";
        local _, _, method, path, vars = string.find(request, "([A-Z]+) (.+)?(.+) HTTP");
        if(method == nil)then 
            _, _, method, path = string.find(request, "([A-Z]+) (.+) HTTP"); 
        end
        local _GET = {}
        if (vars ~= nil)then 
            for k, v in string.gmatch(vars, "(%w+)=(%w+)&*") do 
                _GET[k] = v 
            end 
        end
        buf = buf.."<h1> Hello, NodeMcu.</h1><form src=\"/\">Turn GPIO2 <select name=\"pin\" onchange=\"form.submit()\">";
        local _on,_off = "",""
        if(_GET.pin == "ON")then
              _on = " selected=true";
              gpio.write(4, gpio.HIGH);
        elseif(_GET.pin == "OFF")then
              _off = " selected=\"true\"";
              gpio.write(4, gpio.LOW);
        end
        buf = buf.."<option".._on..">ON</opton><option".._off..">OFF</option></select></form>";
        client:send(buf);
        client:close();
        collectgarbage();
    end)
end)

Getting the lua file to the ESP

Its not realy clear to me howto get a .lua file easy to the ESP?

Is this the only way?

--init.lua will be excuted
file.open("init.lua","w")
file.writeline([[print("Hello, do this at the beginning.")]])
file.close()
node.restart() -- this will restart the module.

GPIO pins not working when set to output

Hi, I have put some LED on 0,1,2,3 and only pin 1 is working ok, is this normal?
I set them as output, write HIGH or LOW, read value, but values does not change, and leds are not starting, except pin1, GPIO13 is working ok.

0 GPIO12 not working as output
1 GPIO13 working OK
2 GPIO14 not working as output
3 GPIO15 not working as output
8 GPIO0 can this pin be output?
9 GPIO2 can this pin be output?

Latest binaries in permanent, SDK independent folder

Hi!
When somebody post new article about NodeMCU firmware with link to binaries file, after new SDK released, link is outdated.
Please, make folder "latest" or "latest-binaries-512" or another, what you want, and copy latest binaries and do this after every new version.

Thanks.

Feature Request: Please add real-time clock

First of all: thanks for your great work!

Would it be possible to add a Lua interface to the (apparently) available real-time clock on the chip?

Thanks
Daniel

P.S.: are the sources of the firmware available somewhere?