README.md

   1 # PL2303, CP2103 and FT232R Userspace GPIO control tools
   2
   3 This is a set of small tools for linux userspace that allows you to interact
   4 with GPIO lines on PL2303HX, CP2103 and FT232R devices.
   5 PL2303: It has only been tested on PL2303HXA, but may work for other revisions.
   6 CP2103: It has only been tested on CP2103, but may work for other revisions/versions.
   7 FT232R: It has only been tested on FT232R, but may work also for other revisions/versions.
   8
   9 Since no common GPIO driver for those exists at the time of writing in
  10 the linux kernel - this should serve as a placeholder till upstream guys
  11 fix that.
  12
  13
  14 # Compiling & installing
  15
  16 You'll need libusb-1.0-dev, gcc and pkg-config. Just run
  17
  18 ```
  19 make
  20 sudo make install
  21 ```
  22 ##Installing udev rules (Linux only)
  23
  24 This package comes with udev rules that will be dropped into your
  25 /etc/udev/rules.d/
  26
  27 To automagically install and reload rules run
  28
  29 ```
  30 sudo make install-rules
  31 ```
  32
  33 and replug your pl2303/cp2103/ft232r dongles. You should no longer need root
  34 permissions to access gpio in them.
  35
  36 ## Do I have to close minicom / rmmod pl2303 or rmmod ftdi_sio to use this tool ?
  37
  38 Nope. Just run it in a separate terminal whenever you need it
  39
  40 ## Can I chose which of 70 PL2303 devices plugged this will work with?
  41
  42 Yep. You can specify --product, --serial and --manuf strings to match
  43 the device you want.
  44 These must _precede_ any other options. Example:
  45
  46 ```
  47 ./cp2303gpio --product=PowerUART --serial=fireblade --gpio 0 --out 1
  48 ```
  49
  50 ## Usage
  51
  52 CP2103
  53 ```
  54 PL2303HXA/CP2103 userspace GPIO control tool
  55 (c) Andrew 'Necromant' Andrianov 2014, License: GPLv3
  56 Usage: ./cp2103gpio [action1] [action2] ...
  57 Options are:
  58          --product=blah    - Use device with this 'product' string
  59          --serial=blah     - Use device with this 'serial' string
  60          --manuf=blah      - Use device with this 'manufacturer' string
  61          -g/--gpio  n      - select GPIO, n=0, 1
  62          -i/--in           - configure GPIO as input
  63          -o/--out v        - configure GPIO as output with value v
  64          -r/--read v       - Read current GPIO value
  65
  66          -s/--sleep v      - Delay for v ms
  67
  68 Examples:
  69         ./cp2103gpio --gpio=1 --out 1
  70         ./cp2103gpio --gpio=0 --out 0 --gpio=1 --in
  71
  72 All arguments are executed from left to right, you can add
  73 delays using --sleep v option. e.g.
  74         ./cp2103gpio --gpio=0 --out 0 --sleep 1000 --gpio=0 --out 1
  75 ```
  76
  77 PL2303
  78 ```
  79 PL2303HXA/CP2103 userspace GPIO control tool
  80 (c) Andrew 'Necromant' Andrianov 2014, License: GPLv3
  81 Usage: ./pl2303gpio [action1] [action2] ...
  82 Options are:
  83          --product=blah    - Use device with this 'product' string
  84          --serial=blah     - Use device with this 'serial' string
  85          --manuf=blah      - Use device with this 'manufacturer' string
  86          -g/--gpio  n      - select GPIO, n=0, 1
  87          -i/--in           - configure GPIO as input
  88          -o/--out v        - configure GPIO as output with value v
  89          -r/--read v       - Read current GPIO value
  90
  91          -s/--sleep v      - Delay for v ms
  92
  93 Examples:
  94         ./pl2303gpio --gpio=1 --out 1
  95         ./pl2303gpio --gpio=0 --out 0 --gpio=1 --in
  96
  97 Notes:
  98         pl2302gpio actually do *not* support for gpio>=2.
  99         Witout notice gpio=0 is used in this case!
 100
 101 All arguments are executed from left to right, you can add
 102 delays using --sleep v option. e.g.
 103         ./pl2303gpio --gpio=0 --out 0 --sleep 1000 --gpio=0 --out 1
 104 ```
 105
 106 FT232R
 107 ```
 108 FT232R userspace GPIO control tool
 109 (c) Peter Henn 2017, License: GPLv3
 110 Usage: ./ft232rgpio [action1] [action2] ...
 111 Options are:
 112          --product=blah    - Use device with this 'product' string
 113          --serial=blah     - Use device with this 'serial' string
 114          --manuf=blah      - Use device with this 'manufacturer' string
 115          -g/--gpio  n      - select GPIO, n=0, 1
 116          -i/--in           - configure GPIO as input
 117          -o/--out v        - configure GPIO as output with value v
 118          -r/--read v       - Read current GPIO value
 119
 120          -s/--sleep v      - Delay for v ms
 121
 122 Examples:
 123         ./ft232rgpio --gpio=1 --out 1
 124         ./ft232rgpio --gpio=0 --out 0 --gpio=1 --in
 125
 126 Notes:
 127         Changing the so called CBUS GPIO lines of the FT232R chip
 128         requires prior a correct programming of the embedded EEPROM
 129         of this chip. Ft232rgpio is tested only for gpio outputs
 130         and altering only one GPIO line!
 131
 132 All arguments are executed from left to right, you can add
 133 delays using --sleep v option. e.g.
 134         ./ft232rgpio --gpio=0 --out 0 --sleep 1000 --gpio=0 --out 1
 135 ```
 136
 137
 138 ## Limitations
 139 cp2303 code misses magic required for 'input' mode of GPIO lines.
 140
 141 ## Tips and tricks
 142 The arguments are executed from left to right. Therefore you can use only one
 143 call to pl2303gpio/cp2303gpio to execute a sequence of actions. If the gpio line
 144 stays the same, you can omit subsequent --gpio arguments.
 145 You can use --sleep to add arbitary delays (in milliseconds)
 146
 147 Example (sets the gpio3 line to 1, sleeps for one second, sets the gpio3 to 0:
 148 ```
 149 ./cp2303gpio --gpio=3 --out=1 --sleep=1000 --out=0
 150 ```
 151
 152 ##Bonus scripts
 153 The 'extra' directory contains a few scripts I use on my OpenWRT box to manage a few
 154 SBC servers. They are installed via install-scripts.
 155
 156 serverctl - is a bach script that allows quickly to power on/power off/reboot/access minicom on any of the boxes by just supplying the hostname (which is also wired into cp2303 onboard eeprom as 'serial number').
 157 serverd   - is a lua daemon that pings servers in round-robin fasion and displays their state on LEDs
 158
 159 ## Mac OS X hint
 160 These tools have been reported to work on Mac OS X. For obvious reasons you
 161 don't need udev rules on a mac.
 162
 163
 164 ## License
 165
 166 GPLv3. I'm too lazy to copy all the text here. Google for it.