README.md

   1 # PL2303 and CP2103 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 and CP2103 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
   8 Since no common GPIO driver for those exists at the time of writing in
   9 the linux kernel - this should serve as a placeholder till upstream guys
  10 fix that.
  11
  12
  13 # Compiling & installing
  14
  15 You'll need libusb-1.0-dev, gcc and pkg-config. Just run
  16
  17 ```
  18 make
  19 sudo make install
  20 ```
  21 ##Installing udev rules (Linux only)
  22
  23 This package comes with udev rules that will be dropped into your
  24 /etc/udev/rules.d/
  25
  26 To automagically install and reload rules run
  27
  28 ```
  29 sudo make install-rules
  30 ```
  31
  32 and replug your pl2303/cp2103 dongles. You should no longer need root
  33 permissions to access gpio in them.
  34
  35 ## Do I have to close minicom / rmmod pl2303 to use this tool ?
  36
  37 Nope. Just run it in a separate terminal whenever you need it
  38
  39 ## Can I chose which of 70 PL2303 devices plugged this will work with?
  40
  41 Yep. You can specify --product, --serial and --manuf strings to match
  42 the device you want.
  43 These must _precede_ any other options. Example:
  44
  45 ```
  46 ./cp2303gpio --product=PowerUART --serial=fireblade --gpio 0 --out 1
  47 ```
  48
  49 ## Usage
  50
  51 CP2103
  52 ```
  53 PL2303HXA/CP2103 userspace GPIO control tool
  54 (c) Andrew 'Necromant' Andrianov 2014, License: GPLv3
  55 Usage: ./cp2103gpio [action1] [action2] ...
  56 Options are:
  57          --product=blah    - Use device with this 'product' string
  58          --serial=blah     - Use device with this 'serial' string
  59          --manuf=blah      - Use device with this 'manufacturer' string
  60          -g/--gpio  n      - select GPIO, n=0, 1
  61          -i/--in           - configure GPIO as input
  62          -o/--out v        - configure GPIO as output with value v
  63          -r/--read v       - Read current GPIO value
  64
  65          -s/--sleep v      - Delay for v ms
  66
  67 Examples:
  68         ./cp2103gpio --gpio=1 --out 1
  69         ./cp2103gpio --gpio=0 --out 0 --gpio=1 --in
  70
  71 All arguments are executed from left to right, you can add
  72 delays using --sleep v option. e.g.
  73         ./cp2103gpio --gpio=0 --out 0 --sleep 1000 --gpio=0 --out 1
  74 ```
  75
  76 PL2303
  77 ```
  78 PL2303HXA/CP2103 userspace GPIO control tool
  79 (c) Andrew 'Necromant' Andrianov 2014, License: GPLv3
  80 Usage: ./pl2303gpio [action1] [action2] ...
  81 Options are:
  82          --product=blah    - Use device with this 'product' string
  83          --serial=blah     - Use device with this 'serial' string
  84          --manuf=blah      - Use device with this 'manufacturer' string
  85          -g/--gpio  n      - select GPIO, n=0, 1
  86          -i/--in           - configure GPIO as input
  87          -o/--out v        - configure GPIO as output with value v
  88          -r/--read v       - Read current GPIO value
  89
  90          -s/--sleep v      - Delay for v ms
  91
  92 Examples:
  93         ./pl2303gpio --gpio=1 --out 1
  94         ./pl2303gpio --gpio=0 --out 0 --gpio=1 --in
  95
  96 All arguments are executed from left to right, you can add
  97 delays using --sleep v option. e.g.
  98         ./pl2303gpio --gpio=0 --out 0 --sleep 1000 --gpio=0 --out 1
  99 ```
 100
 101 ## Limitations
 102 cp2303 code misses magic required for 'input' mode of GPIO lines.
 103
 104 ## Tips and tricks
 105 The arguments are executed from left to right. Therefore you can use only one
 106 call to pl2303gpio/cp2303gpio to execute a sequence of actions. If the gpio line
 107 stays the same, you can omit subsequent --gpio arguments.
 108 You can use --sleep to add arbitary delays (in milliseconds)
 109
 110 Example (sets the gpio3 line to 1, sleeps for one second, sets the gpio3 to 0:
 111 ```
 112 ./cp2303gpio --gpio=3 --out=1 --sleep=1000 --out=0
 113 ```
 114
 115 ##Bonus scripts
 116 The 'extra' directory contains a few scripts I use on my OpenWRT box to manage a few
 117 SBC servers. They are installed via install-scripts.
 118
 119 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').
 120 serverd   - is a lua daemon that pings servers in round-robin fasion and displays their state on LEDs
 121
 122 ## Mac OS X hint
 123 These tools have been reported to work on Mac OS X. For obvious reasons you
 124 don't need udev rules on a mac.
 125
 126
 127 ## License
 128
 129 GPLv3. I'm too lazy to copy all the text here. Google for it.