pympacds-gpio

GPIO server service for pympacds. Monitors GPIO line state and edge events and exposes reads, writes, and change notifications over D-Bus.

Features

• Reads (get_value, get_lines) and writes (set_value) of GPIO lines over D-Bus, with per-output-line default (reset) values (get_default_value / set_default_value).
• Edge-event watching (line_changed signal) driven by the kernel gpiod edge-event API, polled asynchronously with a short timeout so the event loop is never stalled.
• Kernel-side debounce via debounce_us (passed to libgpiod), and active_low inversion for watched lines. No software debounce.
• A configurable line-name mapping ([gpio.linemap]) so lines can be referenced by human-readable name or numeric offset on the D-Bus API.
• Runtime configuration: [gpio] keys are writable via the framework ConfigContract.
• Exports the framework HealthContract (always) and ConfigContract (opt-in via [dbus] contract_config = true) alongside the GPIO contract.

Why gpiod

The service uses the gpiod Python bindings (libgpiod v2 API) because it is the reference userspace interface to the kernel GPIO character-device subsystem: line requests, edge events, and debounce are all handled in the kernel. It is isolated in this service's own package, so the core pympacds framework keeps its zero-dependency property.

Installation

Using PIP

pip install pympacds-gpio

Using pip installs the Python package only — the D-Bus policy, systemd unit, and udev rule are not installed. You can still run the service directly with pympacds-gpio -c /etc/pympacds/gpio.ini, or register and enable it system-wide with the admin script. Since there is no packaged unit, pass the pip-installed executable via --program so the unit is generated:

sudo pympacds-admin setup                      # one-time: user, log dir, D-Bus policy
sudo pympacds-admin install gpio \
    --program "$(command -v pympacds-gpio)" \
    --config /etc/pympacds/gpio.ini --start

Under pip you must also grant access to /dev/gpiochip* yourself (see Device access below); the udev rule ships only with the Debian package.

Alternatively, install the Debian package (see below), which already ships the unit, policy, and udev rule.

Using PPA

Debian packages are provided through launchpad ppa (dargor0/mpacds):

sudo add-apt-repository ppa:dargor0/mpacds
sudo apt update
sudo apt install python3-pympacds-gpio

The package installs the service system-wide (executable, systemd unit, D-Bus policy, udev rule, and the gpio.ini.example config) and depends on python3-pympacds.

Repository has been tested on Ubuntu (plucky, resolute, stonking) and Debian (stable, testing, unstable).

Configuration

The service reads its parameters from the [gpio] INI section and the optional [gpio.linemap] section (see config/gpio.ini.example):

The [gpio.linemap] section maps human-readable names to offsets (btn = 0). Names must not begin with a digit.

Run with:

pympacds-gpio -c /etc/pympacds/gpio.ini

Device access (permissions)

The service does not require root. Access to /dev/gpiochip* is granted via a udev rule (shipped by the Debian package) that assigns the device to the gpio group with mode 0660; add the service user to the gpio group:

sudo usermod -aG gpio <service-user>

D-Bus API

Interface org.pympacds.GPIO at object path /org/pympacds/gpio:

A line argument is a decimal offset or a [gpio.linemap] name, resolved number-first-then-name. An unresolvable line produces a D-Bus error reply.

The framework HealthContract (at .../health) and ConfigContract ([dbus] contract_config = true) are also exported.