opio.1 6.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227
  1. .\" Automatically generated by Pandoc 2.9.2.1
  2. .\"
  3. .TH "OPIO" "1" "Oct 2021" "opio v2.1" ""
  4. .hy
  5. .SH NAME
  6. .PP
  7. opio - Control GPIO pins on OrangePi.
  8. A replacement for WiringPi
  9. .SH SYNOPSIS
  10. .PP
  11. \f[B]opio\f[R] [-2] readall {or status}
  12. .PP
  13. \f[B]opio\f[R] [-2] readallx {or statusx}
  14. .PP
  15. \f[B]opio\f[R] [-2] exports
  16. .PP
  17. \f[B]opio\f[R] leds
  18. .PP
  19. \f[B]opio\f[R] mode \f[I]pin\f[R] [ in | out | alt ]
  20. .PP
  21. \f[B]opio\f[R] [ -d ] read \f[I]pin\f[R]
  22. .PP
  23. \f[B]opio\f[R] [ -d ] write \f[I]pin\f[R] [ 1 | 0 | on | off ]
  24. .SH DESCRIPTION
  25. .PP
  26. \f[B]opio\f[R] allows access to the GPIO pins of OrangePi single-board
  27. computers.
  28. This version is designed speciifically for the
  29. .IP \[bu] 2
  30. OrangePi i96
  31. .IP \[bu] 2
  32. OrangePi 2G-iot
  33. .PP
  34. Running \f[B]opio\f[R] without any parameters will show its usage.
  35. \f[B]opio\f[R] requires `su' permissions, so must be run as `root' or
  36. via `sudo'.
  37. .SH COMMANDS
  38. .TP
  39. \f[B]readall\f[R] or \f[B]status\f[R]
  40. Displays the state of the gpio pins in a grid format.
  41. The list includes all the pins used in the on-board 40 pin connector.
  42. For each pin, the listing shows the gpio pin number, its alternate
  43. function, its i96 pin name, its current \f[I]mode\f[R] and
  44. \f[I]value\f[R], and the corresponding pin number on the 40 pin
  45. connector.
  46. .TP
  47. \f[B]readallx\f[R] or \f[B]statusx\f[R]
  48. Creates a similar chart, but includes the RDA pin names and Linux device
  49. driver names.
  50. .TP
  51. \f[B]leds\f[R]
  52. Creates a smaller chart, for the interesting I/O pins which are
  53. \f[I]not\f[R] part of the 40 pin connector.
  54. On the i96 board, there are 3 LEDs which can be controlled via
  55. \f[B]opio\f[R]
  56. .TP
  57. \f[B]exports\f[R]
  58. Print a list of current entries in /sys/class/gpio, indicating which
  59. pins have been exported (prepared for read/write).
  60. If a gpio pin exists on the 40 pin connector, the pin number is listed.
  61. .TP
  62. \f[B]mode\f[R]
  63. Sets the \f[I]mode\f[R] for a pin as either `in', `out' or
  64. `alternate-function'.
  65. Normally \f[B]opio\f[R] will create an export for this gpio pin, and
  66. then set the direction.
  67. If you set the `alt' function, the export will be removed.
  68. With the \f[B]-d\f[R] option, the export is not created, but the
  69. `in'/`out'/`alt' \f[I]mode\f[R] setting will still be done.
  70. .IP \[bu] 2
  71. \f[B]mode\f[R] with a pin number and no set-mode request, will simply
  72. return the current \f[I]mode\f[R] (in, out, alt, in*, alt*).
  73. .TP
  74. \f[B]read\f[R]
  75. Returns the current \f[I]value\f[R] (1/0) of the gpio pin, if possible.
  76. If the pin is in `alt' \f[I]mode\f[R], it is changed to `in' before the
  77. \f[I]value\f[R] is read.
  78. .TP
  79. \f[B]write\f[R]
  80. Attempts to write the given \f[I]value\f[R] into the given pin.
  81. If the pin is in `alt' \f[I]mode\f[R], it is changed to `out' before the
  82. \f[I]value\f[R] is asserted.
  83. .SH OPTIONS
  84. .TP
  85. \f[B]-d\f[R]
  86. Use low-level access to control the pins.
  87. Without the \f[B]-d\f[R] option, \f[B]opio\f[R] tries to use the
  88. `export' gpio mechanism (at /sys/class/gpio).
  89. The \f[B]-d\f[R] option only applies to \f[B]mode, read\f[R] and
  90. \f[B]write\f[R]
  91. .TP
  92. \f[B]-2\f[R]
  93. Use the pin assignments for the OrangePi-2G-iot.
  94. The default is to use the pins for the OrangePi-i96.
  95. If you wish to make this option persistent, create a file named
  96. /etc/OrangePi_2G_IOT.
  97. .SS Mode
  98. .PP
  99. The microcontroller used on these boards presents i/o pins which can be
  100. set to `general usage' GPIO as `input' or `output, or alternatively, set
  101. to operate in a specific way (uart, i2c, i2s, pcm, etc). \f[B]opio\f[R]
  102. refers the the current \f[I]mode\f[R] of each pin one of these: either
  103. GPIO \[cq]in', GPIO `out', or \[cq]alt\[cq]ernate function.
  104. .PP
  105. The `in*' or `out*' are marked with an asterisk to indicate that the pin
  106. is in GPIO \f[I]mode\f[R], but \f[I]not\f[R] listed in the current
  107. `export' list.
  108. .PP
  109. As a convenience, the \f[B]read\f[R] and \f[B]write\f[R] commands will
  110. automatically set the \f[I]mode\f[R] on the GPIO pin and create an
  111. export.
  112. So, generally, the \f[B]mode\f[R] command is only \f[I]required\f[R] if
  113. you wish to change a pin back to its `alt' function.
  114. .SH HERITAGE
  115. .PP
  116. This program is styled after the \f[B]gpio\f[R] program written by
  117. Gordon Henderson for the Raspberry Pi.
  118. Unlike the original \f[B]gpio\f[R] program, this one does not implement:
  119. .IP \[bu] 2
  120. export\&...\&...\&.....exports are created automatically by \f[B]mode,
  121. read\f[R] and \f[B]write\f[R]
  122. .IP \[bu] 2
  123. pwm, clk\&...\&...\&...this microcontroller does not have PWM or CLK
  124. type pins
  125. .IP \[bu] 2
  126. aread, awrite\&....these boards have not connected and ADC/DAC pins
  127. .SH NUMBERING
  128. .PP
  129. There are 4 naming schemes used to identify pins in these boards.
  130. \f[B]opio\f[R] uses exclusively the Linux gpio device driver numbers,
  131. the first on this list:
  132. .IP \[bu] 2
  133. Linux gpio numbers (from /sys/class/gpio)
  134. .IP \[bu] 2
  135. I/O connector pin numbers (1-40)
  136. .IP \[bu] 2
  137. RDA microcontroller pin names (like GPIOA_C23)
  138. .IP \[bu] 2
  139. i96 pin names (like GPIOB)
  140. .PP
  141. You can explore the correspondence between these naming schemes with
  142. \f[B]opio readall\f[R] and \f[B]opio readallx\f[R]
  143. .SH HIGH LEVEL/LOW LEVEL ACCESS
  144. .PP
  145. Normally, \f[B]opio\f[R] will access the GPIO pins through the Linux
  146. gpio device driver, and the corresponding files at
  147. \f[C]/sys/class/gpio\f[R].
  148. This is \f[I]high level\f[R] access.
  149. .PP
  150. If you wish to bypass the Linux gpio driver, add the \f[C]-d\f[R] option
  151. to the \f[B]opio\f[R] command line and the reads/writes will be done at
  152. a \f[I]low level\f[R], directly on the machine\[cq]s registers.
  153. .PP
  154. The commands \f[B]readall, readallx\f[R] and \f[B]leds\f[R] are always
  155. done using \f[I]low level\f[R] access.
  156. The \f[B]exports\f[R] command is always done with \f[I]high level\f[R]
  157. commands.
  158. .PP
  159. Be careful about making changed with the \f[B]-d\f[R] option.
  160. Some linux gpio drivers will cache the direction and value, so changes
  161. you make with the \f[B]-d\f[R] option may not be reflected in the export
  162. folder.
  163. .SH EXAMPLES
  164. .PP
  165. display a chart of the pin assignments of the 40 pin connector:
  166. .IP
  167. .nf
  168. \f[C]
  169. opio readall
  170. \f[R]
  171. .fi
  172. .PP
  173. list the currently `exported' pins:
  174. .IP
  175. .nf
  176. \f[C]
  177. opio exports
  178. \f[R]
  179. .fi
  180. .PP
  181. set gpio 15 to an output; also create an export for gpio15 \&...then
  182. flash the pin (gpio15 Linux number):
  183. .IP
  184. .nf
  185. \f[C]
  186. opio mode 15 out
  187. opio write 15 on
  188. sleep 2
  189. opio write 15 off
  190. \f[R]
  191. .fi
  192. .PP
  193. set gpio 15 to an output; do \f[I]not\f[R] create an export
  194. .IP
  195. .nf
  196. \f[C]
  197. opio -d mode 15 out
  198. \f[R]
  199. .fi
  200. .PP
  201. write to gpio15 pin, bypassing the export mechanism
  202. .IP
  203. .nf
  204. \f[C]
  205. opio -d write 15 on
  206. \f[R]
  207. .fi
  208. .PP
  209. \f[B]NOTE\f[R] The more recent /dev/gpio driver is not yet available on
  210. these boards, since they\[cq]re running the 3.xx kernels.
  211. .PP
  212. \f[B]NOTE\f[R] The 2G-IOT board uses the I2C1 bus to communicate with
  213. the modem chip.
  214. This is i2c-0 in the kernel, and is pins 3 & 5 on the 40 pin connector.
  215. Do not use these pins to connect to peripherals.
  216. And do not use \f[B]opio\f[R] to modify the \f[I]mode\f[R] of these
  217. pins.
  218. .PP
  219. \f[B]NOTE\f[R] The 2G-IOT board uses the I2C3 bus to communicate with
  220. the LCD.
  221. If you are using an LCD in the socket, do \f[I]not\f[R] change the mode
  222. on pins 38 & 40.
  223. .PP
  224. \f[B]NOTE\f[R] To create a man page, run
  225. \f[C]pandoc README.md -s -o opio.1\f[R]
  226. .SH AUTHORS
  227. Pat Beirne <patb@pbeirne.com>.