From bc0bc764fc505c1e96e02f137a468e0aca9dda58 Mon Sep 17 00:00:00 2001
From: Damien George <damien.p.george@gmail.com>
Date: Tue, 4 Nov 2014 18:07:06 +0000
Subject: [PATCH] docs: Add debounce tutorial; order Pin methods; add pull
 resistor info.

---
 docs/library/pyb.Pin.rst   | 59 ++++++++++++++++++++------------------
 docs/tutorial/debounce.rst | 37 ++++++++++++++++++++++++
 docs/tutorial/index.rst    |  1 +
 3 files changed, 69 insertions(+), 28 deletions(-)
 create mode 100644 docs/tutorial/debounce.rst

diff --git a/docs/library/pyb.Pin.rst b/docs/library/pyb.Pin.rst
index 576268172..010996acf 100644
--- a/docs/library/pyb.Pin.rst
+++ b/docs/library/pyb.Pin.rst
@@ -55,6 +55,9 @@ an ordinal pin number:
 You can set ``pyb.Pin.debug(True)`` to get some debug information about
 how a particular object gets mapped to a pin.
 
+When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled,
+that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND
+respectively (except pin Y5 which has 11k Ohm resistors).
 
 Constructors
 ------------
@@ -62,7 +65,7 @@ Constructors
 .. class:: pyb.Pin(id, ...)
 
    Create a new Pin object associated with the id.  If additional arguments are given,
-   they are used to initialise the pin.  See ``init``.
+   they are used to initialise the pin.  See :meth:`pin.init`.
 
 
 Class methods
@@ -88,24 +91,6 @@ Class methods
 Methods
 -------
 
-.. method:: pin.__str__()
-
-   Return a string describing the pin object.
-
-.. method:: pin.af()
-
-   Returns the currently configured alternate-function of the pin. The
-   integer returned will match one of the allowed constants for the af
-   argument to the init function.
-
-.. method:: pin.gpio()
-
-   Returns the base address of the GPIO block associated with this pin.
-
-.. method:: pin.high()
-
-   Set the pin to a high logic level.
-
 .. method:: pin.init(mode, pull=Pin.PULL_NONE, af=-1)
 
    Initialise the pin:
@@ -126,10 +111,37 @@ Methods
    
    Returns: ``None``.
 
+.. method:: pin.high()
+
+   Set the pin to a high logic level.
+
 .. method:: pin.low()
 
    Set the pin to a low logic level.
 
+.. method:: pin.value([value])
+
+   Get or set the digital logic level of the pin:
+
+     - With no argument, return 0 or 1 depending on the logic level of the pin.
+     - With ``value`` given, set the logic level of the pin.  ``value`` can be
+       anything that converts to a boolean.  If it converts to ``True``, the pin
+       is set high, otherwise it is set low.
+
+.. method:: pin.__str__()
+
+   Return a string describing the pin object.
+
+.. method:: pin.af()
+
+   Returns the currently configured alternate-function of the pin. The
+   integer returned will match one of the allowed constants for the af
+   argument to the init function.
+
+.. method:: pin.gpio()
+
+   Returns the base address of the GPIO block associated with this pin.
+
 .. method:: pin.mode()
 
    Returns the currently configured mode of the pin. The integer returned
@@ -158,15 +170,6 @@ Methods
    will match one of the allowed constants for the pull argument to the init
    function.
 
-.. method:: pin.value([value])
-
-   Get or set the digital logic level of the pin:
-   
-     - With no argument, return 0 or 1 depending on the logic level of the pin.
-     - With ``value`` given, set the logic level of the pin.  ``value`` can be
-       anything that converts to a boolean.  If it converts to ``True``, the pin
-       is set high, otherwise it is set low.
-
 
 Constants
 ---------
diff --git a/docs/tutorial/debounce.rst b/docs/tutorial/debounce.rst
new file mode 100644
index 000000000..f730e1d34
--- /dev/null
+++ b/docs/tutorial/debounce.rst
@@ -0,0 +1,37 @@
+Debouncing a pin input
+======================
+
+A pin used as input from a switch or other mechanical device can have a lot
+of noise on it, rapidly changing from low to high when the switch is first
+pressed or released.  This noise can be eliminated using a capacitor (a
+debouncing circuit).  It can also be eliminated using a simple function that
+makes sure the value on the pin is stable.
+
+The following function does just this.  It gets the current value of the given
+pin, and then waits for the value to change.  The new pin value must be stable
+for a continuous 20ms for it to register the change.  You can adjust this time
+(to say 50ms) if you still have noise. ::
+
+    import pyb
+
+    def wait_pin_change(pin):
+        # wait for pin to change value
+        # it needs to be stable for a continuous 20ms
+        cur_value = pin.value()
+        active = 0
+        while active < 20:
+            if pin.value() != cur_value:
+                active += 1
+            else:
+                active = 0
+            pyb.delay(1)
+
+
+Use it something like this::
+
+    import pyb
+
+    pin_x1 = pyb.Pin('X1', pyb.Pin.IN, pyb.Pin.PULL_DOWN)
+    while True:
+        wait_pin_change(pin_x1)
+        pyb.LED(4).toggle()
diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst
index ed1137e1b..c134d0deb 100644
--- a/docs/tutorial/index.rst
+++ b/docs/tutorial/index.rst
@@ -43,4 +43,5 @@ Tips, tricks and useful things to know
    :maxdepth: 1
    :numbered:
 
+   debounce.rst
    pass_through.rst