diff mbox series

README: update Tools section for v2 tools

Message ID 20221115034520.22456-1-warthog618@gmail.com
State New
Headers show
Series README: update Tools section for v2 tools | expand

Commit Message

Kent Gibson Nov. 15, 2022, 3:45 a.m. UTC
Update the Tools section to reflect the changes to the tools for v2.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
---

A first draft of changes for the README.
If you want to wait for a v5 of the tools series I can add it on to the
end of that.

Cheers,
Kent.

 README | 176 ++++++++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 132 insertions(+), 44 deletions(-)
diff mbox series

Patch

diff --git a/README b/README
index 814a0f1..e6edf8b 100644
--- a/README
+++ b/README
@@ -59,62 +59,150 @@  There are currently six command-line tools available:
 * gpiodetect - list all gpiochips present on the system, their names, labels
                and number of GPIO lines
 
-* gpioinfo   - list all lines of specified gpiochips, their names, consumers,
-               direction, active state and additional flags
+* gpioinfo   - list lines, their gpiochip, offset, name, and direction, and
+               if in use then the consumer name and any other configured
+               attributes, such as active state, bias, drive, edge detection
+               and debounce period
 
 * gpioget    - read values of specified GPIO lines
 
-* gpioset    - set values of specified GPIO lines, potentially keep the lines
-               exported and wait until timeout, user input or signal
+* gpioset    - set values of specified GPIO lines, holding the lines until the
+               process is killed or otherwise exits
 
-* gpiofind   - find the gpiochip name and line offset given the line name
-
-* gpiomon    - wait for events on GPIO lines, specify which events to watch,
-               how many events to process before exiting or if the events
+* gpiomon    - wait for edge events on GPIO lines, specify which edges to watch
+               for, how many events to process before exiting, or if the events
                should be reported to the console
 
+* gpionotify - wait for changed to the info for GPIO lines, specify which
+               changes to watch for, how many events to process before exiting,
+               or if the events should be reported to the console
+
 Examples:
 
-    # Read the value of a single GPIO line.
-    $ gpioget gpiochip1 23
-    0
+    (using a Raspberry Pi 4B)
+
+    # Detect the available gpiochips.
+    $ gpiodetect
+    gpiochip0 [pinctrl-bcm2711] (58 lines)
+    gpiochip1 [raspberrypi-exp-gpio] (8 lines)
+
+    # Read the info for all the lines on a gpiochip.
+    $ gpioinfo -c 1
+    gpiochip1 - 8 lines:
+     line   0: "BT_ON"          output
+     line   1: "WL_ON"          output
+     line   2: "PWR_LED_OFF"    output active-low consumer="led1"
+     line   3: "GLOBAL_RESET"   output
+     line   4: "VDD_SD_IO_SEL"  output consumer="vdd-sd-io"
+     line   5: "CAM_GPIO"       output consumer="cam1_regulator"
+     line   6: "SD_PWR_ON"      output consumer="sd_vcc_reg"
+     line   7: "SD_OC_N"        input
+
+    # Read the info for particular lines.
+    $ ./gpioinfo PWR_LED_OFF STATUS_LED_G_CLK GLOBAL_RESET
+    gpiochip0 42 "STATUS_LED_G_CLK" output consumer="led0"
+    gpiochip1 2 "PWR_LED_OFF"    output active-low consumer="led1"
+    gpiochip1 3 "GLOBAL_RESET"   output
+
+    # Read the value of a single GPIO line by name.
+    $ gpioget RXD1
+    "RXD1"=active
+
+    # Read the value of a single GPIO line by chip and offset.
+    $ gpioget -c 0 15
+    "15"=active
+
+    # Read the value of a single GPIO line as a numeric value.
+    $ gpioget --numeric RXD1
+    1
 
     # Read two values at the same time. Set the active state of the lines
