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()
+- file.close()
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.open()
+- file.close()
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.open()
+- file.write()
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.mode()
+- gpio.read()
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
+- gpio.mode()
+- gpio.write()
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))
+
+