The piio command

Synopsis

piio subcommand ?arg ...?

Description

The piio command lets you manipulate the Raspberry Pi gpio pins. There are two userspace APIs for working with gpio: Sysfs interface and GPIO character device. The former is considered obsolete/deprecated. The piio package supports both.

The available subcommands are listed below. Note that you can abbreviate the subcommands.

Commands using the GPIO character device API

piio chip ?name?: Obtain information about the specified GPIO chip. If name is not specified, a list of the GPIO chips present on the machine is returned.
piio line ?-chip chip? line: Obtain information about the specified GPIO line.
piio acquire ?-option value ...? line ...: Attempt to acquire exclusive access to one or more GPIO lines. If successful, the command returns a handle that may be used in successive commands to work with the acquired GPIO lines. An error is thrown if the lines are not all currently available or in case of other issues. All requested lines share the same configuration.
piio release handle: Release the lines covered by the specified handle back to the kernel.
piio configure handle ?-option value ...?: Verify or change the configuration of the GPIO lines.
piio get handle: Obtain the current states of all the GPIO lines covered by handle. The return value is an integer, where bit0 holds the state of the first GPIO line, bit1 holds the state of the second GPIO line, etc.
piio set handle value: Set the current states of all GPIO lines covered by handle. Each bit in value represents one of the acquired GPIO lines. This command will throw an error if the lines are not currently configured as outputs.
piio poll handle: Check if there are any events present in the kernel event buffer. If so, return the first one. The lines need to be configured with an -edge setting other than none for events to be stored in the event buffer.
piio handler handle ?script?: Set up or query the handler for dealing with events detected on the GPIO lines. Whenever an event happens, the specified script is invoked with one additional argument; a dict containing information about the event. The lines need to be configured with an -edge setting other than none for events to occur.

Commands using the Sysfs interface API

piio detach gpiopin ...: Release pins that have been claimed by the sysfs API to allow them to be used by the character device API.
piio event gpiopin edge ?script?: Arrange for the Tcl script script to be called whenever the level change specified by edge (rising or falling) is detected on the input port. If script is the empty string, the current handler is deleted. If script is omitted, the currently installed script is returned (or an empty string if no such handler is installed).
piio function ?gpiopin? ?function?: Obtain or configure the function of a gpiopin. When both gpiopin and function are specified, the function of the gpio pin is configured. When only a gpiopin is specified, the current function of the pin is returned. Without arguments a list of all pin functions is returned. The gpiopin must be specified as a number between 0 and 53. Valid functions are: input, output, altfunc0, altfunc1, altfunc2, altfunc3, altfunc4, or altfunc5. Check the BCM2835 documentation for the available alternate functions for each pin.
piio input gpiopin: Reads the current state of the gpio pin. Returns 0 for low and 1 for a high logical level.
piio output gpiopin state: Set the state of a gpio output pin. The state must be specified as an integer, where 0 sets the output low and any other value sets it high.
piio pull direction gpiopin ?gpiopin ...?: Control weak pull-up or -down for an input port. Valid values for direction are: up, down, none.

Miscellaneous commands

piio usleep usec: When dealing with hardware it may be useful to be able to delay short amounts of time. This command will block for the specified number of microseconds.

Details about the GPIO character device commands

A GPIO chip may be specified using its device name gpiochip0, gpiochip1, etc. or the Linux kernel name assigned to the GPIO chip, e.g: pinctrl-bcm2835.

GPIO lines may similarly be referenced by their index or by their name. For example, on the BCM2835, line 32 may also be referred to as TXD0.

In both cases mentioned above, using a name requires a lookup operation, which is less efficient than accessing the resource directly. If efficiency is a concern, use the device name for the chip and the index for GPIO lines.

The following configuration options are available:

-bias: Specifies which type of bias, if any, is applied to the GPIO lines. Valid values are: disabled, pullup, pulldown. This setting is silently ignored when the underlying hardware does not support the requested value.
-clock: Select the clock source to be used for the timestamp of line events. Valid values are: monotonic, realtime, hardware. Selecting the hardware clock source will throw an error if the device is unable to support that method. Timestamps are always expressed in nanoseconds, irrespective of the selected clock source. When the code is compiled against version 1 of the GPIO character device userspace API, the clock source is hardcoded into the kernel and cannot be changed. It will be realtime on kernels before 5.7, and monotonic on more recent kernels.
-default: Specify the default states for the GPIO lines to be applied when the lines are changed to outputs. The value must be an integer where each bit corresponds to one of the acquired lines in the order they were requested. The value may also be specified as the empty string to disable changing any states. See also the -mask option.
-direction: Whether to use the GPIO line as input or output. Valid values are: none, input, output. When GPIO lines are requested with a direction of "none", the line is used "as-is", without altering the electrical configuration.
-driver: Specify the type of driver to be used when the GPIO lines function as outputs. Valid values are: pushpull, opendrain, opensource. If the hardware does not support the selected drive method, it is emulated by switching the line to input when it should not be actively driven.
-edge: Select which line changes, if any, should generate an event when the GPIO lines function as inputs. Valid values are: none, rising, falling, both. Specifying a setting that is not supported by the hardware will result in an error.
-logic: Specifies how to apply logical levels on the line. Valid values are: normal, inverted. When set to "normal", high is active and low is inactive. With "inverted", low is active and high is inactive.
-mask: Control which of the bits of the -default option are significant. Only lines corresponding to bits in the mask value that are set to 1 will have their state forced to the levels indicated by the -default option. By default all lines are selected.

The handle returned by the piio acquire command is actually a file descriptor. It is included in the list of open file descriptors returned by the chan names command. Regular file commands can be used to some extend on the handle: chan configure is similar to piio configure, with the distinction that piio configure works instantly, while changes made using chan configure are delayed until idle time. The chan close command is equivalent to piio release. The chan read command will read raw event buffer entries as binary data.