nodeMcu API Instruction

version 0.9.2 build 2014-11-20

change log:

2014-11-20

fix tmr.delay to support more than 2s delay, may cause bacon time out, lost connection to AP.

add tmr.wdclr to clear watchdog counter in chip, use in long time loop.

fix UDP part of net module.

add a timeout para to createServer(net.TCP, timeout).

2014-11-19

add adc module, use adc.read(0) to read adc value, no tests made.

add wifi.sta.getap() api to wifi.sta module, to get ap list.

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

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

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

node.chipid()

Description

return chip ID

Syntax

node.chipid()

Parameters

nil

Returns

number:chip ID

Example

    id = node.chipid();

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

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

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

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)

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

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

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

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

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

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

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

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

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

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

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)

wifi.getmode(mode)

Description

get wifi operation mode.

Syntax

wifi.getmode()

Parameters

nil

Returns

wifi operation mode

Example

    print(wifi.getmode())

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

wifi.stopsmart()

Description

stop the configuring process.

Syntax

wifi.stopsmart()

Parameters

nil

Returns

nil

Example

    wifi.stopsmart()

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

wifi.sta.connect()

Description

connect to AP in station mode.

Syntax

wifi.sta.connect()

Parameters

nil

Returns

nil

Example

    wifi.sta.connect()

wifi.sta.disconnect()

Description

disconnect from AP in station mode.

Syntax

wifi.sta.disconnect()

Parameters

nil

Returns

nil

Example

    wifi.sta.disconnect()

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

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

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

wifi.sta.getap()

Description

scan and get ap list as a lua table into callback function.

Syntax

wifi.sta.getap(function(table))

Parameters

function(table): a callback function to receive ap table when scan is done

this function receive a table, the key is the ssid, value is other info in format: authmode,rssi,bssid,channel

Returns

nil

Example

    -- print ap list
    function listap(t)
      for k,v in pairs(t) do
        print(k.." : "..v)
      end
    end
    wifi.sta.getap(listap)

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

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

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

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)

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

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 )

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

tmr.wdclr()

Description

clear system watchdog counter.

Syntax

tmr.wdclr()

Parameters

nil.

Returns

nil

Example

    for i=1,10000 do 
      print(i)
      tmr.wdclr()   -- should call tmr.wdclr() in a long loop to avoid hardware reset caused by watchdog.
    end

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)

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)

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)

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)

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)

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)

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)

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)

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)

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

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)

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.

net module

CONSTANT

net.TCP, net.UDP

net.createServer()

Description

create a server.

Syntax

net.createServer(type, timeout)

Parameters

type: net.TCP or net.UDP

timeout: for a TCP server, timeout is 1~28800 seconds, for a inactive client to disconnected.

Returns

net.server sub module

Example

    net.createServer(net.TCP, 30) -- 30s timeout

net.createConnection()

Description

create a client.

Syntax

net.createConnection(type, secure)

Parameters

type: net.TCP or net.UDP

secure: 1 or 0, 1 for ssl link, 0 for normal link

Returns

net.server sub module

Example

    net.createConnection(net.UDP, 0)

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, 30)    -- 30s time out for a inactive client
    -- 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)

close()

Description

close server.

Syntax

net.server.close()

Parameters

nil

Returns

nil

Example

    -- create a server
    sv=net.createServer(net.TCP, 30)
    -- close server
    sv:close()

net.socket module

connect()

Description

connect to remote.

Syntax

connect(port, ip)

Parameters

port: port number

ip: ip address in string

Returns

nil

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

on()

Description

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, 0)
    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")

close()

Description

close socket.

Syntax

close()

Parameters

nil

Returns

nil

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

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

i2c.start()

Description

start i2c transporting.

Syntax

i2c.start(id)

Parameters

id = 0

Returns

nil

i2c.stop()

Description

stop i2c transporting.

Syntax

i2c.stop(id)

Parameters

id = 0

Returns

nil

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

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

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

adc module

CONSTANT

none

adc.read()

Description

read adc value of id, esp8266 has only one 10bit adc, id=0, pin TOUT

Syntax

adc.read(id)

Parameters

id = 0

Returns

adc value

nodeMcu API Instruction

version 0.9.2 build 2014-11-20

change log:

Summary

Burn/Flash Firmware

Address

node module

node.restart()

Description

Syntax

Parameters

Returns

Example

See also

node.dsleep()

Description

Syntax

Parameters

Returns

Example

See also

node.chipid()

Description

Syntax

Parameters

Returns

Example

See also

node.heap()

Description

Syntax

Parameters

Returns

Example

See also

node.key()

Description

Syntax

Parameters

Returns

Example

See also

node.led()

Description

Syntax

Parameters

Returns

Example

See also

node.input()

Description

Syntax

Parameters

Returns

Example

See also

node.output()

Description

Syntax

Parameters

Returns

Example

See also

file module

file.remove()

Description

Syntax

Parameters

Returns

Example

See also

file.open()

Description

Syntax

Parameters

Returns

Example

See also

file.close()

Description