Module gpio

The gpio library enables to interact with GPIOs.

It provides read, write, and register methods, as well as GPIO configuration and listing features.

This module is mainly based on Linux kernel userspace mapping to act on GPIOs.
See Kernel GPIO doc, "Sysfs Interface for Userspace" chapter.
Please check you device system comes with this capability before using this module. Also, pay attention to access rights to /sys/class/gpio files, and check that the process running this module has correct user rights to access those files.

Type gpio

gpio.availablelist()

Lists available GPIO on the system.
gpio.configure(id, config)

Configures the GPIO parameters.
gpio.enabledlist()

Lists enabled GPIOs.
gpio.getconfig(id)

Retrieves GPIO configuration.
gpio.read(id)

Reads a GPIO value.
gpio.register(id, userhook)

Registers a GPIO for monitoring it for changes.
gpio.write(id, value)

Writes a GPIO value.

Type gpio

Field(s)

gpio.availablelist()

Lists available GPIO on the system.

The list contains the GPIOs ids that the system claims to be able to manage. The list content is not modified by calling other API. In particular, the list contains GPIOs that haven't been configured yet (using gpio.configure API).

Beware, this doesn't mean that every GPIO in the list should be used by a user application, some can be already used by hardware drivers or other applications. Please check the device and the system documentation to get more precise info.

Return values

  1. available GPIOs list when successful

  2. nil followed by an error message otherwise

Usage:

local gpio = require"gpio"
local res = gpio.availablelist()
--On a Raspberry-Pi, res is likely to be:
-- res = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17,
18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36,
37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53 }
gpio.configure(id, config)

Configures the GPIO parameters.

The parameters that can be set are:

  • direction: the direction of the GPIO; input or output
  • edge: this setting describes when embedded application will be notified for changes: never, on rising edge (from inactive to active) or falling edge (from active to inactive).
  • activelow: This setting describes how to interpret the GPIO value: Is high voltage value (e.g.: 3.3V or 5V) to be interpreted as "active"/"on" (the default behavior i.e. activelow set to "0") or as "inactive"/"off" (activelow set to "1").

Before calling this function:

  • Required configuration:
    If no previous configuration (neither automatic nor explicit) has been done for this GPIO, then the first explicit call to gpio.configure must contain the direction parameter.

Parameters

  • id : GPIO id as a number

  • config : a map with fields:

    • edge: accepted value: "none", "rising", "falling", "both". Beware: changing edge value on a GPIO monitored for change (using gpio.register API). will alter the way notifications are done for this GPIO.
    • direction: accepted values (string): "in", "out".
    • activelow: accepted values (string): "0", "1".

Return values

  1. "ok" when successful

  2. nil followed by an error message otherwise

Usage:


local gpio = require"gpio"
local val = gpio.configure(42, {direction="in", edge="both", activelow="0"})
gpio.enabledlist()

Lists enabled GPIOs.

The list contains the GPIOs ids that have already been activated/configured. Using this library, once a GPIO have been activated/configured, it will remain "enabled" until system reboot.

Beware, this doesn't mean that every GPIO in the list should be used by a user application, some can be already used by hardware drivers or other applications. Please check the device and the system documentation to get more precise info.

Return values

  1. available GPIOs list when successful

  2. nil followed by an error message otherwise

Usage:

local gpio = require"gpio"
gpio.read(4)
local res = gpio.enabledlist()
-- If no other application have been using GPIO since last system reboot
-- then the is likely to be:
-- res = { 4 }
gpio.getconfig(id)

Retrieves GPIO configuration.

See gpio.configure for available settings.

Parameter

  • id : a number, the gpio id.

Return values

  1. GPIO configuration as a table

  2. nil followed by an error message otherwise

Usage:

local gpio = require"gpio"
local res = gpio.getconfig(4)
-- res = { direction="in", edge="none", activelow="0" }
gpio.read(id)

Reads a GPIO value.

GPIO Configuration:

  • Default configuration:
    If the gpio has not been configured (using gpio.configure API) prior to call this function, then the gpio will be automatically configured using:
    {direction="in", edge="none", activelow="0"}.

  • Required configuration:
    If the gpio have been previously set as output, its the configuration will not be changed, it is very likely to be readable without any error.

The value returned is impacted by the configuration of the GPIO:
* activelow parameter: this parameter will modify the way to interpret edge values "rising", "falling".

Parameter

  • id : a number, the gpio id.

Return values

  1. GPIO value as a "string" when successful

  2. nil followed by an error message otherwise

Usage:

local gpio = require"gpio"
local val = gpio.read(42)
gpio.register(id, userhook)

Registers a GPIO for monitoring it for changes.

Using nil for userhook parameter, this function also enables to cancel previous registration.

GPIO Configuration:

  • Default configuration:
    If the gpio has not been configured (using gpio.configure API) prior to call this function, then the gpio will be automatically configured using:
    {direction="in", edge="both", activelow="0"}.

  • Required configuration:

If the gpio have been previously set as input, its the configuration will not be changed.

The behavior of notification (i.e. when the user callback will be called) is impacted by the configuration of the GPIO: * edge parameter: "rising", "falling" and "both" will enable the notification and the callback will be called according to the behavior of edge value. Using "none" will disable any notification.

  • activelow parameter: this parameter will modify the way to interpret edge values ("rising", "falling").

Parameters

  • id : a number, the gpio id.

  • userhook : a function that will be called when a notification is available for the GPIO.

    This param can be set to nil to cancel previous registration. userhook signature: hook(gpioid, value)

Return values

  1. "ok" when successful

  2. nil followed by an error message otherwise

Usage:

local function myhook(id, value)
print(string.format("GPIO %d has changed! New value = %s", id, value))
end
gpio.register(42, myhook)
-- this may produce this print:
"GPIO 42 has changed! New value = '1'"
gpio.write(id, value)

Writes a GPIO value.

GPIO Configuration:

  • Default configuration:
    If the gpio has not been configured (using gpio.configure API) prior to call this function, then the gpio will be automatically configured using:
    {direction="out", edge="none", activelow="0"}.

  • Required configuration:
    If the GPIO have been previously set as input, its configuration will not be changed and the write call will return an error.

Parameters

  • id : a number, the GPIO id

  • value : string or number :"0" or 0,"1" or 1, the value to set the GPIO.

Return values

  1. "ok" on success

  2. nil, error string never returns (throws a Lua error instead)

Usage:

local gpio = require"gpio"
gpio.write(42, 1)