-    # to low.
-    $ gpioget --active-low gpiochip1 23 24
-    1 1
-
-    # Set values of two lines, then daemonize and wait for a signal (SIGINT or
-    # SIGTERM) before releasing them.
-    $ gpioset --mode=signal --background gpiochip1 23=1 24=0
-
-    # Set the value of a single line, then exit immediately. This is useful
-    # for floating pins.
-    $ gpioset gpiochip1 23=1
-
-    # Find a GPIO line by name.
-    $ gpiofind "USR-LED-2"
-    gpiochip1 23
-
-    # Toggle a GPIO by name, then wait for the user to press ENTER.
-    $ gpioset --mode=wait `gpiofind "USR-LED-2"`=1
+    # to low and without quoted names.
+    $ gpioget --active-low --unquoted GPIO23 GPIO24
+    GPIO23=active GPIO24=active
+
+    # Set the value of a line and hold the line until killed.
+    $ gpioset GPIO23=1
+
+    # Set values of two lines, then daemonize and hold the lines.
+    $ gpioset --daemonize GPIO23=1 GPIO24=0
+
+    # Set the value of a single line, hold it for 20ms, then exit.
+    $ gpioset --hold-period 20ms -t0 GPIO23=1
+
+    # Blink an LED on GPIO22 at 1Hz
+    $ gpioset -t500ms GPIO22=1
+
+    # Blink an LED on GPIO22 at 1Hz with a 20% duty cycle
+    $ gpioset -t200ms,800ms GPIO22=1
+
+    # Set some lines interactively (requires --enable-gpioset-interative)
+    $ gpioset --interactive --unquoted GPIO23=inactive GPIO24=active
+    gpioset> get
+    GPIO23=inactive GPIO24=active
+    gpioset> toggle
+    gpioset> get
+    GPIO23=active GPIO24=inactive
+    gpioset> set GPIO24=1
+    gpioset> get
+    GPIO23=active GPIO24=active
+    gpioset> toggle
+    gpioset> get
+    GPIO23=inactive GPIO24=inactive
+    gpioset> toggle GPIO23
+    gpioset> get
+    GPIO23=active GPIO24=inactive
+    gpioset> exit
 
     # Wait for three rising edge events on a single GPIO line, then exit.
-    $ gpiomon --num-events=3 --rising-edge gpiochip2 3
-    event:  RISING EDGE offset: 3 timestamp: [    1151.814356387]
-    event:  RISING EDGE offset: 3 timestamp: [    1151.815449803]
-    event:  RISING EDGE offset: 3 timestamp: [    1152.091556803]
-
-    # Wait for a single falling edge event. Specify a custom output format.
-    $ gpiomon --format="%e %o %s %n" --falling-edge gpiochip1 4
-    0 4 1156 615459801
-
-    # Pause execution until a single event of any type occurs. Don't print
-    # anything. Find the line by name.
-    $ gpiomon --num-events=1 --silent `gpiofind "USR-IN"`
-
-    # Monitor multiple lines, exit after the first event.
-    $ gpiomon --silent --num-events=1 gpiochip0 2 3 5
+    $ gpiomon --num-events=3 --edges=rising GPIO22
+    10002.907638045	rising	"GPIO22"
+    10037.132562259	rising	"GPIO22"
+    10047.179790748	rising	"GPIO22"
+
+    # Wait for three edge events on a single GPIO line, with time in local time
+    # and with unquoted line name, then exit.
+    $ gpiomon --num-events=3 --edges=both --localtime --unquoted GPIO22
+    2022-11-15T10:36:59.109615508	rising	GPIO22
+    2022-11-15T10:36:59.129681898	falling	GPIO22
+    2022-11-15T10:36:59.698971886	rising	GPIO22
+
+    # Wait for falling edge events with a custom output format.
+    $ gpiomon --format="%e %c %o %l %S" --edges=falling -c gpiochip0 22
+    2 gpiochip0 22 GPIO22 10946.693481859
+    2 gpiochip0 22 GPIO22 10947.025347604
+    2 gpiochip0 22 GPIO22 10947.283716669
+    2 gpiochip0 22 GPIO22 10947.570109430
+    ...
+
+    # Block until an edge event occurs. Don't print anything.
+    $ gpiomon --num-events=1 --quiet GPIO22
+
+    # Monitor multiple lines, exit after the first edge event.
+    $ gpiomon --quiet --num-events=1 GPIO5 GPIO6 GPIO12 GPIO17
+
+    # Monitor a line for changes to info.
+    $ gpionotify GPIO23
+    11571.816473718	requested	"GPIO23"
+    11571.816535124	released	"GPIO23"
+    11572.722894029	requested	"GPIO23"
+    11572.722932843	released	"GPIO23"
+    11573.222998598	requested	"GPIO23"
+    ...
+
+    # Monitor a line for requests, reporting UTC time and unquoted line name.
+     $ gpionotify --utc --unquoted GPIO23
+    2022-11-15T03:05:23.807090687Z	requested	GPIO23
+    2022-11-15T03:05:23.807151390Z	released	GPIO23
+    2022-11-15T03:05:24.784984280Z	requested	GPIO23
+    2022-11-15T03:05:24.785023873Z	released	GPIO23
+    ...
+
+    # Monitor multiple lines, exit after the first is requested.
+    $ gpionotify --quiet --num-events=1 --event=requested GPIO5 GPIO6 GPIO12 GPIO17
+
+    # Block until a line is released.
+    $ gpionotify --quiet --num-events=1 --event=released GPIO6
 
 BINDINGS
 --------