nodemcu-firmware/docs/en/modules/gpio.md

GPIO Module

Since	Origin / Contributor	Maintainer	Source
2014-12-22	Zeroday	Zeroday	gpio.c

This module provides access to the GPIO (General Purpose Input/Output) subsystem.

All access is based on the I/O index number on the NodeMCU dev kits, not the internal GPIO pin. For example, the D0 pin on the dev kit is mapped to the internal GPIO pin 16.

If not using a NodeMCU dev kit, please refer to the below GPIO pin maps for the index↔gpio mapping.

IO index	ESP8266 pin	IO index	ESP8266 pin
0 [*]	GPIO16	7	GPIO13
1	GPIO5	8	GPIO15
2	GPIO4	9	GPIO3
3	GPIO0	10	GPIO1
4	GPIO2	11	GPIO9
5	GPIO14	12	GPIO10
6	GPIO12

** [*] D0(GPIO16) can only be used as gpio read/write. No support for open-drain/interrupt/pwm/i2c/ow. **

gpio.mode()

Initialize pin to GPIO mode, set the pin in/out direction, and optional internal weak pull-up.

Syntax

gpio.mode(pin, mode [, pullup])

Parameters

• pin pin to configure, IO index
• mode one of gpio.OUTPUT, gpio.OPENDRAIN, gpio.INPUT, or gpio.INT (interrupt mode)
• pullup gpio.PULLUP enables the weak pull-up resistor; default is gpio.FLOAT

Returns

nil

Example

gpio.mode(0, gpio.OUTPUT)

See also

• gpio.read()
• gpio.write()

gpio.read()

Read digital GPIO pin value.

Syntax

gpio.read(pin)

Parameters

pin pin to read, IO index

Returns

a number, 0 = low, 1 = high

Example

-- read value of gpio 0.
gpio.read(0)

See also

gpio.mode()

gpio.serout()

Serialize output based on a sequence of delay-times. After each delay, the pin is toggled.

Syntax

gpio.serout(pin, start_level, delay_times [, repeat_num])

Parameters

• pin pin to use, IO index
• start_level level to start on, either gpio.HIGH or gpio.LOW
• delay_times an array of delay times between each toggle of the gpio pin.
• repeat_num an optional number of times to run through the sequence.

Note that this function blocks, and as such any use of it must adhere to the SDK guidelines of time spent blocking the stack (10-100ms). Failure to do so may lead to WiFi issues or outright crashes/reboots.

Returns

nil

Example

gpio.mode(1,gpio.OUTPUT,gpio.PULLUP)
gpio.serout(1,1,{30,30,60,60,30,30})  -- serial one byte, b10110010
gpio.serout(1,1,{30,70},8)  -- serial 30% pwm 10k, lasts 8 cycles
gpio.serout(1,1,{3,7},8)  -- serial 30% pwm 100k, lasts 8 cycles
gpio.serout(1,1,{0,0},8)  -- serial 50% pwm as fast as possible, lasts 8 cycles
gpio.serout(1,0,{20,10,10,20,10,10,10,100}) -- sim uart one byte 0x5A at about 100kbps
gpio.serout(1,1,{8,18},8) -- serial 30% pwm 38k, lasts 8 cycles

gpio.trig()

Establish or clear a callback function to run on interrupt for a pin.

This function is not available if GPIO_INTERRUPT_ENABLE was undefined at compile time.

Syntax

gpio.trig(pin, [type [, callback_function]])

Parameters

• pin 1-12, pin to trigger on, IO index. Note that pin 0 does not support interrupts.
• type "up", "down", "both", "low", "high", which represent rising edge, falling edge, both edges, low level, and high level trigger modes respectivey. If the type is "none" or omitted then the callback function is removed and the interrupt is disabled.
• callback_function(level) callback function when trigger occurs. The level of the specified pin at the interrupt passed as the parameter to the callback. The previous callback function will be used if the function is omitted.

Returns

nil

Example

do
  -- use pin 1 as the input pulse width counter
  local pin, pulse1, du, now, trig = 1, 0, 0, tmr.now, gpio.trig
  gpio.mode(pin,gpio.INT)
  local function pin1cb(level)
    local pulse2 = now()
    print( level, pulse2 - pulse1 )
    pulse1 = pulse2
    trig(pin, level == gpio.HIGH  and "down" or "up")
  end
  trig(pin, "down", pin1cb)
end

See also

gpio.mode()

gpio.write()

Set digital GPIO pin value.

Syntax

gpio.write(pin, level)

Parameters

• pin pin to write, 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()