Home

NodeMCU/Linux Wiki

NodeMCU/Linux aims to target following hardware running a Debian-based Linux:

• Raspberry series (like Raspberry Pi 3, Raspberry Pi Zero) running Raspbian
• Orange Pi series (like Orange Pi Zero, Orange Pi Lite, etc) running Armbian
• NanoPi series (like NanoPi Neo, etc) running Armbian

detailed list of supported devices will be published as soon gpio and i2c modules are more complete and tested.

How To Implement

• majority of the modules are meant to be implemented with Lua itself and external modules via luarocks
• if hardware-near implementation is needed:
  • Lua 5.1 and luaffifb module https://github.com/facebookarchive/luaffifb
  • LuaJIT FFI: http://luajit.org/ext_ffi.html interfacing C functions and structures (parses string to extract struct information) NOTE: currently luajit is disregarded, but lua5.1 is used
• ...

Modules

Following modules are aimed to implement NodeMCU/Linux mainly based on the NodeMCU/ESP8266 API and partially on NodeMCU/ESP32 API:

adc

Functions (bold=implemented):

• adc.force_init_mode() Checks and if necessary reconfigures the ADC mode setting in the ESP init data block.
• adc.read() Samples the ADC.
• adc.readvdd33() Reads the system voltage.

ads1115

adxl345

am2320

apa102

bit

State: built-in

Notes:

• Lua 5.1: using bitop module
• Lua 5.3: it's included https://www.lua.org/manual/5.3/manual.html#3.4.2

bme280

bmp085

coap

cron

Functions (bold=implemented):

• cron.schedule() Creates a new schedule entry.
• cron.reset() Removes all scheduled entries.
• cron.entry:handler() Sets a new handler for entry.
• cron.entry:schedule() Sets a new schedule mask.
• cron.entry:unschedule() Disables schedule.

crypto

dht

ds18b20

encoder

enduser setup

file

State: most functionality implemented with io module, vastly untested

Functions (bold=implemented):

• file.chdir() Change current directory (and drive).
• file.exists() Determines whether the specified file exists.
• file.format() Format the file system.
• file.fscfg() Returns the flash address and physical size of the file system area, in bytes.
• file.fsinfo() Return size information for the file system.
• file.list() Lists all files in the file system.
• file.mount() Mounts a FatFs volume on SD card.
• file.on() Registers callback functions.
• file.open() Opens a file for access, potentially creating it (for write modes).
• file.remove() Remove a file from the file system.
• file.rename() Renames a file.
• file.stat() Get attribtues of a file or directory in a table.
• file.close(), file.obj:close() Closes the open file, if any.
• file.flush(), file.obj:flush() Flushes any pending writes to the file system, ensuring no data is lost on a restart.
• file.read(), file.obj:read() Read content from the open file.
• file.readline(), file.obj:readline() Read the next line from the open file.
• file.seek(), file.obj:seek() Sets and gets the file position, measured from the beginning of the file, to the position given by offset plus a base specified by the string whence.
• file.write(), file.obj:write() Write a string to the open file.
• file.writeline(), file.obj:writeline() Write a string to the open file and append '\n' at the end.

gdbstub

gpio

State: partially implemented but entirely untested

Functions (bold=implemented):

• gpio.mode() Initialize pin to GPIO mode, set the pin in/out direction, and optional internal weak pull-up.
• gpio.read() Read digital GPIO pin value.
• gpio.serout() Serialize output based on a sequence of delay-times in µs.
• gpio.trig() Establish or clear a callback function to run on interrupt for a pin.
• gpio.write() Set digital GPIO pin value.

Notes:

• https://github.com/vsergeev/lua-periphery
• https://github.com/Tieske/rpi-gpio assumes Raspberry Pi

hdc1080

hmc5883l

http

State: partial implemented (only http.get)

Notes:

• partial Lua implementation exists at https://github.com/Spiritdude/nodemcu-shell/blob/master/lib/http.lua (depends on net module)

hx711

i2c

State: basic incomplete and untested skeleton

Notes:

• https://github.com/vsergeev/lua-periphery

