quick2wire.gpio Pin classes now follow same API conventions as those in ...

doc/getting-started-with-gpio.md

@@ -22,63 +22,58 @@ group membership.
 Now Let's Write Some Code!
 --------------------------
 
-The GPIO pins are controlled by GPIOPin objects. Python program must
-import the GPIOPin class from the quick2wire.gpio module, along with
-constants to configure the pin:
-
-    from quick2wire.gpio import GPIOPin, In, Out
-
-Then you can create a Pin. The Pin's constructor takes two arguments:
-the header pin number and whether the pin is to be used for input or
-output.
-
-    in_pin = Pin(0, direction=In)
-    out_pin = Pin(1, direction=Out)
-
-When you have a Pin instance you can read or write its value.  A value
-of 1 is high, a value of 0 is low.
-
-    out_pin.value = 1
-    print(in_pin.value)
-
-When you have finished using the pin, you must unexport it:
+The GPIO pins are controlled by Pin objects, and those Pin objects are
+managed by a "pin bank".  The simplest pin bank to use is called
+`pins` and gives access to the pins labelled P0 to P7 on the
+Quick2Wire interface board (or named GPIO0 to GPIO7 on the Raspberry
+Pi's header number 1).  There's also a bank called pi_header_1 that
+gives access to all the header pins, but we don't need that for this
+example.
+
+Python programs must import the `pins` pin bank from the
+`quick2wire.gpio` module, along with constants to configure the pin:
+
+    from quick2wire.gpio import pins, In, Out
+
+Then you can get a Pin by calling the pin bank's `pin` method. This
+takes two arguments: the pin number and whether the pin is to be used
+for input or output.
+
+    in_pin = pins.pin(0, direction=In)
+    out_pin = pins.pin(1, direction=Out)
+
+You must open a pin before you can read or write its value and close
+the pin when you no longer need it.  The most convenient way to do
+this is to use Python's `with` statement, which will open the pins at
+the start of the statement and close them when the body of the
+statement has finished running, even if the user kills the program or
+failure makes the code throw an exception.
+
+    with in_pin, out_pin:
+        out_pin.value = 1
+        print(in_pin.value)
 
-    out_pin.unexport()
-    in_pin.unexport()
+A pin has a value of 1 when high, a value of 0 when low.
 
 Putting it all together into a single program:
 
-    from quick2wire.gpio import Pin
-
-    in_pin = Pin(0, direction=In)
-    out_pin = Pin(1, direction=Out)
+    from quick2wire.gpio import pins, In, Out
 
-    out_pin.value = 1
-    print(in_pin.value)
+    in_pin = pins.pin(0, direction=In)
+    out_pin = pins.pin(1, direction=Out)
 
-    out_pin.unexport()
-    in_pin.unexport()
-
-To make sure you always unexport any pins you've exported, you can wrap the Pin objects
-with `exported()`, a Python [context manager](http://docs.python.org/reference/datamodel.html#context-managers),
-as part of a [with](http://docs.python.org/reference/compound_stmts.html#with) statement:
-
-    from quick2wire.gpio import Pin, exported
-
-    with exported(GPIOPin(0, direction=In)) as in_pin, exported(GPIOPin(1, direction=Out)) as out_pin:
+    with in_pin, out_pin:
         out_pin.value = 1
-    	print(in_pin.value)
+        print(in_pin.value)
 
-This will unexport the pins when the program leaves the `with` statement, even 
-if the user kills the program or a bad piece of code throws an exception.
 
 Here's a slightly more complicated example that blinks an LED attached to pin 1. This will
 loop forever until the user stops it with a Control-C.
 
     from time import sleep
-    from quick2wire.gpio import GPIOPin, Out, exported
+    from quick2wire.gpio import pins, Out
 
-    with exported(GPIOPin(1, direction=Out)) as pin:
+    with pins.pin(1, direction=Out) as pin:
         while True:
             pin.value = 1 - pin.value
             sleep(1)

examples/blink

@@ -2,16 +2,12 @@
 
 import sys
 from time import sleep
-from quick2wire.gpio import GPIOPin, Out
+from quick2wire.gpio import pins, Out
 
-pin = GPIOPin(int(sys.argv[1]) if len(sys.argv) > 1 else 1, direction=Out)
-
-
-try:
+pin = pins.pin(int(sys.argv[1]) if len(sys.argv) > 1 else 1, direction=Out)
+with pin:
     pin.value = 1
     while True:
         sleep(1)
         pin.value = 1 - pin.value
-except KeyboardInterrupt:
-    pin.value = 0
-    pin.unexport()
+

examples/button-blink

@@ -1,12 +1,13 @@
-#!/usr/bin/python3
+#!/usr/bin/env python3
 
 import sys
 from time import sleep
-from quick2wire.gpio import GPIOPin, In, Out
+from quick2wire.gpio import pins, In, Out
 
-led = GPIOPin(1, direction=Out)
-button = GPIOPin(0, direction=In)
+led = pins.pin(1, direction=Out)
+button = pins.pin(0, direction=In)
 
-while True:
-      led.value = button.value
-      sleep(0.1)
+with led, button:
+     while True:
+          led.value = button.value
+          sleep(0.1)

examples/counter

@@ -1,19 +1,20 @@
-#!/usr/bin/python3
+#!/usr/bin/env python3
 
 from itertools import cycle
 from time import sleep
-from quick2wire.gpio import Pin
+from quick2wire.gpio import gpio, Out
 
-pins = [Pin(n, Pin.Out) for n in [7, 22, 18, 16, 15, 13, 12, 11]]
+pins = [gpio.pin(i, Out) for i in range(8)]
 
 try:
+    for p in pins:
+        p.open()
+
     for count in cycle(range(256)):
         bitset = [int(count & (1<<n) > 0) for n in range(8)]
         for (pin, value) in zip(pins, bitset):
             pin.value = value
         sleep(0.5)
-
-except KeyboardInterrupt:
-    for pin in pins:
-        pin.value = 0
-        pin.unexport()
+finally:
+    for p in pins:
+        p.close()

examples/gpio-speed

@@ -1,12 +1,9 @@
-#!/usr/bin/env python
+#!/usr/bin/env python3
 
 from datetime import datetime
-from quick2wire.gpio import Pin
+from quick2wire.gpio import pins, In, Out
 from timeit import Timer
 
-outpin = Pin(12, Pin.Out)
-inpin = Pin(11, Pin.In)
-iterations = 10000
 
 def nothin():
     pass
@@ -18,12 +15,16 @@ def onepass_toggle():
     outpin.value = 1
     outpin.value = 0
 
-overhead = Timer(nothin).timeit(iterations)
-readresult = Timer(onepass_read).timeit(iterations)
-toggleresult = Timer(onepass_toggle).timeit(iterations)
+iterations = 10000
 
-print("The time to do nothing %d times is %4.3fsec" % (iterations, overhead))
-print("The time to read %d times is %4.3fsec" % (iterations, readresult))
-print("The time to toggle %d times is %4.3fsec" % (iterations, toggleresult))
+outpin = pins.pin(0, Out)
+inpin = pins.pin(1, In)
 
+with inpin, outpin:
+    overhead = Timer(nothin).timeit(iterations)
+    readresult = Timer(onepass_read).timeit(iterations)
+    toggleresult = Timer(onepass_toggle).timeit(iterations)
 
+    print("The time to do nothing %d times is %4.3fsec" % (iterations, overhead))
+    print("The time to read %d times is %4.3fsec" % (iterations, readresult))
+    print("The time to toggle %d times is %4.3fsec" % (iterations, toggleresult))

examples/pullup

@@ -5,16 +5,14 @@
 # the Pi's GPIO pins.
 #
 
-from quick2wire.gpio import Pin
+from quick2wire.gpio import pins, In, PullUp, PullDown
 
-pin = Pin(11, Pin.In)
-print( "Pull up/down is unspecified, pin is now", pin.value)
-pin.unexport()
+with pins.pin(0, In) as pin:
+    print("Pull up/down is unspecified, pin is now", pin.value)
 
-pin = Pin(11, Pin.In, pull=Pin.PullUp)
-print( "Pin is set with pull up, pin in is now", pin.value)
-pin.unexport()
+with pins.pin(0, In, pull=PullUp) as pin:
+    print("Pin is set with pull up, pin in is now", pin.value)
+
+with pins.pin(0, In, pull=PullDown) as pin:
+    print("Pin is set with pull down, pin is now", pin.value)
 
-pin = Pin(11, Pin.In, pull=Pin.PullDown)
-print( "Pin is set with pull down, pin is now", pin.value)
-pin.unexport()

examples/selector-button-blink

@@ -1,15 +1,15 @@
-#!/usr/bin/python3
+#!/usr/bin/env python3
 
 import sys
 import os
 from contextlib import closing
-from quick2wire.gpio import GPIOPin, Both, In, Out, exported
+from quick2wire.gpio import pins, Both, In, Out
 from quick2wire.selector import Selector, Timer
 
 blink_rate=2.0
 
-with exported(GPIOPin(0, direction=In, interrupt=Both)) as button_pin, \
-     exported(GPIOPin(1, direction=Out)) as led_pin, \
+with pins.pin(0, direction=In, interrupt=Both) as button_pin, \
+     pins.pin(1, direction=Out) as led_pin, \
      Timer(interval=1/blink_rate) as timer, \
      Selector() as selector:
 

quick2wire/board_revision.py

@@ -8,3 +8,4 @@ def revision():
                 return 0
     except:
         return 0
+