rust-embedded/gpio-utils

Userspace Utilities for managing GPIOs in Linux

Linux GPIO Utils

GPIO Utils provides convenient access to GPIOs on a Linux system. The library builds on top of the sysfs interface to GPIOs exposed by the kernel and provides essential functionality required for most embedded systems.

Install

To install the latest released version of gpio utils, ensure that you have installed Rust and then run:

cargo install gpio-utils

Features

• Infrastructure for providing names for the GPIOs in one's system providing names that map to individual pins. These names (in addition to GPIO numbers) may be used with other commands.
• Ability to export/unexport GPIOs and expose symlinks using the GPIO "friendly" names simpler.
• Ability to set input/output state on each pin
• Ability to set active low state on each pin
• Ability to get/set gpio values by pin number or name (including temporary export if necessary)
• Ability to block awaiting pin state change (with timeout)
• Ability to set exported GPIO permissions

System Integration

GPIO Utils provides two main pieces that one may integrate into their final system:

1. The gpio command. This provides the core functionality for GPIO Utils and is useful in its own right.
2. The gpio init script/systemd service. This can be integrated into a target system and will ensure that configured GPIOs get exported on system startup (The GPIO command searches for /etc/gpio.toml and /etc/gpio.d/*.toml configs)

The GPIO Utils library is built on top of the Rust sysfs-gpio library which may be used independent of this project.

GPIO Configuration File

GPIO Utils uses the TOML. There is some flexibility in the configuration, but the following examples shows the basics of how you can configure your GPIOs.

#
# Example GPIO configuration (e.g. /etc/gpio.toml)
#
# The main configuration consists of zero or more pins, each of which may have
# the following keys:
#
# - `num`: Required.  The GPIO number.
# - `names`: Required.  One or more names for the GPIO
# - `direction`: Default: `"in"`.  Must be either "in" or "out"
# - `active_low`: Default: `false`.  If set to true, the polarity of the pin will
#    be reversed.
# - `export`: Default: `true`.  If true, this GPIO will be automatically
#    exported when `gpio export-all` is run (e.g. by an init script).
# - `user`: User that should own the exported GPIO
# - `group`: Group that should own the exported GPIO
# - `mode`: Mode for exported directory

[[pins]]
num = 73                 # required
names = ["reset_button"] # required (may have multiple)
direction = "in"         # default: in
active_low = false       # default: false (really means invert logic)
export = true            # default: true
user = "root"            # default: (OS Default - root)
group = "gpio"           # default: (OS Default - root)
mode = 0o664             # default: (OS Default - 0o644)

[[pins]]
num = 37
names = ["status_led", "A27", "green_led"]
direction = "out"

# ...

Implementation Notes

Unlike several other existing solutions to this problem, this project is implemented in Rust (a modern systems programming language operating at the same level as C but with a type system providing greater productivity and reliability) and seeks to operate with a minimum of overhead.

Minimum Supported Rust Version (MSRV)

This crate is guaranteed to compile on stable Rust 1.26.2 and up. It might compile with older versions but that may change in any new patch release.

Contributing

Contributions are very welcome. See CONTRIBUTING.md for additional information on how to report bugs, submit changes, test changes, get support, etc.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Code of Conduct

Contribution to this crate is organized under the terms of the Rust Code of Conduct, the maintainer of this crate, the Embedded Linux Team, promises to intervene to uphold that code of conduct.

gpio-utils's Issues

Add sysv init script

Add an example (ideally usable as-is) init script that will export pins on system start.

Error with nix crate

To do PR for Issue #17, I got this error when build

Compiling nix v0.5.0
error[E0591]: extern "C" fn(*mut std::boxed::Box<std::ops::FnMut() -> isize>) -> i32 {sched::clone::callback} is zero-sized and can't be transmuted to *const extern "C" fn(*const std::boxed::Box<std::ops::FnMut() -> isize>) -> i32
--> /home/pi/.cargo/registry/src/github.com-1ecc6299db9ec823/nix-0.5.0/src/sched.rs:192:20
|
192 | ffi::clone(mem::transmute(callback), ptr as *mut c_void, flags.bits(), &mut cb)
| ^^^^^^^^^^^^^^
|
note: cast with as to a pointer instead
--> /home/pi/.cargo/registry/src/github.com-1ecc6299db9ec823/nix-0.5.0/src/sched.rs:192:20
|
192 | ffi::clone(mem::transmute(callback), ptr as *mut c_void, flags.bits(), &mut cb)
| ^^^^^^^^^^^^^^

error: aborting due to previous error

error: Could not compile nix.
Build failed, waiting for other jobs to finish...
error: build failed

I use this version

pi@raspberrypi:~/SharePI/RUST/gpio-utils $ cargo --version
cargo 0.19.0-nightly (c995e9eb5 2017-03-17)
pi@raspberrypi:~/SharePI/RUST/gpio-utils $ rustc --version
rustc 1.17.0-nightly (e703b33e3 2017-03-23)

Contributing.md Link is Dead

Document should be added. Maybe based on https://github.com/nix-rust/nix/blob/master/CONTRIBUTING.md (although homu is not setup as there are issues with the web service currently).

pigpio and pigpio-sys crates created

Hi, sorry for abusing this channel, I'm in hurry and want to get this out ASAP and don't have time for searching a better channel. I've created pigpio and pigpio-sys crates (published on crates.io). Feel free to try it out and help.

I can add someone from WG as maintainer if you're interested.

How to use poll command with timeout & edge value?

I test gpio-utils on a Raspberry PI 3.
It's Ok for read/write command but I can't use the poll command.
I do this

gpio --config ./raspberrypi.toml poll GPIO07

I got this error

Error setting edge on pin: Io(Error { repr: Os { code: 5, message: "Input/output error" } })

And if I do

gpio --config ./raspberrypi.toml poll GPIO07 both

I got this

error: Found argument 'both' which wasn't expected, or isn't valid in this context

Add Systemd Service Configuration

Add example Systemd service file (ideally usable as-is) that will export pins on startup (and unexport on stop). Relates to #8.

Error No such file or directory

On a raspberry PI 3/debian,

$ gpio --config ./raspberrypi.toml status GPIO07
| Number | Exported | Direction | Active Low | Names | Value |
+------------+------------+------------+------------+------------+------------+
ERROR: Io(Error { repr: Os { code: 2, message: "No such file or directory" } })

raspberrypi.toml is in current directory.

What does this error mean?

Interaction in gpio.toml between `direction` and `active_low` undefined

Looking at line https://github.com/rust-embedded/gpio-utils/blob/master/src/export.rs#L129, the order of direction and active_low leave some ambiguity about what the actual output state of the pin will be after initial export. If a user specified the following:

active_low = true
direction = "low"

Would the desired output be electrically high or low? With the current code it would be electrically low.

Discussing with @posborne, it seems that the order should be reversed so that the state specified by direction matches the semantics of the kernel:

/**
 * gpiod_set_value_nocheck() - set a GPIO line value without checking
 * @desc: the descriptor to set the value on
 * @value: value to set
 *
 * This sets the value of a GPIO line backing a descriptor, applying
 * different semantic quirks like active low and open drain/source
 * handling.
 */
static void gpiod_set_value_nocheck(struct gpio_desc *desc, int value)
{
    if (test_bit(FLAG_ACTIVE_LOW, &desc->flags))
        value = !value;
    if (test_bit(FLAG_OPEN_DRAIN, &desc->flags))
        gpio_set_open_drain_value_commit(desc, value);
    else if (test_bit(FLAG_OPEN_SOURCE, &desc->flags))
        gpio_set_open_source_value_commit(desc, value);
    else
        gpiod_set_raw_value_commit(desc, value);
}

This will be a breaking change and needs to be clearly documented. In addition to being clearly documented going forward just in general.