Skip to content

Commit bc0bc76

Browse files
dpgeorgedpgeorge
committed
docs: Add debounce tutorial; order Pin methods; add pull resistor info.
1 parent 183ac71 commit bc0bc76

3 files changed

Lines changed: 69 additions & 28 deletions

File tree

‎docs/library/pyb.Pin.rst‎

Lines changed: 31 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -55,14 +55,17 @@ an ordinal pin number:
5555
You can set ``pyb.Pin.debug(True)`` to get some debug information about
5656
how a particular object gets mapped to a pin.
5757

58+
When a pin has the ``Pin.PULL_UP`` or ``Pin.PULL_DOWN`` pull-mode enabled,
59+
that pin has an effective 40k Ohm resistor pulling it to 3V3 or GND
60+
respectively (except pin Y5 which has 11k Ohm resistors).
5861

5962
Constructors
6063
------------
6164

6265
.. class:: pyb.Pin(id, ...)
6366

6467
Create a new Pin object associated with the id. If additional arguments are given,
65-
they are used to initialise the pin. See ``init``.
68+
they are used to initialise the pin. See :meth:`pin.init`.
6669

6770

6871
Class methods
@@ -88,24 +91,6 @@ Class methods
8891
Methods
8992
-------
9093

91-
.. method:: pin.__str__()
92-
93-
Return a string describing the pin object.
94-
95-
.. method:: pin.af()
96-
97-
Returns the currently configured alternate-function of the pin. The
98-
integer returned will match one of the allowed constants for the af
99-
argument to the init function.
100-
101-
.. method:: pin.gpio()
102-
103-
Returns the base address of the GPIO block associated with this pin.
104-
105-
.. method:: pin.high()
106-
107-
Set the pin to a high logic level.
108-
10994
.. method:: pin.init(mode, pull=Pin.PULL_NONE, af=-1)
11095

11196
Initialise the pin:
@@ -126,10 +111,37 @@ Methods
126111

127112
Returns: ``None``.
128113

114+
.. method:: pin.high()
115+
116+
Set the pin to a high logic level.
117+
129118
.. method:: pin.low()
130119

131120
Set the pin to a low logic level.
132121

122+
.. method:: pin.value([value])
123+
124+
Get or set the digital logic level of the pin:
125+
126+
- With no argument, return 0 or 1 depending on the logic level of the pin.
127+
- With ``value`` given, set the logic level of the pin. ``value`` can be
128+
anything that converts to a boolean. If it converts to ``True``, the pin
129+
is set high, otherwise it is set low.
130+
131+
.. method:: pin.__str__()
132+
133+
Return a string describing the pin object.
134+
135+
.. method:: pin.af()
136+
137+
Returns the currently configured alternate-function of the pin. The
138+
integer returned will match one of the allowed constants for the af
139+
argument to the init function.
140+
141+
.. method:: pin.gpio()
142+
143+
Returns the base address of the GPIO block associated with this pin.
144+
133145
.. method:: pin.mode()
134146

135147
Returns the currently configured mode of the pin. The integer returned
@@ -158,15 +170,6 @@ Methods
158170
will match one of the allowed constants for the pull argument to the init
159171
function.
160172

161-
.. method:: pin.value([value])
162-
163-
Get or set the digital logic level of the pin:
164-
165-
- With no argument, return 0 or 1 depending on the logic level of the pin.
166-
- With ``value`` given, set the logic level of the pin. ``value`` can be
167-
anything that converts to a boolean. If it converts to ``True``, the pin
168-
is set high, otherwise it is set low.
169-
170173

171174
Constants
172175
---------

‎docs/tutorial/debounce.rst‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
Debouncing a pin input
2+
======================
3+
4+
A pin used as input from a switch or other mechanical device can have a lot
5+
of noise on it, rapidly changing from low to high when the switch is first
6+
pressed or released. This noise can be eliminated using a capacitor (a
7+
debouncing circuit). It can also be eliminated using a simple function that
8+
makes sure the value on the pin is stable.
9+
10+
The following function does just this. It gets the current value of the given
11+
pin, and then waits for the value to change. The new pin value must be stable
12+
for a continuous 20ms for it to register the change. You can adjust this time
13+
(to say 50ms) if you still have noise. ::
14+
15+
import pyb
16+
17+
def wait_pin_change(pin):
18+
# wait for pin to change value
19+
# it needs to be stable for a continuous 20ms
20+
cur_value = pin.value()
21+
active = 0
22+
while active < 20:
23+
if pin.value() != cur_value:
24+
active += 1
25+
else:
26+
active = 0
27+
pyb.delay(1)
28+
29+
30+
Use it something like this::
31+
32+
import pyb
33+
34+
pin_x1 = pyb.Pin('X1', pyb.Pin.IN, pyb.Pin.PULL_DOWN)
35+
while True:
36+
wait_pin_change(pin_x1)
37+
pyb.LED(4).toggle()

‎docs/tutorial/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,4 +43,5 @@ Tips, tricks and useful things to know
4343
:maxdepth: 1
4444
:numbered:
4545

46+
debounce.rst
4647
pass_through.rst

0 commit comments

Comments
 (0)