Module gpio
GPIO driver module.
Description
This module provides functions for interacting with micro-controller GPIO (General Purpose Input and Output) pins.
Note: -type pin() used in this driver refers to a pin number on Espressif
chips, or a tuple {GPIO_GROUP, PIN} for stm32 chips.
Data Types
direction()
direction() = input | output | output_od
gpio()
gpio() = pid()
high_level()
high_level() = high | 1
level()
level() = low_level() | high_level()
low_level()
low_level() = low | 0
pin()
pin() = non_neg_integer() | {atom(), non_neg_integer()}
pull()
pull() = up | down | up_down | floating
trigger()
trigger() = none | rising | falling | both | low | high
Function Index
| attach_interrupt/2 | Convenience function for gpio:set_int/3 |
| close/1 | Stop the GPIO interrupt port. |
| deep_sleep_hold_dis/0 | Disable all gpio pad functions during Deep-sleep. |
| deep_sleep_hold_en/0 | Enable all hold functions to continue in deep sleep. |
| deinit/1 | Reset a pin back to the NULL function. |
| detach_interrupt/1 | Convenience function for gpio:remove_int/2 |
| digital_read/1 | Read the digital state of a GPIO pin. |
| digital_write/2 | Set GPIO digital output level. |
| hold_dis/1 | Release a pin from a hold state. |
| hold_en/1 | Hold the state of a pin. |
| init/1 | Initialize a pin to be used as GPIO. |
| open/0 | Start the GPIO driver port. |
| read/2 | Read the digital state of a GPIO pin. |
| remove_int/2 | Remove a GPIO interrupt. |
| set_direction/3 | Set the operational mode of a pin. |
| set_int/3 | Set a GPIO interrupt. |
| set_level/3 | Set GPIO digital output level. |
| set_pin_mode/2 | Set the operational mode of a pin. |
| set_pin_pull/2 | Set the internal resistor of a pin. |
| start/0 | Start the GPIO driver port. |
| stop/0 | Stop the GPIO interrupt port. |
Function Details
attach_interrupt/2
attach_interrupt(Pin::pin(), Trigger::trigger()) -> ok | error
Pin: number of the pin to set the interrupt onTrigger: is the state that will trigger an interrupt
returns: ok | error
Convenience function for gpio:set_int/3
This is a convenience function for gpio:set_int/3 that allows an
interrupt to be set using only the pin number and trigger as
arguments.
This function should only be used when only one gpio trigger is used in an application. If multiple pins are being configured with interrupt triggers gpio:set_int/3 should be used otherwise there is a race condition when start() is called internally by this function.
close/1
close(GPIO::gpio()) -> ok | error
GPIO: pid that was returned from gpio:start/0
returns: ok atom
Stop the GPIO interrupt port
This function disables any interrupts that are set, stops the listening port, and frees all of its resources.
deep_sleep_hold_dis/0
deep_sleep_hold_dis() -> ok
returns: ok
Disable all gpio pad functions during Deep-sleep.
deep_sleep_hold_en/0
deep_sleep_hold_en() -> ok
returns: ok
Enable all hold functions to continue in deep sleep.
The gpio pad hold function works in both input and output modes, but must be output-capable gpios.
When the chip is in Deep-sleep mode, all digital gpio will hold the state before sleep, and when the chip is woken up, the status of digital gpio will not be held. Note that the pad hold feature only works when the chip is in Deep-sleep mode, when not in sleep mode, the digital gpio state can be changed even you have called this function.
Power down or call gpio_hold_dis will disable this function,
otherwise, the digital gpio hold feature works as long as the chip
enters Deep-sleep.
deinit/1
deinit(Pin::pin()) -> ok
Pin: number to deinitialize
returns: ok
Reset a pin back to the NULL function. Currently only implemented for RP2040 (Pico).
detach_interrupt/1
detach_interrupt(Pin::pin()) -> ok | error
Pin: number of the pin to remove the interrupt
returns: ok | error
Convenience function for gpio:remove_int/2
This is a convenience function for gpio:remove_int/2 that allows an
interrupt to be removed using only the pin number as an argument.
Unlike gpio:attach_interrupt/2 this function can be safely used
regardless of the number of interrupt pins used in the application.
digital_read/1
digital_read(Pin::pin()) -> high | low
Pin: number of the pin to read
returns: high | low
Read the digital state of a GPIO pin
Read if an input pin state is high or low.
Warning: if a is not previously configured as an input using
gpio:set_pin_mode/2 it will always read as low.
digital_write/2
digital_write(Pin::pin(), Level::level()) -> ok | error
Pin: number of the pin to write
returns: ok | error
Set GPIO digital output level
Set a pin to high (1) or low (0).
hold_dis/1
hold_dis(Pin::pin()) -> ok | error
Pin: number of the pin to be released
returns: ok | error
Release a pin from a hold state.
When the chip is woken up from Deep-sleep, the gpio will be set to
the default mode, so, the gpio will output the default level if
this function is called. If you don’t want the level changes, the
gpio should be configured to a known state before this function is
called. e.g. If you hold gpio18 high during Deep-sleep, after the
chip is woken up and gpio:hold_dis is called, gpio18 will output
low level(because gpio18 is input mode by default). If you don’t
want this behavior, you should configure gpio18 as output mode and
set it to hight level before calling gpio:hold_dis.
hold_en/1
hold_en(Pin::pin()) -> ok | error
Pin: number of the pin to be held
returns: ok | error
Hold the state of a pin
The gpio pad hold function works in both input and output modes, but must be output-capable gpios.
If pad hold enabled: In output mode: the output level of the pad will be force locked and can not be changed. In input mode: the input value read will not change, regardless the changes of input signal.
The state of digital gpio cannot be held during Deep-sleep, and it
will resume the hold function when the chip wakes up from
Deep-sleep. If the digital gpio also needs to be held during
Deep-sleep gpio:deep_sleep_hold_en should also be called.
init/1
init(Pin::pin()) -> ok
Pin: number to initialize
returns: ok
Initialize a pin to be used as GPIO. Currently only implemented (and required) for RP2040 (Pico).
open/0
open() -> gpio()
returns: Pid
Start the GPIO driver port
The GPIO port driver will be stared and registered as gpio. If the
port has already been started through the gpio:open/0 or
gpio:start/0 the command will fail. The use of gpio:open/0 or
gpio:start/0 is required before using any functions that require a
GPIO pid as a parameter.
read/2
read(GPIO::gpio(), Pin::pin()) -> high | low
GPIO: pid that was returned from gpio:start/0Pin: number of the pin to read
returns: high | low
Read the digital state of a GPIO pin
Read if an input pin state is high or low.
Warning: if a is not previously configured as an input using
gpio:set_direction/3 it will always read as low.
remove_int/2
remove_int(GPIO::gpio(), Pin::pin()) -> ok | error
GPIO: pid that was returned from gpio:start/0Pin: number of the pin to remove the interrupt
returns: ok | error
Remove a GPIO interrupt
Removes an interrupt from the specified pin.
set_direction/3
set_direction(GPIO::gpio(), Pin::pin(), Direction::direction()) -> ok | error
GPIO: pid that was returned from gpio:start/0Pin: number of the pin to configureDirection: is input, output, or output_od
returns: ok | error
Set the operational mode of a pin
Pins can be used for input, output, or output with open drain.
set_int/3
set_int(GPIO::gpio(), Pin::pin(), Trigger::trigger()) -> ok | error
GPIO: pid that was returned from gpio:start/0Pin: number of the pin to set the interrupt onTrigger: is the state that will trigger an interrupt
returns: ok | error
Set a GPIO interrupt
Available triggers are none (which is the same as disabling an
interrupt), rising, falling, both (rising or falling), low, and
high. When the interrupt is triggered it will send a tuple:
{gpio_interrupt, Pin}
to the process that set the interrupt. Pin will be the number
of the pin that triggered the interrupt.
set_level/3
set_level(GPIO::gpio(), Pin::pin(), Level::level()) -> ok | error
GPIO: pid that was returned from gpio:start/0Pin: number of the pin to write
returns: ok | error
Set GPIO digital output level
Set a pin to high (1) or low (0).
set_pin_mode/2
set_pin_mode(Pin::pin(), Direction::direction()) -> ok | error
Pin: number to set operational modeDirection: is input, output, or output_od
returns: ok | error
Set the operational mode of a pin
Pins can be used for input, output, or output with open drain.
set_pin_pull/2
set_pin_pull(Pin::pin(), Pull::pull()) -> ok | error
Pin: number to set internal resistor directionPull: is the internal resistor state
returns: ok | error
Set the internal resistor of a pin
Pins can be internally pulled up, down, up_down (pulled in
both directions), or left floating.
start/0
start() -> gpio()
returns: Pid
Start the GPIO driver port
Returns the pid of the active GPIO port driver, otherwise the GPIO
port driver will be stared and registered as gpio. The use of
gpio:open/0 or gpio:start/0 is required before using any functions
that require a GPIO pid as a parameter.
stop/0
stop() -> ok | error
returns: ok atom
Stop the GPIO interrupt port
This function disables any interrupts that are set, stops the listening port, and frees all of its resources.