[PATCH RESEND libgpiod v2 17/18] README: document the DBus API
Bartosz Golaszewski
brgl at bgdev.pl
Fri Jun 28 18:58:36 UTC 2024
From: Bartosz Golaszewski <bartosz.golaszewski at linaro.org>
Add information on the DBus API as well as gpio-manager and gpiocli to
the README file.
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski at linaro.org>
---
README | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 64 insertions(+)
diff --git a/README b/README
index ef5d328..192943c 100644
--- a/README
+++ b/README
@@ -224,6 +224,70 @@ C library using make, they will be automatically configured to build against the
build results of the C library. Please refer to bindings/rust/libgpiod/README.md
for more information.
+DBUS
+----
+
+A commonly requested feature for the GPIO character device was state persistence
+after releasing the lines (as a kernel feature) or providing a central authority
+(in user-space) that would be in charge of keeping the lines requested and in a
+certain state (similarily to how the sysfs ABI works). DBus API has been
+provided to address this requirement. We define an interface covering the
+majority of the GPIO chardev's functionality and implement it from both the
+server and client sides in the form of the gpio-manager daemon and the gpiocli
+command-line utility for talking to the manager.
+
+DBus support can be built by passing --enable-dbus to configure. The daemon
+is bundled with a systemd unit file and an example configuration file for the
+io.gpiod1 interface that allows all users to access basic information about the
+GPIOs in the system but only root to request lines or change their values.
+
+With the manager running the user can run gpiocli to control GPIOs by asking
+gpio-manager to act on their behalf:
+
+ # Detect chips in the system.
+ $ gpiocli detect
+ gpiochip0 [INT34C6:00] (463 lines)
+
+ # Request a set of lines. Note that gpiocli exits immediately but the
+ # state of the lines is retained because it's the gpio-manager that
+ # requested them.
+ $ gpiocli request --output foo=active
+ request0
+
+ # Previous invocation printed out the name of the request by which the
+ # caller can refer to it later. All active requests can also be inspected
+ # at any time.
+ $ gpiocli requests
+ request0 (gpiochip1) Offsets: [5]
+
+ # We can print the information about the requested line using the
+ # information above.
+ $ gpiocli info --chip=gpiochip1 5
+ gpiochip1 5: "foo" [used,consumer="gpiocli request",managed="request0",output,push-pull]
+
+ # We can now change the value of the line.
+ $ gpiocli set foo=inactive
+
+ # And read it.
+ $ gpiocli get foo
+ "foo"=inactive
+
+ # We can even reconfigure it to input and enable edge-detection.
+ $ gpiocli reconfigure --input --both-edges request0
+
+ # And wait for edge events.
+ $ gpiocli monitor cos
+ 21763952894920 rising "foo"
+
+ # And finally release the request.
+ $ gpiocli release request0
+
+For more information please refer to the output of gpiocli --help as well as
+gpiocli <command> --help which prints detailed info on every available command.
+
+Of course - this being DBus - users can talk to gpio-manager using any DBus
+library available and are not limited to the provided client.
+
TESTING
-------
--
2.43.0
More information about the dbus
mailing list