opio/opio.1

.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "OPIO" "1" "Aug 2021" "opio v1.0" ""
.hy
.SH NAME
.PP
opio - Control GPIO pins on OrangePi.
A replacement for WiringPi
.SH SYNOPSIS
.PP
\f[B]opio\f[R] [-2] readall
.PP
\f[B]opio\f[R] [-2] readallx
.PP
\f[B]opio\f[R] [-2] exports
.PP
\f[B]opio\f[R] leds
.PP
\f[B]opio\f[R] mode \f[I]pin\f[R] [ in | out | alt ]
.PP
\f[B]opio\f[R] [ -d ] read \f[I]pin\f[R]
.PP
\f[B]opio\f[R] [ -d ] write \f[I]pin\f[R] [ 1 | 0 | on | off ]
.SH DESCRIPTION
.PP
\f[B]opio\f[R] allows access to the GPIO pins of OrangePi single-board
computers.
This version is designed speciifically for the
.IP \[bu] 2
OrangePi i96
.IP \[bu] 2
OrangePi 2G-iot
.PP
Running \f[B]opio\f[R] without any parameters will show its usage.
\f[B]opio\f[R] requires `su' permissions, so must be run as `root' or
via `sudo'.
.SH COMMANDS
.TP
\f[B]readall\f[R]
Displays the state of the gpio pins in a grid format.
The list includes all the pins used in the on-board 40 pin connector.
For each pin, the listing shows the gpio pin number, its alternate
function, its i96 pin name, its current \f[I]mode\f[R] and
\f[I]value\f[R], and the corresponding pin number on the 40 pin
connector.
.TP
\f[B]readallx\f[R]
Creates a similar chart, but includes the RDA pin names.
.TP
\f[B]leds\f[R]
Creates a smaller chart, for the interesting I/O pins which are
\f[I]not\f[R] part of the 40 pin connector.
On the i96 board, there are 3 LEDs which can be controlled via
\f[B]opio\f[R]
.TP
\f[B]exports\f[R]
Print a list of entries in /sys/class/gpio, indicating which pins have
been exported (prepared for read/write).
If a gpio pin exists on the 40 pin connector, the pin number is listed.
.TP
\f[B]mode\f[R]
Sets the \f[I]mode\f[R] for a pin as either `in', `out' or
`alternate-function'.
Normally \f[B]opio\f[R] will create an export for this gpio pin, and
then set the direction.
If you set the `alt' function, the export will be removed.
With the \f[B]-d\f[R] option, the export is not created, but the
`in'/`out'/`alt' \f[I]mode\f[R] setting will still be done.
\f[B]mode\f[R] with a pin number and no set-mode request, will simply
return the current \f[I]mode\f[R] (in, out, alt, in*, alt*).
.TP
\f[B]read\f[R]
Returns the current \f[I]value\f[R] (1/0) of the gpio pin, if possible.
If the pin is in `alt' \f[I]mode\f[R], it is changed to `in' before the
\f[I]value\f[R] is read.
.TP
\f[B]write\f[R]
Attempts to write the given \f[I]value\f[R] into the given pin.
If the pin is in `alt' \f[I]mode\f[R], it is changed to `out' before the
\f[I]value\f[R] is asserted.
.SH OPTIONS
.TP
\f[B]-d\f[R]
Use low-level access to control the pins.
Without the \f[B]-d\f[R] option, \f[B]opio\f[R] tries to use the
`export' gpio mechanism (at /sys/class/gpio).
The \f[B]-d\f[R] option only applies to \f[B]mode, read\f[R] and
\f[B]write\f[R]
.TP
\f[B]-2\f[R]
Use the pin assignments for the OrangePi-2G-iot.
The default is to use the pins for the OrangePi-i96.
If you wish to make this option persistent, create a file named
/etc/OrangePi_2G_IOT.
.SS Mode
.PP
The microcontroller used on these boards presents i/o pins which can be
set to `general usage' GPIO as `input' or `output, or alternatively, set
to operate in a specific way (uart, i2c, i2s, pcm, etc). \f[B]opio\f[R]
refers the the current \f[I]mode\f[R] of each pin one of these: either
GPIO \[cq]in', GPIO `out', or \[cq]alt\[cq]ernate function.
.PP
The `in*' or `out*' are marked with an asterisk to indicate that the pin
is in GPIO \f[I]mode\f[R], but \f[I]not\f[R] listed in the current
`export' list.
.PP
As a convenience, the \f[B]read\f[R] and \f[B]write\f[R] commands will
automatically set the \f[I]mode\f[R] on the GPIO pin and create an
export.
So, generally, the \f[B]mode\f[R] command is only \f[I]required\f[R] if
you wish to change a pin back to its `alt' function.
.SH HERITAGE
.PP
This program is styled after the \f[B]gpio\f[R] program written by
Gordon Henderson for the Raspberry Pi.
Unlike the original \f[B]gpio\f[R] program, this one does not implement:
.IP \[bu] 2
export\&...\&...\&.....exports are created automatically by \f[B]mode,
read\f[R] and \f[B]write\f[R]
.IP \[bu] 2
pwm, clk\&...\&...\&...this microcontroller does not have PWM or CLK
type pins
.IP \[bu] 2
aread, awrite\&....these boards have not connected and ADC/DAC pins
.SH NUMBERING
.PP
There are 4 naming schemes used to identify pins in these boards.
\f[B]opio\f[R] uses exclusively the Linux gpio device driver numbers,
the first on this list:
.IP \[bu] 2
Linux gpio numbers (from /sys/class/gpio)
.IP \[bu] 2
I/O connector pin numbers (1-40)
.IP \[bu] 2
RDA microcontroller pin names (like GPIOA_C23)
.IP \[bu] 2
i96 pin names (like GPIOB)
.PP
You can explore the correspondence between these naming schemes with
\f[B]opio readall\f[R] and \f[B]opio readallx\f[R]
.SH HIGH LEVEL/LOW LEVEL ACCESS
.PP
Normally, \f[B]opio\f[R] will access the GPIO pins through the Linux
gpio device driver, and the corresponding files at
\f[C]/sys/class/gpio\f[R].
This is \f[I]high level\f[R] access.
.PP
If you wish to bypass the Linux gpio driver, add the \f[C]-d\f[R] option
to the \f[B]opio\f[R] command line and the reads/writes will be done at
a \f[I]low level\f[R], directly on the machine\[cq]s registers.
.PP
The commands \f[B]readall, readallx\f[R] and \f[B]leds\f[R] are always
done using \f[I]low level\f[R] access.
The \f[B]exports\f[R] command is always done with \f[I]high level\f[R]
commands.
.PP
Be careful about making changed with the \f[B]-d\f[R] option.
Some linux gpio drivers will direction and value, so changes you make
with the \f[B]-d\f[R] option may not be reflected in the export folder.
.SH EXAMPLES
.PP
display a chart of the pin assignments of the 40 pin connector:
.IP
.nf
\f[C]
opio readall     
\f[R]
.fi
.PP
list the currently `exported' pins:
.IP
.nf
\f[C]
opio exports
\f[R]
.fi
.PP
set gpio 15 to an output; also create an export for gpio15 \&...then
flash the pin (gpio15 Linux number):
.IP
.nf
\f[C]
opio mode 15 out    
opio write 15 on
sleep 2
opio write 15 off   
\f[R]
.fi
.PP
set gpio 15 to an output; do \f[I]not\f[R] create an export
.IP
.nf
\f[C]
opio -d mode 15 out 
\f[R]
.fi
.PP
write to gpio15 pin, bypassing the export mechanism
.IP
.nf
\f[C]
opio -d write 15 on  
\f[R]
.fi
.PP
\f[B]NOTE\f[R] The more recent /dev/gpio driver is not yet available on
these boards, since they\[cq]re running the 3.xx kernels.
.PP
\f[B]NOTE\f[R] The 2G-IOT board uses the I2C1 bus to communicate with
the modem chip.
This is i2c-0 in the kernel, and is pins 3 & 5 on the 40 pin connector.
Do not use these pins to connect to peripherals.
And do not use \f[B]opio\f[R] to modify the \f[I]mode\f[R] of these
pins.
.PP
\f[B]NOTE\f[R] The 2G-IOT board uses the I2C3 bus to communicate with
the LCD.
If you are using an LCD in the socket, do \f[I]not\f[R] change the mode
on pins 38 & 40.
.SH AUTHORS
Pat Beirne <patb@pbeirne.com>.