A comprehensive Lua C library wrapper for libgpiod, providing complete GPIO control functionality for Linux systems.

This library provides a complete Lua binding for the libgpiod library, allowing you to control GPIO pins on Linux systems from Lua scripts. It supports all major gpiod features including input/output operations, event handling, bulk operations, and chip enumeration.

• English
• 中文

• Complete GPIO Control: Input/output operations, value reading/writing
• Event Handling: Rising edge, falling edge, and both edge event detection
• Bulk Operations: Efficient multi-line GPIO operations
• Chip Management: Enumerate and manage multiple GPIO chips
• Line Properties: Access line names, consumers, directions, bias settings
• Precise Timing: Built-in precise sleep function for timing-critical applications

• Linux system with GPIO support
• libgpiod library installed
• Lua 5.4 (or compatible version)
• GCC compiler

On Ubuntu/Debian:

sudo apt-get install libgpiod-dev lua5.4-dev build-essential

On Fedora/RHEL:

sudo dnf install libgpiod-devel lua-devel gcc

make

sudo make install

local gpiod = require("gpiod")

-- Open GPIO chip
local chip = gpiod.chip_open("gpiochip0")

-- Get a GPIO line
local line = chip:get_line(18)

-- Configure as output
line:request_output("my_app", 0)

-- Set high
line:set_value(1)

-- Clean up
line:release()
chip:close()

local gpiod = require("gpiod")

local chip = gpiod.chip_open("gpiochip0")
local line = chip:get_line(24)

-- Request rising edge events
line:request_rising_edge_events("button_monitor")

print("Waiting for button press...")
if line:event_wait(5.0) then  -- 5 second timeout
    local event = line:event_read()
    print("Button pressed at:", event:timestamp())
    print("Event type:", event:event_type())
end

line:release()
chip:close()

local gpiod = require("gpiod")

local chip = gpiod.chip_open("gpiochip0")
local lines = chip:get_lines({18, 19, 20, 21})

-- Configure all as outputs with initial values
lines:request_output("led_controller", {0, 1, 0, 1})

-- Set all values at once
lines:set_values({1, 1, 1, 1})

-- Read all values
local values = lines:get_values()
for i, value in ipairs(values) do
    print("Line " .. (i-1) .. ": " .. value)
end

lines:release()
chip:close()

• gpiod.chip_open(name_or_number) - Open GPIO chip by name or number
• gpiod.chip_iter() - Create chip iterator
• gpiod.sleep(seconds) - Precise sleep function
• gpiod.version() - Get libgpiod version

• chip:get_line(offset) - Get single GPIO line
• chip:get_lines(offsets) - Get multiple GPIO lines
• chip:find_line(name) - Find line by name
• chip:get_all_lines() - Get all available lines
• chip:name() - Get chip name
• chip:label() - Get chip label
• chip:num_lines() - Get number of lines
• chip:close() - Close chip

• line:request_input(consumer, [flags]) - Configure as input
• line:request_output(consumer, default_val, [flags]) - Configure as output
• line:release() - Release line

• line:get_value() - Read current value
• line:set_value(value) - Set output value

• line:request_rising_edge_events(consumer) - Monitor rising edges
• line:request_falling_edge_events(consumer) - Monitor falling edges
• line:request_both_edges_events(consumer) - Monitor both edges
• line:event_wait(timeout) - Wait for event
• line:event_read() - Read event
• line:event_get_fd() - Get event file descriptor

• line:offset() - Get line offset
• line:name() - Get line name
• line:consumer() - Get current consumer
• line:direction() - Get direction ("input"/"output")
• line:active_state() - Get active state ("high"/"low")
• line:bias() - Get bias setting
• line:is_used() - Check if line is in use
• line:is_open_drain() - Check open drain configuration
• line:is_open_source() - Check open source configuration
• line:update() - Update line information

• bulk:num_lines() - Get number of lines
• bulk:get_line(index) - Get line by index
• bulk:request_input(consumer, [flags]) - Configure all as inputs
• bulk:request_output(consumer, values, [flags]) - Configure all as outputs
• bulk:get_values() - Read all values
• bulk:set_values(values) - Set all values
• bulk:release() - Release all lines

• event:event_type() - Get event type ("rising_edge"/"falling_edge")
• event:timestamp() - Get event timestamp

• gpiod.OPEN_DRAIN - Open drain output
• gpiod.OPEN_SOURCE - Open source output
• gpiod.ACTIVE_LOW - Active low logic
• gpiod.BIAS_DISABLE - Disable bias
• gpiod.BIAS_PULL_DOWN - Pull-down bias
• gpiod.BIAS_PULL_UP - Pull-up bias

Run the example:

lua gpiod_example.lua

Test module loading:

make test

Build and test using Docker (recommended for CI/CD):

# Build the Docker image
docker build -t lua-gpiod-test .

# Run tests in container
docker run --rm lua-gpiod-test

# Interactive shell for manual testing
docker run --rm -it lua-gpiod-test /bin/bash

The Docker environment includes:

• Debian bookworm-slim base image
• All required dependencies (libgpiod, Lua 5.4, build tools)
• Automatic build and basic functionality tests
• Health check for module loading verification

This project is licensed under the MIT License - see the LICENSE file for details.

This project is hosted at: https://github.com/HsOjo/lua-gpiod

Contributions are welcome! Please feel free to submit issues and pull requests at the GitHub repository.

If you get permission errors, you may need to add your user to the gpio group:

sudo usermod -a -G gpio $USER

List available GPIO chips:

gpiodetect

Make sure libgpiod is installed and the shared library is in the correct path.