l3g4200d

math

Status: built-in

Notes:

• ESP8266: not available
• ESP32: experimentally available
• Linux: built-in

mcp4725

mdns

mqtt

net

Notes:

• https://github.com/diegonehab/luasocket
• https://github.com/ignacio/luanode

Functions (bold=implemented):

• net.createConnection() Creates a client.
• net.createServer() Creates a server.
• net.createUDPSocket() Creates an UDP socket.
• net.multicastJoin() Join multicast group.
• net.multicastLeave() Leave multicast group.
• net.server:close() Closes the server.
• net.server:listen() Listen on port from IP address.
• net.server:getaddr() Returns server local address/port.
• net.socket:close() Closes socket.
• net.socket:connect() Connect to a remote server.
• net.socket:dns() Provides DNS resolution for a hostname.
• net.socket:getpeer() Retrieve port and ip of remote peer.
• net.socket:getaddr() Retrieve local port and ip of socket.
• net.socket:hold() Throttle data reception by placing a request to block the TCP receive function.
• net.socket:on() Register callback functions for specific events.
• net.socket:send() Sends data to remote peer.
• net.socket:ttl() Changes or retrieves Time-To-Live value on socket.
• net.socket:unhold() Unblock TCP receiving data by revocation of a preceding hold().
• net.udpsocket:close() Closes UDP socket.
• net.udpsocket:listen() Listen on port from IP address.
• net.udpsocket:on() Register callback functions for specific events.
• net.udpsocket:send() Sends data to specific remote peer.
• net.udpsocket:dns() Provides DNS resolution for a hostname.
• net.udpsocket:getaddr() Retrieve local port and ip of socket.
• net.udpsocket:ttl() Changes or retrieves Time-To-Live value on socket.
• net.dns.getdnsserver() Gets the IP address of the DNS server used to resolve hostnames.
• net.dns.resolve() Resolve a hostname to an IP address.
• net.dns.setdnsserver() Sets the IP of the DNS server used to resolve hostnames.

node

State: partially implemented, but untested

Functions (bold=implemented):

• node.bootreason() Returns the boot reason and extended reset info.
• node.chipid() Returns the ESP chip ID.
• node.compile() Compiles a Lua text file into Lua bytecode, and saves it as .
• node.dsleep() Enters deep sleep mode, wakes up when timed out.
• node.flashid() Returns the flash chip ID.
• node.flashsize() Returns the flash chip size in bytes.
• node.heap() Returns the current available heap size in bytes.
• node.info() Returns NodeMCU version, chipid, flashid, flash size, flash mode, flash speed, architecture (new: 'esp8266', 'esp32', or 'linux')
• node.input() Submits a string to the Lua interpreter.
• node.output() Redirects the Lua interpreter output to a callback function.
• node.restart() Restarts the chip/device, NOTE: nodemcu must be run as root (e.g. via sudo nodemcu)
• node.restore()
• node.setcpufreq() Change the working CPU Frequency (for Allwinner H2/H3)
• node.sleep() Put NodeMCU in light sleep mode to reduce current consumption.
• node.stripdebug() Controls the amount of debug information kept during node.
• node.osprint() Controls whether the debugging output from the SDK is printed.
• node.random() This behaves like math.
• node.egc.setmode() Sets the Emergency Garbage Collector mode.
• node.task.post() Enable a Lua callback or task to post another task request.

ow (1-Wire)

pcm

perf

pwm

rc

rfswitch

rotary

rtcfifo

rtcmem

rtctime

State: partially implemented, but untested

Functions (bold=implemented):

