nodeMcu API Instruction
-version 0.2 2014-11-10
-change log:
-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
NodeMcu
+A lua based firmware for wifi-soc esp8266
+version 0.9.2 2014-11-12
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. +
- Based on Lua 5.1.4 +
- Event-Drive programming preferred. +
- Build-in file, timer, pwm, i2c, net, gpio, wifi, and system api. +
- GPIO pin re-mapped, use the index to access gpio, i2c, pwm.
- GPIO Map Table:
Firmware Program
-Address
-eagle.app.v6.flash.bin: 0x00000
-eagle.app.v6.irom0text.bin: 0x10000
-esp_init_data_default.bin: 0x7c000
-blank.bin: 0x7e000
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.
-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
-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
- -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
-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)) -