-
* * * Work in Progress * * *
I have started a thread on the ESP8266 forum, Discussions on my nodeMCU Lua unofficial FAQ. Please use this to discuss any issues that you have with this FAQ; any areas where you feel that the explanation is unclear or needs further expansion; or any or Qs that you feel need answering and would help others if they were included here. Thank-you. Terry Ellison
This FAQ does not aim to help you to learn to program or even how to program in Lua. There are plenty of resources on the Internet for this, some of which are listed in Where to start. What this FAQ does is to answer some of the common questions that a competent Lua developer would ask in learning how to develop Lua applications for the ESP8266 based boards running the nodeMCU firmware.
The nodeMCU firmware implements Lua 5.1 over the Espressif SDK for its ESP8266 SoC and the IoT modules based on this.
Whilst the Lua standard distribution includes a host stand-alone Lua interpreter, Lua itself is primarily an extension language that makes no assumptions about a “main” program: Lua works embedded in a host application to provide a powerful, light-weight scripting language for use within the application. This host application can then invoke functions to execute a piece of Lua code, can write and read Lua variables, and can register C functions to be called by Lua code. Through the use of C functions, Lua can be augmented to cope with a wide range of different domains, thus creating customized programming languages sharing a syntactical framework.
The ESP8266 was designed and is fabricated in China by Espressif Systems. Espressif have also developed and released a companion software development kit (SDK) to enable developers to build practical IoT applications for the ESP8266. The SDK is made freely available to developers in the form of binary libraries and SDK documentation. However this is in a closed format, with no developer access to the source files, so ESP8266 applications must rely solely on the SDK API (and the somewhat Spartan SDK API documentation).
The nodeMCU Lua firmware is an ESP8266 application and must therefore be layered over the ESP8266 SDK. However, the hooks and features of Lua enable it to be seamlessly integrated without loosing any of the standard Lua language features. The firmware has replaced some standard Lua modules that don't align well with the SDK structure with ESP8266-specific versions. For example, the standard io
and os
libraries don't work, but have been largely replaced by the nodeMCU node
and file
libraries. The debug
and math
libraries have also been omitted to reduce the runtime footprint.
NodeMCU Lua is based on eLua, a fully featured implementation of Lua 5.1 that has been optimized for embedded system development and execution to provide a scripting framework that can be used to deliver useful applications within the limited RAM and Flash memory resources of embedded processors such as the ESP8266. One of the main changes introduced in the eLua fork is to use read-only tables and constants wherever practical for library modules. On a typical build this approach reduces the RAM footprint by some 20-25KB and this makes a Lua implementation for the ESP8266 feasible. This technique is called LTR and this is documented in detail in an eLua technical paper: Lua Tiny RAM.
The mains impacts of the ESP8266 SDK and together with its hardware resource limitations are not in the Lua language implementation itself, but in how application programmers must approach developing and structuring their applications. As discussed in detail below, the SDK is non-preemptive and event driven. Tasks can be associated with given events by using the SDK API to registering callback functions to the corresponding events. Events are queued internally within the SDK, and it then calls the associated tasks one at a time, with each task returning control to the SDK on completion. The SDK states that if any tasks run for more than 10 mSec, then services such as Wifi can fail.
The nodeMCU libraries act as C wrappers around registered Lua callback functions to enable these to be used as SDK tasks. You must therefore use an Event-driven programming style in writing your ESP8266 Lua programs. Most programmers are used to writing in a procedural style where there is a clear single flow of execution, and the program interfaces to operating system services by a set of synchronous API calls to do network I/O, etc. Whilst the logic of each individual task is procedural, this is not how you code up ESP8266 applications.
core
, coroutine
, string
and table
are implemented.file
library.debug
library support. So you have to use 1980s-style “binary-chop” to locate errors and use print statement diagnostics though the systems UART interface. (This omission was largely because of the Flash memory footprint of this library, but there is no reason in principle why we couldn't make this library available in the near future as an custom build option).function table.pack()
will cause a runtime error because you can't write to the global table
. (Yes, there are standard sand-boxing techniques to achieve the same effect by using metatable based inheritance, but if you try to use this type of approach within a real application, then you will find that you run out of RAM before you implement anything useful.)init.lua
script. It then “listens” to the serial port for input Lua chunks, and executes them once syntactically complete. There is no luac
or batch support, although automated embedded processing is normally achieved by setting up the necessary event triggers in the init.lua
script.net
, tmr
, wifi
, etc.) use the SDK callback mechanism to bind Lua processing to individual events (for example a timer alarm firing). Developers should make full use of these events to keep Lua execution sequences short. If any individual task takes too long to execute then other queued tasks can time-out and bad things start to happen.socket:send()
are on consecutive lines in a Lua programme, then the first has completed by the time the second is executed. This is wrong. Each socket:send()
request simply queues the send operation for dispatch. Neither will start to process until the Lua code has return to is calling C function. Stacking up such requests in a single Lua task function burns scarce RAM and can trigger a PANIC. This true for timer, network, and other callbacks. It is even the case for actions such as requesting a system restart, as can be seen by the following example:<code Lua> node.restart(); for i = 1, 20 do print(“not quite yet – ”,i); end </code>
void userinit(void), defined by convention in the C module
usermain.c
, which it invokes on boot. The user_init()
function can be used to do any initialisation required and to call the necessary timer alarms or other SDK API calls to bind and callback routines to implement the tasks needed in response to any system events.tmr.alarm(id, interval, repeat, callback)
function. The calls a function in the tmr
library which registers a C function for this alarm using the SDK, and when this C function is called it then invokes the Lua callback.The nodeMCU firmware simply mirrors this structure at a Lua scripting level:
init.lua
is invoked on boot. This function module can be used to do any initialisation required and to call the necessary timer alarms or libary calls to bind and callback routines to implement the tasks needed in response to any system events.
This event-driven approach is very different to a conventional procedural implementation of Lua.
Consider a simple telnet example given in examples/fragment.lua
:
s=net.createServer(net.TCP) s:listen(23,function(c) con_std = c function s_output(str) if(con_std~=nil) then con_std:send(str) end end node.output(s_output, 0) c:on("receive",function(c,l) node.input(l) end) c:on("disconnection",function(c) con_std = nil node.output(nil) end) end)
This example defines five Lua functions:
Function | Defined in | Parameters | Callback? |
---|---|---|---|
Main | Outer module | … (Not used) | |
Connection listener | Main | c (connection socket) | |
s_output | Connection listener | str | Yes |
On Receive | Connection listener | c, l (socket, input) | Yes |
On Disconnect | Connection listener | c (socket) | Yes |
s
, constd
are global, and no upvalues are used. There is no “correct” order to define these in, but we could reorder this code for clarity (though doing this adds a few extra globals) and define these functions separately one another. However, let us consider how this is executed:
and
soutput
Main
is then assigning the created net.createServer()
to the global s
. The connection listener
closure is created and bound to a temporary variable which is then passed to the socket.listen()
as an argument. The routine then exits returning control to the firmware.soutput, and registers this function with the
node.output hook. Likewise the
on receive and
on disconnection are bound to temporary variables which are passed to the respective on handlers. We now have four Lua functions registered in the Lua runtime libraries associated with four events. This routine then exits returning control to the firmware.
* When a record is received, the on receive handler within the net library retrieves the reference to the
on receive Lua function and calls it passing it the record. This routine then passes this to the
node.input() and exits returning control to the firmware.
* The
node.input handler polls on an 80 mSec timer alarm. If a compete Lua chunk is available (either via the serial port or node input function), then it executes it and any output is then passed to the
note.output handler. which calls
soutput
function. Any pending sends are then processed.
* This cycle repeats until the other computer disconnects, and net
library disconnection handler then calls the Lua on disconnect
handler. This Lua routine dereferences the connected socket and closes the node.output
hook and exits returning control to the disconnect handler which garbage collects any associated sockets and registered on handlers.
Whilst this is all going on, The SDK can (and often will) schedule other event tasks in between these Lua executions (e.g. to do the actual TCP stack processing). The longest individual Lua execution in this example is only 18 bytecode instructions (in the main routine).
alarm(id, interval, repeat, function())
|
| node | key(type, function())
, output(function(str), serialdebug) |
| wifi |
startsmart(chan, function()),
sta.getap(function(table)) |
| net.server |
sk:listen(port,[ip],function(socket)) |
| net |
sk:on(event, function(socket, [, data])),
sk:send(string, function(sent)),
sk:dns(domain, function(socket,ip)) |
| gpio |
trig(pin, type, function(level)) |
| mqqt |
client:m:on(event, function(conn[, topic, data]) |
| uart |
uart.on(event, cnt, [function(data)], [runinput])
|
==== So how is context passed between Lua event tasks? ====
* It is important to understand that any event callback task is associated with a single Lua function. This function is executed from the relevant nodeMCU library C code using a luacall(). Even system initialisation which executes the
dofile(“init.lua”) can be treated as a special case of this. Each function can invoke other functions and so on, but it must ultimate return control to the C library code.
* By their very nature Lua
local variables only exist within the context of an executing Lua function, and so all locals are destroyed between these
luacall()
actions. No locals are retained across events.
* So context can only be passed between event routines by one of three mechanisms:
* Globals are by nature globally accessible. Any global will persist until explicitly dereference by reassigning nil
to it. Globals can be readily enumerated by a for k,v in pairs(_G) do
so their use is transparent.
* The File system is a special case of persistent global, so there is no reason in principle why it can't be used to pass context. However the ESP8266 file system uses flash memory and this has a limited write cycle lifetime, so it is best to avoid using the file system to store frequently changing content except as a mechanism of last resort.
* Upvalues. When a function is declared within an outer function, all of the local variables in the outer scope are available to the inner function. Since all functions are stored by reference the scope of the inner function might outlast the scope of the outer function, and the Lua runtime system ensures that any such references persist for the life of any functions that reference it. This standard feature of Lua is known as closure and is described in [Pil 6]. Such values are often called upvalues. Functions which are global or registered callbacks will persist between event routines, and hence any upvalues referenced by them can be used for passing context.
==== So how is the Lua Registry used and why is this important? ====
So all Lua callbacks are called by C wrapper functions that are themselves callback activated by the SDK as a result of a given event. Such C wrapper functions themselves frequently need to store state for passing between calls or to other wrapper C functions. The Lua registry is simply another Lua table which is used for this purpose, except that it is hidden from direct Lua access. Any content that needs to be saved is created with a unique key. Using a standard Lua table enables standard garbage collection algorithms to operate on its content.
Note that we have identified a number of cases where library code does not correctly clean up Registry content when closing out an action, leading to memory leaks.nil
them when you have done with them.
==== Can I encapsulate actions such as sending an email in a Lua function? ====
Think about the implications of these last few answers.
If you are used coding in a procedural paradigm then it is understandable that you consider using tmr.delay()
to time sequence your application. However as discussed in the previous section, with nodeMCU Lua you are coding in an event-driven paradigm.
If you look at the app/modules/tmr.c
code for this function, then you will see that it executes a low level etsdelayus(delay)
. This function isn't part of the nodeMCU code or the SDK; it's actually part of the xtensa-lx106 boot ROM, and is a simple timing loop which polls against the internal CPU clock. It does this with interrupts disabled, because if they are enabled then there is no guarantee that the delay will be as requested.
tmr.delay()
is really intended to be used where you need to have more precise timing control on an external hardware I/O (e.g. lifting a GPIO pin high for 20 μSec). It will achieve no functional purpose in pretty much every other usecase, as any other system code-based activity will be blocked from execution; at worst it will break your application and create hard-to-diagnose timeout errors.
The latest SDK includes a caution that if any (callback) task runs for more than 10 mSec, then the Wifi and TCP stacks might fail, so if you want a delay of more than 8 mSec or so, then using tmr.delay()
is the wrong approach. You should be using a timer alarm or another library callback, to allow the other processing to take place. As the nodeMCU documentation correctly advises (translating Chinese English into English): tmr.delay()
will make the CPU work in non-interrupt mode, so other instructions and interrupts will be blocked. Take care in using this function.
Most of us have fallen into the trap of creating an init.lua
that has a bug in it, which then causes the system to reboot and hence gets stuck in a reboot loop. If you haven't then you probably will do so at least once.
init.lua
as simple as possible – say configure the wifi and then start your app using a one-time tmr.alarm()
after a 2-3 sec delay. This delay is long enough to issue a file.remove(“init.lua”)
through the serial port and recover control that way.init.lua
by creating it as inittest.lua, say, and manually issuing a
dofile(“inittest.lua”)
through the serial port, and then only rename it when you are certain it is working as you require.node.compile()
to pre-compile any production code. This removes the debug information from the compiled code reducing its size by roughly 40%. (However this is still perhaps 1.5-2x larger than a LuaSrcDiet-compressed source format, so if SPIFFS is tight then you might consider leaving less frequently run modules in Lua format. If you do a compilation, then you should consider removing the Lua source copy from file system as there's little point in keeping both on the ESP8266.nil
dereferences the previous context of that variable. (Note that reference-based variables such as tables, strings and functions can have multiple variables referencing the same object, but once the last reference has been set to nil
, the collector will recover the storage.require()
library function creates a reference for the loaded module in the package.loaded
table, and this reference prevents the module from being garbage collected. To make a module volatile, you should remove this reference to the loaded module by setting its corresponding entry in package.loaded
to nil
. You can't do this in the outermost level of the module (since the reference is only created once execution has returned from the module code), but you can do it in any module function, and typically an initialisation function for the module, as in the following example:
<code Lua>local s=net.createServer(net.TCP) s:listen(80,function© require(“connector”).init© end) </code>
connector.lua
would be a standard module pattern except that the M.init()
routine must include the lines
<code Lua>
local M, module = {}, …function M.init(csocket) package.loaded[module]=nil
end
return M </code>
require()
will automatically search for connector.lc
followed by connector.lua
, so the code will work for both source and compiled variants.<code Lua>
local s=net.createServer(net.TCP) s:listen(80,function© require(“connector”)© end) </code>
local module = ... -- this is a situation where using an upvalue is essential! return function (csocket) package.loaded[module]=nil module = nil -- . . . end
-- . . . local s=net.createServer(net.TCP) local connector = require("connector") -- don't do this unless you've got the RAM available! s:listen(80,connector)
Note that there are two methods of saving compiled Lua to SPIFFS:
node.compile()
on the .lua
source file, which generates the equivalent bytecode .lc
file. This approach strips out all the debug line and variable information.loadfile()
to load the source file into memory, followed by string.dump()
to convert it in-memory to a serialised load format which can then be written back to a .lc
file. This approach creates a bytecode file which retains the debug information.
The memory footprint of the bytecode created by method (2) is the same as when executing source files directly, but the footprint of bytecode created by method (1) is typically 60% of this size, because the debug information is almost as large as the code itself. So using .lc
files generated by node.compile()
considerably reduces code size in memory – albeit with the downside that any runtime errors are extremely limited.
In general consider method (1) if you have stable production code that you want to run in as low a RAM footprint as possible. Yes, method (2) can be used if you are still debugging, but you will probably be changing this code quite frequently, so it is easier to stick with .lua
files for code that you are still developing.
Note that if you use require(“XXX”)
to load your code then this will automatically search for XXX.lc
then XXX.lua
so you don't need to include the conditional logic to load the bytecode version if it exists, falling back to the source version otherwise.
luac
against your source on your PC with the -l -s
option will give you a good idea of what your code will generate. The main difference between these two variants is the sizet for ESP8266 is 4 bytes rather than the 8 bytes sizet found on modern 64bit development PCs; and the eLua variants generate different access references for ROM data types. If you want to see what the string.dump()
version generates then drop the -s
option to retain the debug information..lc
files to the PC and disassemble then there. There are a number of Lua code disassemblers which can list off the compiled code that you application modules will generate, if
you have a script to upload files from your ESP8266 to your development PC. I use ChunkSpy which can be downloaded here , but you will need to apply the following patch so that ChunkSpy understands eLua data types:
<code diff>
— a/ChunkSpy-0.9.8/5.1/ChunkSpy.lua 2015-05-04 12:39:01.267975498 +0100
+++ b/ChunkSpy-0.9.8/5.1/ChunkSpy.lua 2015-05-04 12:35:59.623983095 +0100
@@ -2193,6 +2193,9 @@
config.AUTODETECT = true
elseif a == “–brief” then
config.DISPLAYBRIEF = truenode.heap()
regularly through your code.
Consider the output of dofile(“test1a.lua”)
on the following code compared to the equivalent where the function pnh()
is removed and the extra print(heap())
statement is placed inline:
-- test1b.lua collectgarbage() local heap = node.heap print(heap()) local function pnh() print(heap()) end pnh() print(heap())
Heap Value | Function Call | Inline |
---|---|---|
1 | 20712 | 21064 |
2 | 20624 | 21024 |
3 | 20576 | 21024 |
Here bigger means less RAM used.
Of course you should still use functions to structure your code and encapsulate common repeated processing, but just bear in mind that each function definition has a relatively high overhead for its header record and stack frame (compared to the 20 odd KB RAM available). So try to avoid overusing functions. If there are less than a dozen or so lines in the function then you should consider putting this code inline if it makes sense to do so.
luac
to generate a bytecode listing of your code and to validate new code syntactically before downloading to the ESP8266. This will also allow you to develop server-side applications and embedded applications in a common language. restore to default
option in advanced menu tab), or <TODO>
<TODO>
<TODO>