zig-gpio/README.md

2.7 KiB

zig-gpio

zig-gpio is a Zig library for controlling GPIO lines on Linux systems

This library can be used to access GPIO on devices such as Raspberry Pis or the Milk-V Duo (which is the board I created it for and tested it with).

This is my first Zig project, so I'm open to any suggestions!

There's a companion article available on my website: https://www.elara.ws/articles/milkv-duo.

Compatibility

zig-gpio uses the v2 character device API, which means it will work on any Linux system running kernel 5.10 or above. All you need to do is find out which gpiochip device controls which pin and what the offsets are, which you can do by either finding documentation online, or using the gpiodetect and gpioinfo tools from libgpiod.

I plan to eventually write a Zig replacement for gpiodetect and gpioinfo.

Try it yourself!

Here's an example of a really simple program that requests pin 22 from gpiochip2 and makes it blink at a 1 second interval. That pin offset is the LED of a Milk-V Duo board, so if you're using a different board, make sure to change it.

const std = @import("std");
const gpio = @import("gpio");

pub fn main() !void {
    var chip = try gpio.getChip("/dev/gpiochip2");
    defer chip.close();
    std.debug.print("Chip Name: {s}\n", .{chip.name});

    var line = try chip.requestLine(22, .{ .output = true });
    defer line.close();
    while (true) {
        try line.setHigh();
        std.time.sleep(std.time.ns_per_s);
        try line.setLow();
        std.time.sleep(std.time.ns_per_s);
    }
}

For more examples, see the _examples directory. You can build all the examples using the zig build examples command.

Using zig-gpio in your project

If you don't have a zig project already, you can create one by running zig init-exe in a new folder.

To add zig-gpio as a dependency, there are two steps:

  1. Add zig-gpio to your build.zig.zon file
  2. Add zig-gpio to your build.zig file

If you don't have a build.zig.zon file, create one. If you do, just add zig-gpio as a dependency. Here's what it should look like:

.{
    .name = "my_project",
    .version = "0.0.1",

    .dependencies = .{
        .gpio = .{
            .url = "https://gitea.elara.ws/Elara6331/zig-gpio/archive/v0.0.1.tar.gz",
            .hash = "1220e3af3194d1154217423d60124ae3a46537c2253dbfb8057e9b550526d2885df1",
        }
    }
}

Then, in your build.zig file, add the following before b.installArtifact(exe):

const gpio = b.dependency("gpio", .{
    .target = target,
    .optimize = optimize,
});
exe.addModule("gpio", gpio.module("gpio"));

And that's it! You should now be able to use zig-gpio via @import("gpio");