Python bindings for libgpiod

Warnings

• breaking The `gpiod` library underwent a major breaking change with version 2.0.2. This version replaced an older, unofficial pure-Python implementation (versions 1.5.4 and prior) with official C-bindings to `libgpiod`. The APIs are not backwards compatible.
  Fix: Ensure your `pip install` command specifies `gpiod>=2.0.2` to get the official bindings. If migrating from older code, refactor imports and usage patterns according to the v2+ API (e.g., `gpiod.Chip` instead of `gpiod.chip`).
• gotcha Building `gpiod` from source (which is often required as binary wheels are not provided) necessitates the `python3-dev` package (or equivalent development headers for Python). Without it, installation will fail.
  Fix: Before `pip install gpiod`, ensure system dependencies are met: `sudo apt install python3-dev` (on Debian/Ubuntu) or equivalent for your distribution.
• gotcha The path to the GPIO character device (`/dev/gpiochipX`) varies between different hardware platforms. Specifically, Raspberry Pi 5 typically uses `/dev/gpiochip4` for external GPIOs, while older Raspberry Pi models (e.g., Pi 4, Pi 3, Pi Zero) commonly use `/dev/gpiochip0`.
  Fix: Always verify the correct GPIO chip path for your specific hardware using `gpioinfo` (a command-line tool from `libgpiod`) or by inspecting `/dev/gpiochip*` files. Update your code's `chip_path` accordingly.
• gotcha GPIO line objects (`gpiod.Chip` and `gpiod.LineRequest`) manage system resources (file descriptors). Failure to close these resources can lead to resource leaks and prevent other processes from accessing the GPIOs.
  Fix: Always use `gpiod.Chip` and `gpiod.LineRequest` objects within a `with` statement. This ensures that resources are properly acquired and released automatically, even if errors occur.
• gotcha Permissions issues are common when accessing `/dev/gpiochipX` devices, especially when running Python scripts as a regular user.
  Fix: Ensure the user running the script has appropriate permissions to access the GPIO character devices. This may involve adding the user to a specific group (e.g., `gpio` on some systems) or, as a temporary measure for testing, running the script with `sudo`.

Install

• pip install gpiod Standard installation
• sudo apt install python3-dev pip install gpiod Required for building from source (Debian/Ubuntu)
• LINK_SYSTEM_LIBGPIOD=1 pip install gpiod Optional: Link against system libgpiod

Imports

• gpiod

  import gpiod

• Chip
  wrong:

  import gpiod.chip

  correct:

  from gpiod import Chip

  As of v2.0.2, the main Chip class is accessed directly from the `gpiod` module or imported as `gpiod.Chip` (uppercase). Older, unofficial pure-Python bindings (v1.5.4 and prior) used `gpiod.chip` (lowercase).
• LineSettings

  from gpiod.line import LineSettings

• Direction

  from gpiod.line import Direction

• Value

  from gpiod.line import Value

Quickstart

This example demonstrates how to set a GPIO line to an output direction and toggle its state (blink). It uses the `with` statement for proper resource management and highlights the common chip path and line offset configuration. Remember to replace `GPIO_LINE_OFFSET` with an actual GPIO pin number on your device. For Raspberry Pi 5, the GPIO chip is typically `/dev/gpiochip4`, while for older models (Pi 4, 3, Zero), it's usually `/dev/gpiochip0`.

import time
import os
from gpiod import Chip
from gpiod.line import Direction, Value, LineSettings

# NOTE: For Raspberry Pi 5, use '/dev/gpiochip4'. For Pi 4 and older, use '/dev/gpiochip0'.
GPIO_CHIP_PATH = os.environ.get('GPIO_CHIP_PATH', '/dev/gpiochip0')
GPIO_LINE_OFFSET = int(os.environ.get('GPIO_LINE_OFFSET', '17')) # Example offset, replace with your actual GPIO pin number

def blink_gpio(chip_path: str, line_offset: int, num_blinks: int = 5, delay: float = 0.5):
    try:
        with Chip(chip_path) as chip:
            print(f"Accessing GPIO chip: {chip.name} [{chip.label}] ({chip.num_lines} lines)")

            # Request the line for output
            line_settings = LineSettings(direction=Direction.OUTPUT)
            # Use a dictionary for request_lines config
            config = {line_offset: line_settings}
            
            # Using request_lines to get a LineRequest object
            with chip.request_lines(consumer="quickstart_blinker", config=config) as request:
                print(f"Blinking GPIO line {line_offset}...")
                for i in range(num_blinks):
                    request.set_value(line_offset, Value.ACTIVE)
                    print(f"[{i+1}/{num_blinks}] Line {line_offset} HIGH")
                    time.sleep(delay)
                    request.set_value(line_offset, Value.INACTIVE)
                    print(f"[{i+1}/{num_blinks}] Line {line_offset} LOW")
                    time.sleep(delay)
                print("Blinking complete.")

    except FileNotFoundError:
        print(f"Error: GPIO chip '{chip_path}' not found. Ensure it exists and you have permissions.")
    except PermissionError:
        print(f"Error: Permission denied to access '{chip_path}'. Try running with 'sudo'.")
    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == '__main__':
    blink_gpio(GPIO_CHIP_PATH, GPIO_LINE_OFFSET)