gpio #

Linux GPIO from pure Dart, over the /dev/gpiochip* character device using the v2 userspace ABI.

No native library. No bundled binaries. No apt install step. Just dart:ffi and the libc that is already in your process.

Status: pre-release (0.1.0). The API is complete and tested; it has not yet been exercised on real hardware, so treat it as unproven on a live board until it has been.

Why another GPIO package #

Because the v2 ABI carries three things v1 does not, and every existing Dart option gives up at least one of them:

• Kernel-side debounce, so contact bounce is filtered below userspace instead of by a timer you wrote.
• Event sequence numbers, so when the kernel's buffer overflows and edges are dropped, you find out. Every other Dart package silently loses them.
• A selectable event clock, so timestamps mean something specific.

Edge events arrive as a Stream, timestamped by the kernel at the interrupt — so scheduling affects when you see an event, never what time it says. The raw timestampNs is what the event carries, because Dart's Duration is microsecond-resolution and would quietly drop the low three digits; timestamp is there as a convenience when that does not matter.

Requirements #

• Linux 5.10 or newer (when the v2 ABI landed). There is no v1 fallback, by design — you cannot silently end up on the deprecated ABI. An older kernel answers EINVAL to every v2 ioctl (not ENOTTY, which means "not a gpiochip"), and the error message says so.

• Access to /dev/gpiochip*. Root works; a udev rule is better:

  # /etc/udev/rules.d/60-gpio.rules
  SUBSYSTEM=="gpio", KERNEL=="gpiochip*", GROUP="gpio", MODE="0660"
  

  then add your user to the gpio group and re-login.

Usage #

import 'package:gpio/gpio.dart';

final chip = GpioChip.byLabel('pinctrl-rp1');

final request = chip.request(
  consumer: 'my-app',
  lines: [
    LineConfig.input(17,
      bias: Bias.pullUp,
      activeLow: true,
      edge: Edge.both,
      debounce: Duration(milliseconds: 5)),
    LineConfig.output(27, initialValue: false),
  ],
);

// One ioctl, one atomic sample across every held line.
print(request.getValues());          // {17: false, 27: false}
request.setValue(27, value: true);

request.events.listen((event) => switch (event) {
  LineEdgeEvent(:final edge, :final timestampNs) =>
    print('$edge at $timestampNs ns'),
  LineEventsDropped(:final count) =>
    print('the kernel dropped $count edges'),
});

await request.close();
await chip.close();

Runnable versions of both halves are in example/.

Knowing when someone else takes a line #

lineInfo() is a snapshot, stale the moment it returns. watchLineInfo reports each change as the kernel sees it — including changes made by other processes:

final chip = GpioChip.byLabel('pinctrl-rp1');

chip.watchLineInfo([17, 27]).listen((change) {
  switch (change.kind) {
    case LineChangeKind.requested:
      print('line ${change.offset} taken by "${change.info.consumer}"');
    case LineChangeKind.released:
      print('line ${change.offset} is free again');
    case LineChangeKind.reconfigured:
      print('line ${change.offset} reconfigured');
  }
});

Without this, a collision with another process shows up only as EBUSY at request time — by which point there is nothing to do but fail. A daemon holding a footswitch learns that someone ran gpioset against the same line; a service restarting learns the previous instance let go.

Watching costs nothing until something changes: the kernel pushes, so there is no polling. unwatchLineInfo(offset) stops one line, and closing the chip stops everything.

Note that lines this process requests report here too — the kernel does not distinguish your own claims from anyone else's.

Testing your own code #

FakeKernel models the character device in memory, so code that talks to GPIO is testable on a machine that has none:

import 'package:gpio/gpio_testing.dart';

final fake = FakeChip(name: 'gpiochip0', label: 'test', lineCount: 8);
final chip = GpioChip.byLabel('test', syscalls: FakeKernel([fake]));

fake.setLevel(3, value: true);       // drive a pin from "outside"
expect(request.getValue(3), isTrue);

It models ownership and EBUSY, masked atomic access, activeLow inversion, kernel debounce, and edge events with sequence numbers — including dropNextEvents, which reproduces a FIFO overflow so you can test that your code notices.

Finding your chip #

Look chips up by label, not by index:

final chip = GpioChip.byLabel('pinctrl-rp1');   // Raspberry Pi 5

Chip numbering is assigned by probe order, so it moves. On the Raspberry Pi 5 the RP1 southbridge sits on PCIe and enumerates late: older kernels expose the 40-pin header as gpiochip4, kernels after mid-2024 renumber it to gpiochip0. Code with a hardcoded index is a bug waiting for a kernel update.

Platform support #

Windows deserves a word, because "Windows has no GPIO" is wrong. Windows on ARM runs on a Raspberry Pi 3/4/5, and it is the same silicon — the pins are physically there. What Windows does not do is expose them as a character device: GPIO arrives through the GpioClx driver and rhproxy, surfaced to user mode as the WinRT Windows.Devices.Gpio API (the thing .NET's System.Device.Gpio wraps on that platform). So Windows is a second backend behind the same public types, not a port of this one — and the same is true of the BSDs, whose /dev/gpiocN speaks its own ioctls.

None of that is planned work. It is why the package is called gpio rather than linux_gpio, why ioctl and file descriptors stay out of the public API, and why the Linux-specific entry point is a single named constructor (GpioChip.byPath) rather than the shape of the whole library.

macOS is the one genuine "no": no Mac has GPIO pins, and macOS does not run on a Pi. Reaching pins from a Mac means a USB bridge (FT232H, MCP2221), which is a device driver rather than an OS backend.

Running the tests #

dart test                  # 108 tests, no hardware needed
dart test -t integration   # real ioctls against the kernel's gpio-sim

The default suite runs against an in-memory model of the character device, so it passes on any machine.

The integration suite is the one that talks to a real /dev/gpiochipN, via the kernel's own gpio-sim module — the same thing libgpiod's test suite uses. It needs root and a kernel with CONFIG_GPIO_SIM. On GitHub's hosted runners the driver ships in linux-modules-extra-$(uname -r), which the runner image does not install by default; CI installs it and the suite runs on every build. A stock Debian, Ubuntu or Raspberry Pi OS kernel has it already.

What is still unverified: every test, including the gpio-sim ones, runs against a simulated chip. This package has not yet driven a physical pin on real silicon — no measured press-to-event latency, no real debounce on a bouncy switch. Treat it as pre-release until that happens.

Licence #

MIT. The bindings are generated from the kernel's own <linux/gpio.h>, which carries the Linux-syscall-note exception precisely so userspace programs under any licence may use those definitions. libgpiod (LGPL) is deliberately not a source for any part of this package.