nodeMcu API Instruction
version 0.9.2 build 2014-11-18
change log:
2014-11-18
bug fixed: as a tcp server, the connection can’t closed with :close().
tcp server: inactive connection will closed by server in 30s (previously 180s).
add a test api node.input() to put lua chunk into lua interpretor, multi-line supported.
add a test api node.ouput(function) to direct serial output to a callback function.
file.readline() now returns line include EOL(‘\n’), and returns nil when EOF.
2014-11-12
full version firmware
2014-11-11
add file.seek() api to file module
now max 6 pwm channel is supported
2014-11-10
change log module to file module
now file operation support multiple read/write
for now file module only allowed one file opened
2014-11-5
delete log operation api from node module
add log module
modify wifi module api
modify node.key long_press and short_press default function
key is triged only when key is released
Summary
- Easy to access wireless router
- Based on Lua 5.1.4, Developers are supposed to have experience with Lua Program language.
- Event-Drive programming modal.
- Build-in file, timer, pwm, i2c, net, gpio, wifi module.
- Serial Port BaudRate:9600
- Re-mapped GPIO pin, use the index to program gpio, i2c, pwm.
- GPIO Map Table:
| IO index | ESP8266 pin | IO index | ESP8266 pin |
|---|---|---|---|
| 0 | GPIO12 | 8 | GPIO0 |
| 1 | GPIO13 | 9 | GPIO2 |
| 2 | GPIO14 | 10 | GPIO4 |
| 3 | GPIO15 | 11 | GPIO5 |
| 4 | GPIO3 | ||
| 5 | GPIO1 | ||
| 6 | GPIO9 | ||
| 7 | GPIO10 |
Burn/Flash Firmware
Address
nodemcu_512k.bin: 0x00000
node module
node.restart()
Description
restart the chip.
Syntax
node.restart()
Parameters
nil
Returns
nil
Example
node.restart();
See also
node.dsleep()
Description
Enter deep sleep mode, wake up when timed out
Syntax
node.dsleep(us)
-Note: This function can only be used in the condition that esp8266 PIN32(RST) and PIN8(XPD_DCDC) are connected together.
Parameters
us: sleep time in micro second
Returns
nil
Example
node.dsleep(us);
See also
node.chipid()
Description
return chip ID
Syntax
node.chipid()
Parameters
nil
Returns
number:chip ID
Example
id = node.chipid();
See also
node.heap()
Description
return the remain HEAP size in bytes
Syntax
node.heap()
Parameters
nil
Returns
number: system heap size left in bytes
Example
heap_size = node.heap();
See also
node.key()
Description
define button function, button is connected to GPIO16.
Syntax
node.key(type, function())
Parameters
type: type is either string “long” or “short”. long: press the key for 3 seconds, short: press shortly(less than 3 seconds)
function(): user defined function which is called when key is pressed. If nil, cancling the user defined function.
Default function: long: change LED blinking rate, short: reset chip
Returns
nil
Example
node.key("long", function(){print('hello world')})
See also
node.led()
Description
setup the on/off time for led, which connected to GPIO16, multiplexing with node.key()
Syntax
node.led(low, high)
Parameters
Low: LED off time, LED keeps on when low=0. Unit: milliseconds, time resolution: 80~100ms
High: LED off time. Unit: milliseconds, time resolution: 80~100ms
Returns
nil
Example
-- turn led on forever.
node.led(0);
See also
node.input()
Description
accept a string and put the string into Lua interpretor.
same as pcall(loadstring(str)) but support multi seperated line.
Syntax
node.input(str)
Parameters
str: Lua chunk
Returns
nil
Example
-- never use node.input() in console. no effect.
sk:on("receive", function(conn, payload) node.input(payload) end)
See also
node.output()
Description
direct output from lua interpretor to a call back function.
Syntax
node.output(function(str), serial_debug)
Parameters
function(str): a function accept every output as str, and can send the output to a socket.
serial_debug: 1 output also show in serial. 0: no serial output.
Returns
nil
Example
function tonet(str)
sk:send(str)
-- print(str) WRONG!!! never ever print something in this function
-- because this will cause a recursive function call!!!
end
node.ouput(tonet, 1) -- serial also get the lua output.
See also
file module
file.remove()
Description
remove file from file system.
Syntax
file.remove(filename)
Parameters
filename: file to remove
Returns
nil
Example
-- remove "foo.lua" from file system.
file.remove("foo.lua")
See also
file.open()
Description
open file.
Syntax
file.open(filename, mode)
Parameters
filename: file to be opened, directories are not supported
mode:
“r”: read mode (the default)
“w”: write mode
“a”: append mode
“r+”: update mode, all previous data is preserved
“w+”: update mode, all previous data is erased
“a+”: append update mode, previous data is preserved, writing is only allowed at the end of file
Returns
nil
Example
-- open 'init.lua', print the first line.
file.open("init.lua", "r")
print(file.readline())
file.close()
See also
- file.close()
- file.readline()
file.close()
Description
close the file.
Syntax
file.close()
Parameters
nil
Returns
nil
Example
-- open 'init.lua', print the first line.
file.open("init.lua", "r")
print(file.readline())
file.close()
See also
- file.open()
- file.readline()
file.readline()
Description
read one line of file which is opened before.
Syntax
file.readline()
Parameters
nil
Returns
file content in string, line by line, include EOL(‘\n’)
return nil when EOF.
Example
-- print the first line of 'init.lua'
file.open("init.lua", "r")
print(file.readline())
file.close()
See also
file.writeline()
Description
write string to file and add a ‘\n’ at the end.
Syntax
file.writeline(string)
Parameters
string: content to be write to file
Returns
true: write ok.
nil: there is error
Example
-- open 'init.lua' in 'a+' mode
file.open("init.lua", "a+")
-- write 'foo bar' to the end of the file
file.writeline('foo bar')
file.close()
See also
file.write()
Description
write string to file.
Syntax
file.write(string)
Parameters
string: content to be write to file.
Returns
true: write ok.
nil: there is error
Example
-- open 'init.lua' in 'a+' mode
file.open("init.lua", "a+")
-- write 'foo bar' to the end of the file
file.write('foo bar')
file.close()
See also
- file.open()
- file.writeline()
file.flush()
Description
flush to file.
Syntax
file.flush()
Parameters
nil
Returns
nil
Example
-- open 'init.lua' in 'a+' mode
file.open("init.lua", "a+")
-- write 'foo bar' to the end of the file
file.write('foo bar')
file.flush()
file.close()
See also
- file.open()
- file.writeline()
file.seek()
Description
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.
Syntax
file.seek(whence, offset)
Parameters
whence:
“set”: base is position 0 (beginning of the file);
“cur”: base is current position;(default value)
“end”: base is end of file;
offset: default 0
Returns
success: returns the final file position
fail: returns nil
Example
-- open 'init.lua' in 'a+' mode
file.open("init.lua", "a+")
-- write 'foo bar' to the end of the file
file.write('foo bar')
file.flush()
file.seek("set")
print(file.readline())
file.close()
See also
- file.open()
- file.writeline()
file.list()
Description
list all files.
Syntax
file.list()
Parameters
nil
Returns
a lua table which contains the {file name: file size} pairs
Example
l = file.list();
for k,v in l do
print("name:"..k..", size:"..v)
end
See also
wifi module
CONSTANT
wifi.STATION, wifi.SOFTAP, wifi.STATIONAP
wifi.setmode(mode)
Description
setup wifi operation mode.
Syntax
wifi.setmode(mode)
Parameters
mode: value should be: wifi.STATION, wifi.SOFTAP or wifi.STATIONAP
Returns
current mode after setup
Example
wifi.setmode(wifi.STATION)
See also
wifi.getmode(mode)
Description
get wifi operation mode.
Syntax
wifi.getmode()
Parameters
nil
Returns
wifi operation mode
Example
print(wifi.getmode())
See also
wifi.startsmart()
Description
starts to auto configuration, if success set up ssid and pwd automatically .
Syntax
wifi.startsmart(channel, function succeed_callback())
Parameters
channel: 1~13, startup channel for searching, if nil, default to 6. 20 seconds for each channel.
succeed_callback: callback function called after configuration, which is called when got password and connected to AP.
Returns
nil
Example
wifi.startsmart(6, cb())
See also
wifi.stopsmart()
Description
stop the configuring process.
Syntax
wifi.stopsmart()
Parameters
nil
Returns
nil
Example
wifi.stopsmart()
See also
wifi.sta module
wifi.sta.config()
Description
set ssid and password in station mode.
Syntax
wifi.sta.config(ssid, password)
Parameters
ssid: string which is less than 32 bytes.
password: string which is less than 64 bytes.
Returns
nil
Example
wifi.sta.config("myssid","mypassword")
See also
- wifi.sta.connect()
- wifi.sta.disconnect()
wifi.sta.connect()
Description
connect to AP in station mode.
Syntax
wifi.sta.connect()
Parameters
nil
Returns
nil
Example
wifi.sta.connect()
See also
- wifi.sta.disconnect()
- wifi.sta.config()
wifi.sta.disconnect()
Description
disconnect from AP in station mode.
Syntax
wifi.sta.disconnect()
Parameters
nil
Returns
nil
Example
wifi.sta.disconnect()
See also
- wifi.sta.config()
- wifi.sta.connect()
wifi.sta.autoconnect()
Description
auto connect to AP in station mode.
Syntax
wifi.sta.autoconnect(auto)
Parameters
auto: 0 to disable auto connecting. 1 to enable auto connecting
Returns
nil
Example
wifi.sta.autoconnect()
See also
- wifi.sta.config()
- wifi.sta.connect()
- wifi.sta.disconnect()
wifi.sta.getip()
Description
get ip address in station mode.
Syntax
wifi.sta.getip()
Parameters
nil
Returns
ip address in string, for example:”192.168.0.111”
Example
-- print current ip
print(wifi.sta.getip())
See also
wifi.sta.getmac()
Description
get mac address in station mode.
Syntax
wifi.sta.getmac()
Parameters
nil
Returns
mac address in string, for example:”18-33-44-FE-55-BB”
Example
-- print current mac address
print(wifi.sta.getmac())
See also
wifi.ap module
wifi.ap.config()
Description
set ssid and password in ap mode.
Syntax
wifi.ap.config(cfg)
Parameters
cfg: lua table to setup ap.
Example:
cfg={}
cfg.ssid="myssid"
cfg.pwd="mypwd"
wifi.ap.setconfig(cfg)
Returns
nil
Example
wifi.ap.config(ssid, 'password')
See also
wifi.ap.getip()
Description
get ip in ap mode.
Syntax
wifi.ap.getip()
Parameters
nil
Returns
ip address in string, for example:”192.168.0.111”
Example
wifi.ap.getip()
See also
wifi.ap.getmac()
Description
get mac address in ap mode.
Syntax
wifi.ap.getmac()
Parameters
nil
Returns
mac address in string, for example:”1A-33-44-FE-55-BB”
Example
wifi.ap.getmac()
See also
timer module
tmr.delay()
Description
delay us micro seconds.
Syntax
tmr.dealy(us)
Parameters
us: delay time in micro second
Returns
nil
Example
-- delay 100us
tmr.delay(100)
See also
tmr.now()
Description
return the current value of system counter: uint32, us.
Syntax
tmr.now()
Parameters
nil
Returns
uint32: value of counter
Example
-- print current value of counter
print(tmr.now())
See also
tmr.alarm()
Description
alarm time.
Syntax
tmr.alarm(interval, repeat, function do())
Parameters
Interval: alarm time, unit: millisecond
repeat: 0 - one time alarm, 1 - repeat
function do(): callback function for alarm timed out
Returns
nil
Example
-- print "hello world" every 1000ms
tmr.alarm(1000, 1, function() print("hello world") end )
See also
tmr.stop()
Description
stop alarm.
-Note: only one alarm is allowed, the previous one would be replaced if tmr.alarm() called again before tmr.stop().
Syntax
tmr.stop()
Parameters
nil.
Returns
nil
Example
-- print "hello world" every 1000ms
tmr.alarm(1000, 1, function() print("hello world") end )
-- something else
-- stop alarm
tmr.stop()
See also
GPIO module
CONSTANT
gpio.OUTPUT, gpio.INPUT, gpio.INT, gpio.HIGH, gpio.LOW
gpio.mode()
Description
initialize pin to GPIO mode, set the pin in/out mode.
Syntax
gpio.mode(pin, mode)
Parameters
pin: 0~11, IO index
mode: gpio.OUTPUT or gpio.INPUT, or gpio.INT(interrupt mode)
Returns
nil
Example
-- set gpio 0 as output.
gpio.mode(0, gpio.OUTPUT)
See also
gpio.read()
Description
read pin value.
Syntax
gpio.read(pin)
Parameters
pin: 0~11, IO index
Returns
number:0 - low, 1 - high
Example
-- read value of gpio 0.
gpio.read(0)
See also
gpio.write()
Description
set pin value.
Syntax
gpio.write(pin)
Parameters
pin: 0~11, IO index
level: gpio.HIGH or gpio.LOW
Returns
nil
Example
-- set pin index 1 to GPIO mode, and set the pin to high.
pin=1
gpio.mode(pin, gpio.OUTPUT)
gpio.write(pin, gpio.HIGH)
See also
gpio.trig()
Description
set the interrupt callback function for pin.
Syntax
gpio.trig(pin, type, function(level))
Parameters
pin: 0~11, IO index
type: “up”, “down”, “both”, “low”, “high”, which represent rising edge, falling edge, both edge, low level, high level trig mode separately.
function(level): callback function when triggered. The gpio level is the param. Use previous callback function if undefined here.
Returns
nil
Example
-- use pin 0 as the input pulse width counter
pulse0 = 0
du = 0
gpio.mode(0,gpio.INT)
function pin0cb(level)
du = tmr.now() – pulse0
print(du)
pulse0 = tmr.now()
if level == 1 then gpio.trig(0, "down ") else gpio.trig(0, "up ") end
end
gpio.trig(0, "down ",pin0cb)
See also
PWM module
pwm.setup()
Description
set pin to PWM mode. Only 3 pins can be set to PWM mode at the most.
Syntax
pwm.setup(pin, clock, duty)
Parameters
pin: 0~11, IO index
clock: 1~500, pwm frequency
duty: 0~100, pwm duty cycle in percentage
Returns
nil
Example
-- set pin index 0 as pwm output, frequency is 100Hz, duty cycle is 50-50.
pwm.setup(0, 100, 50)
See also
pwm.close()
Description
quit PWM mode for specified pin.
Syntax
pwm.close(pin)
Parameters
pin: 0~11, IO index
Returns
nil
Example
pwm.close(0)
See also
pwm.start()
Description
pwm starts, you can detect the waveform on the gpio.
Syntax
pwm.start(pin)
Parameters
pin: 0~11, IO index
Returns
nil
Example
pwm.start(0)
See also
pwm.stop()
Description
pause the output of PWM waveform.
Syntax
pwm.stop(pin)
Parameters
pin: 0~11, IO index
Returns
nil
Example
pwm.stop(0)
See also
pwm.setclock()
Description
set pwm frequency for pin.
-Note: setup pwm frequency will synchronously change others if there are any. Only one PWM frequency can be allowed for the system.
Syntax
pwm.setclock(pin, clock)
Parameters
pin: 0~11, IO index.
clock: 1~500, pwm frequency.
Returns
nil
Example
pwm.setclock(0, 100)
See also
pwm.getclock()
Description
get pwm frequency of pin.
Syntax
pwm.getclock(pin)
Parameters
pin: 0~11, IO index.
Returns
number:pwm frequency of pin
Example
print(pwm.getclock(0))
See also
pwm.setduty()
Description
set duty clycle for pin.
Syntax
pwm.setduty(pin, duty)
Parameters
pin: 0~11, IO index
duty: 0~100, pwm duty cycle in percentage
Returns
nil
Example
pwm.setduty(0, 50)
See also
pwm.getduty()
Description
get duty clycle for pin.
Syntax
pwm.getduty(pin)
Parameters
pin: 0~11, IO index
Returns
nil
Example
-- D0 is connected to green led
-- D1 is connected to blue led
-- D2 is connected to red led
pwm.setup(0,500,50)
pwm.setup(1,500,50)
pwm.setup(2,500,50)
pwm.start(0)
pwm.start(1)
pwm.start(2)
function led(r,g,b)
pwm.setduty(0,g)
pwm.setduty(1,b)
pwm.setduty(2,r)
end
led(50,0,0) -- set led to red
led(0,0,50) -- set led to blue.
See also
net module
CONSTANT
net.TCP, net.UDP
net.createServer()
Description
create a server.
Syntax
net.createServer(type, secure)
Parameters
type: net.TCP or net.UDP
secure: true or false, true for safe link, false for ordinary link
Returns
net.server sub module
Example
net.createServer(net.TCP, true)
See also
net.createConnection()
Description
create a client.
Syntax
net.createConnection(type, secure)
Parameters
type: net.TCP or net.UDP
secure: true or false, true for safe link, false for ordinary link
Returns
net.server sub module
Example
net.createConnection(net.UDP, false)
See also
net.server module
listen()
Description
listen on port from [ip] address.
Syntax
net.server.listen(port,[ip],function(net.socket))
Parameters
port: port number
ip:ip address string, can be omitted
function(net.socket): callback function, pass to Caller function as param if a connection is created successfully
Returns
nil
Example
-- create a server
sv=net.createServer(net.TCP, false)
-- server listen on 80, if data received, print data to console, and send "hello world" to remote.
sv:listen(80,function(c)
c:on("receive", function(sck, pl) print(pl) end)
c:send("hello world")
end)
See also
close()
Description
close server.
Syntax
net.server.close()
Parameters
nil
Returns
nil
Example
-- create a server
sv=net.createServer(net.TCP, false)
-- close server
sv:close()
See also
net.socket module
connect()
Description
connect to remote.
Syntax
connect(port, ip)
Parameters
port: port number
ip: ip address in string
Returns
nil
See also
send()
Description
send data to remote via connection.
Syntax
send(string, function(sent))
Parameters
string: data in string which will be sent to remote
function(sent): callback function for sending string
Returns
nil
See also
on()
Description
register callback function for event.
Syntax
on(event, function cb())
Parameters
event: string, which can be: “connection”, “reconnection”, “disconnection”, “receive”, “sent”
function cb(net.socket, [string]): callback function. The first param is the socket.
If event is”receive”, the second param is received data in string.
Returns
nil
Example
sk=net.createConnection(net.TCP, false)
sk:on("receive", function(sck, c) print(c) end )
sk:connect(80,"192.168.0.66")
sk:send("GET / HTTP/1.1\r\nHost: 192.168.0.66\r\nConnection: keep-alive\r\nAccept: */*\r\n\r\n")
See also
close()
Description
close socket.
Syntax
close()
Parameters
nil
Returns
nil
See also
dns()
Description
get domain ip
Syntax
dns(domain, function(net.socket, ip))
Parameters
domain: domain name.
function (net.socket, ip): callback function. The first param is the socket, the second param is the ip address in string.
Returns
nil
See also
i2c module
CONSTANT
i2c.SLOW, i2c.TRANSMITTER, i2c. RECEIVER. FAST（400k）is not supported for now.
i2c.setup()
Description
initialize i2c.
Syntax
i2c.setup(id, pinSDA, pinSCL, speed)
Parameters
id = 0
pinSDA: 0~11, IO index
pinSCL: 0~11, IO index
speed: i2c.SLOW
Returns
nil
See also
i2c.start()
Description
start i2c transporting.
Syntax
i2c.start(id)
Parameters
id = 0
Returns
nil
See also
i2c.stop()
Description
stop i2c transporting.
Syntax
i2c.stop(id)
Parameters
id = 0
Returns
nil
See also
i2c.address()
Description
setup i2c address and read/write mode.
Syntax
i2c.address(id, device_addr, direction)
Parameters
id=0
device_addr: device address.
direction: i2c.TRANSMITTER for writing mode , i2c. RECEIVER for reading mode
Returns
nil
See also
i2c.write()
Description
write data to i2c, data can be multi numbers, string or lua table.
Syntax
i2c.write(id, data1, data2,…)
Parameters
id=0
data: data can be numbers, string or lua table.
Returns
nil
Example
i2c.write(0, "hello", "world")
See also
i2c.read()
Description
read data for len bytes.
Syntax
i2c.read(id, len)
Parameters
id=0
len: data length
Returns
string:data received.
Example
id=0
sda=1
scl=0
-- initialize i2c, set pin1 as sda, set pin0 as scl
i2c.setup(id,sda,scl,i2c.SLOW)
-- user defined function: read from reg_addr content of dev_addr
function read_reg(dev_addr, reg_addr)
i2c.start(id)
i2c.address(id, dev_addr ,i2c.TRANSMITTER)
i2c.write(id,reg_addr)
i2c.stop(id)
i2c.start(id)
i2c.address(id, dev_addr,i2c.RECEIVER)
c=i2c.read(id,1)
i2c.stop(id)
return c
end
-- get content of register 0xAA of device 0x77
reg = read_reg(0x77, 0xAA)
pirnt(string.byte(reg))