nodeMcu API Instruction

version 0.9.2 build 2014-11-18

change log:

2014-11-18

bug fixed: net.socket:connect() has no effect.

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

IO indexESP8266 pinIO indexESP8266 pin
0GPIO128GPIO0
1GPIO139GPIO2
2GPIO1410GPIO4
3GPIO1511GPIO5
4GPIO3
5GPIO1
6GPIO9
7GPIO10

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.
    -- a simple telnet server
    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)   -- re-direct output to function s_ouput.
       c:on("receive",function(c,l) 
          node.input(l)           -- works like pcall(loadstring(l)) but support multiple separate line
       end) 
       c:on("disconnection",function(c) 
          con_std = nil 
          node.output(nil)        -- un-regist the redirect output function, output goes to serial
       end) 
    end)

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

- file.remove()

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()

wifi.getmode(mode)

Description

get wifi operation mode.

Syntax

wifi.getmode()

Parameters

nil

Returns

wifi operation mode

Example

    print(wifi.getmode())

See also

- wifi.setmode()

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()

wifi.stopsmart()

Description

stop the configuring process.

Syntax

wifi.stopsmart()

Parameters

nil

Returns

nil

Example

    wifi.stopsmart()

See also

- wifi.startsmart()

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()

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.sta.getip()

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()

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

- wifi.ap.getip()

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()

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.delay()

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.now()

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

- tmr.now()

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()

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.mode()

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.start()

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()

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()

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.start()

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()

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.setclock()

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()

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

- pwm.setduty()

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()

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.createServer()

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

- net.createServer()

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.createServer()

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

- net.socket:on()

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

- net.socket:on()

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

- net.createServer()

close()

Description

close socket.

Syntax

close()

Parameters

nil

Returns

nil

See also

- net.createServer()

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

- net.createServer()

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.read()

i2c.start()

Description

start i2c transporting.

Syntax

i2c.start(id)

Parameters

id = 0

Returns

nil

See also

- i2c.read()

i2c.stop()

Description

stop i2c transporting.

Syntax

i2c.stop(id)

Parameters

id = 0

Returns

nil

See also

- i2c.read()

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.read()

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()

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))

See also

- i2c.write()