• rtctime.dsleep() Puts the device into deep sleep mode, like node.
• rtctime.dsleep_aligned() For applications where it is necessary to take samples with high regularity, this function is useful.
• rtctime.epoch2cal() Converts a Unix timestamp to calendar format.
• rtctime.get() Returns the current time.
• rtctime.set() Sets the rtctime to a given timestamp in the Unix epoch (i.

Notes:

• Lua implementation exists at https://github.com/Spiritdude/nodemcu-shell/blob/master/lib/rtctime.lua

si7021

sigma delta

sjson

Status: partially implemented

Functions (bold=implemented):

• sjson.encoder() This creates an encoder object that can convert a LUA object into a JSON encoded string.
• sjson.encoder:read() This gets a chunk of JSON encoded data.
• sjson.encode() Encode a Lua table to a JSON string.
• sjson.decoder() This makes a decoder object that can parse a JSON encoded string into a lua object.
• sjson.decoder:write() This provides more data to be parsed into the lua object.
• sjson.decoder:result() This gets the decoded lua object, or raises an error if the decode is not yet complete.
• sjson.decode() Decode a JSON string to a Lua table.

Notes: Either use

• https://github.com/rxi/json.lua or
• https://github.com/nodemcu/nodemcu-firmware/blob/master/app/modules/sjson.c or
• lunajson

sntp

• sntp.sync() Attempts to obtain time synchronization.
• sntp.setoffset() Sets the offset between the rtc clock and the NTP time.
• sntp.getoffset() Gets the offset between the rtc clock and the NTP time.

somfy

spi

Notes:

• https://github.com/vsergeev/lua-periphery

struct

State: built-in

Functions (bold=implemented):

• struct.pack()
• struct.unpack()

Notes:

• Using https://github.com/iryont/lua-struct or
• https://luarocks.org/modules/iryont/lua-struct

switec

tcs34725

tls

tm1829

tmr

State: only tmr.now() and tmr.time() implemented, new tmr.uptime() added, all tmr.create():xyz not yet implemented

Functions (bold=implemented):

• tmr.now() Returns the system counter, which counts in microseconds.
• tmr.time() Returns the system uptime, in seconds (integer)
• **tmr.uptime() (new) Returns the system uptime in seconds with microsecond precision (float)
• tmr.alarm() This is a convenience function combining tmr.
• tmr.create() Creates a dynamic timer object.
• tmr.delay() Busyloops the processor for a specified number of microseconds.
• tmr.interval() Changes a registered timer's expiry interval.
• tmr.register() Configures a timer and registers the callback function to call on expiry.
• tmr.resume() Resume an individual timer.
• tmr.resume_all() Resume all timers.
• tmr.softwd() Provides a simple software watchdog, which needs to be re-armed or disabled before it expires, or the system will be restarted.
• tmr.start() Starts or restarts a previously configured timer.
• tmr.state() Checks the state of a timer.
• tmr.stop() Stops a running timer, but does not unregister it.
• tmr.suspend() Suspend an armed timer.
• tmr.suspend_all() Suspend all currently armed timers.
• tmr.unregister() Stops the timer (if running) and unregisters the associated callback.
• tmr.wdclr() Feed the system watchdog.

tsl2561

u8g

u8g2

uart

Notes:

• https://github.com/vsergeev/lua-periphery

ucg

websocket

Notes:

• https://github.com/lipp/lua-websockets

wifi

Functions (bold=implemented):

based on NodeMCU/ESP32 wifi API:

• wifi.getchannel() Gets the current WiFi channel.
• wifi.getmode() Gets WiFi operation mode.
• wifi.mode() Configures the WiFi mode to use.
• wifi.start() Starts the WiFi interface(s).
• wifi.stop() Shuts down the WiFi interface(s).
• wifi.sta.config() Sets the WiFi station configuration.
• wifi.sta.connect() Connects to the configured AP in station mode.
• wifi.sta.disconnect() Disconnects from AP in station mode.
• wifi.sta.on() Registers callbacks for WiFi station status events.
• wifi.sta.getmac() Gets MAC address in station mode.
• wifi.sta.scan() Scan for available networks.
• wifi.ap.config() Configures the AP.
• wifi.ap.on() Registers callbacks for WiFi AP events.
• wifi.ap.getmac() Gets MAC address in access point mode.

and a few from ESP8266 wifi API:

• wifi.sta.gethostname()
• wifi.sta.sethostname()
• wifi.sta.status()
• wifi.sta.getmac()

wps

ws2801

ws2812

xpt2046