Introduction

General-purpose input/output (GPIO) is a pin on an IC (Integrated Circuit). It can be either an input pin or output pin, whose behavior can be controlled at the run time.

NodeMCU Development kit provides access to these GPIOs of ESP8266. The only thing to take care of is that NodeMCU Devkit pins are numbered differently than internal GPIO notations of ESP8266 as shown in the below figure and table. For example, the D0 pin on the NodeMCU Devkit is mapped to the internal GPIO pin 16 of ESP8266.

NodeMCU GPIO

The below table gives NodeMCU Dev Kit IO pins and ESP8266 internal GPIO pins mapping

The GPIO’s shown in the blue box (1, 3, 9, 10) are mostly not used for GPIO purpose on Dev Kit

ESP8266 is a System on Chip (SoC) design with components like the processor chip. The processor has around 16 GPIO lines, some of which are used internally to interface with other components of the SoC, like flash memory.

Since several lines are used internally within the ESP8266 SoC, we have about 11 GPIO pins remaining for GPIO purposes.

Now again 2 pins out of 11 are generally reserved for RX and TX in order to communicate with a host PC through which compiled object code is downloaded.

Hence finally, this leaves just 9 general-purpose I/O pins i.e. D0 to D8.

As shown in the above figure of NodeMCU Dev Kit. We can see RX, TX, SD2, SD3 pins are not mostly used as GPIOs since they are used for other internal processes. But we can try with SD3 (D12) pin which mostly likes to respond for GPIO/PWM/interrupt like functions.

Note that the D0/GPIO16 pin can be only used as GPIO read/write, no special functions are supported on it.

Now let’s see about functions required to initialize pin to GPIO mode, setting pin direction and its state (High/Low)

NodeMCU GPIO functions

gpio.mode()

This function is used to initialize pin to GPIO mode.

Syntax:

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

Parameters:

Pin: pin no. to configure.

Mode: one of gpio.OUTPUT, gpio.OPENDRAIN, gpio.INPUT, or gpio.INT (interrupt mode)

Pullup:gpio.PULLUP enables the weak pull-up resistor. By default it is gpio.FLOAT

Returns: null

Example

gpio.mode(0, gpio.OUTPUT)  -- Setting 0th pin as GPIO output pin

gpio.read()

This function is used to read the digital value of the GPIO pin.

Syntax:

gpio.read(pin)

Parameters:

            Pin: pin no. to read.

Example:

gpio.read(0)   -- Read digital value of D0 (GPIO16) pin.

gpio.write()

This function is used to Set digital GPIO pin value.

Syntax:

gpio.write(pin, level)

Parameters:

Pin: pin to write, IO index

Level:gpio.HIGH or gpio.LOW

Returns: null

Example:

gpio.mode(1, gpio.OUTPUT)–- set 1st pin as GPIO output pin
gpio.write(1, gpio.HIGH) –- set 1st GPIO output pin to High.

Example

Let’s write a Lua script for LED blinking on pin D4.

Here we are using the timer delay function to set a delay in between the LED ON and LED OFF state.

tmr.delay()

This function of the timer is used to provide a delay in microseconds.

Syntax:

tmr.delay(microseconds)

Parameters:

microseconds: It takes no microseconds as an input parameters.

Returns:null

Example:

tmr.delay(100) –- delay of 100 microseconds.

Lua Script for LED Blink

LEDpin = 4         -- Declare LED pin no.
delayuS = 500000   -- Set delay in microSecond. here 0.5 second

gpio.mode(LEDpin,gpio.OUTPUT)-- Set LED pin as GPIO output pin
while(1)           -- Define infinite while loop
do
gpio.write(LEDpin,gpio.HIGH)-- Set LED pin HIGH i.e. LED ON
tmr.delay(delayuS) -- timer Delay
gpio.write(LEDpin,gpio.LOW)-- Set LED pin LOW i.e. LED OFF
tmr.delay(delayuS) -- timer Delay
end

There is another option of timer alarm in which we can toggle LED by setting a repeating alarm of a specific time. Below is timer alarm function information and an example of an LED blink is given.

tmr.alarm()

This function combines tmr.register() (timer register) and tmr.start()(timer start) operations into a single function. To stop the timer when done using it, call tmr.unregister() (timer unregister) on it. For one-shot timers, this is not necessary unless they were stopped before they expired.

Syntax:

tmr.alarm([id/ref], interval_ms, mode, func())

Parameters:

id/ref: timer id (0-6) or object. NodeMCU provides 7 static timers, numbered 0-6.

interval_ms: timer interval in milliseconds. Maximum value is 6870947 (1:54:30.947).

mode (timer mode):

tmr.ALARM_SINGLE  - a one-shot alarm (and no need to call tmr.unregister())

tmr.ALARM_SEMI  - manually repeating alarm (call tmr.start() to restart)

tmr.ALARM_AUTO  - automatically repeating alarm.

func(timer): callback function.

Returns: true if the timer was started, false on error

Lua Script for LED Blink using timer alarm

LEDpin = 4
timer_id = 1
delay_ms = 500

gpio.mode(LEDpin,gpio.OUTPUT)    -- Make LED pin 4 (D4 on kit) as output
LEDvalue = gpio.LOW              -- Initialize variable LEDvalue with digital LOW
-- Set timer alarm calls LEDBlink() function after every 1 sec
tmr.alarm(timer_id,delay_ms,tmr.ALARM_AUTO,function() LEDBlink() end)

function LEDBlink()
    if LEDvalue == gpio.LOW then -- This part inverts the variable state
LEDvalue = gpio.HIGH
    else
LEDvalue = gpio.LOW
    end
gpio.write(LEDpin,LEDvalue)      --write to the LEDpin
end

Note

Some of the GPIO pins are used while booting, so Pulling this pin HIGH or LOW can prevent NODEMCU from booting

• GPIO0: It oscillates and stabilizes HIGH after ~100ms. Boot Failure if pulled LOW
• GPIO1: LOW for ~50ms, then HIGH, Boot Failure if Pulled LOW.
• GPIO2: It oscillates and stabilize HIGH after ~100ms, Boot Failure if Pulled LOW.
• GPIO3: LOW for ~50ms, then HIGH.
• GPIO9: Pin is HIGH at Boot.
• GPIO10: Pin is HIGH at Boot.
• GPIO15: LOW, Boot failure if Pulled HIGH
• GPIO16: HIGH during Boot and Falls to ~1Volt. 

Consider Pins HIGH/ LOW at boot, if you are connecting any peripheral device as output i.e. Relay, Optocouplers, transistors or any such drivers may create a problem.

Built-in LED on NODEMCU: GPIO2 i.e. D4 pin, even some board have LED on GPIO16. 

For detailed reference on GPIO behavior click here.