Skip to content

Commit 3e5e4f9

Browse files
dpgeorgedpgeorge
committed
docs/library/machine.Pin: Update Pin docs to align with new HW API.
1 parent 52df2f8 commit 3e5e4f9

File tree

1 file changed

+192
-113
lines changed

1 file changed

+192
-113
lines changed

‎docs/library/machine.Pin.rst

Lines changed: 192 additions & 113 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,44 @@
33
class Pin -- control I/O pins
44
=============================
55

6-
A pin is the basic object to control I/O pins (also known as GPIO -
7-
general-purpose input/output). It has methods to set
8-
the mode of the pin (input, output, etc) and methods to get and set the
9-
digital logic level. For analog control of a pin, see the ADC class.
6+
A pin object is used to control I/O pins (also known as GPIO - general-purpose
7+
input/output). Pin objects are commonly associated with a physical pin that can
8+
drive an output voltage and read input voltages. The pin class has methods to set the mode of
9+
the pin (IN, OUT, etc) and methods to get and set the digital logic level.
10+
For analog control of a pin, see the :class:`ADC` class.
1011

11-
Usage Model:
12+
A pin object is constructed by using an identifier which unambiguously
13+
specifies a certain I/O pin. The allowed forms of the identifier and the
14+
physical pin that the identifier maps to are port-specific. Possibilities
15+
for the identifier are an integer, a string or a tuple with port and pin
16+
number.
17+
18+
Usage Model::
19+
20+
from machine import Pin
21+
22+
# create an output pin on pin #0
23+
p0 = Pin(0, Pin.OUT)
24+
25+
# set the value low then high
26+
p0.value(0)
27+
p0.value(1)
28+
29+
# create an input pin on pin #2, with a pull up resistor
30+
p2 = Pin(2, Pin.IN, Pin.PULL_UP)
31+
32+
# read and print the pin value
33+
print(p2.value())
34+
35+
# reconfigure pin #0 in input mode
36+
p0.mode(p0.IN)
37+
38+
# configure an irq callback
39+
p0.irq(lambda p:print(p))
1240

1341
.. only:: port_wipy
1442

15-
Board pins are identified by their string id::
43+
On the WiPy board the pins are identified by their string id::
1644

1745
from machine import Pin
1846
g = machine.Pin('GP9', mode=Pin.OUT, pull=None, drive=Pin.MED_POWER, alt=-1)
@@ -40,174 +68,224 @@ Usage Model:
4068
All pin objects go through the pin mapper to come up with one of the
4169
gpio pins.
4270

43-
.. only:: port_esp8266
71+
For the ``drive`` parameter the strengths are:
4472

45-
::
73+
- ``Pin.LOW_POWER`` - 2mA drive capability.
74+
- ``Pin.MED_POWER`` - 4mA drive capability.
75+
- ``Pin.HIGH_POWER`` - 6mA drive capability.
4676

47-
from machine import Pin
77+
For the ``alt`` parameter please refer to the pinout and alternate functions
78+
table at <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_
79+
for the specific alternate functions that each pin supports.
4880

49-
# create an output pin on GPIO0
50-
p0 = Pin(0, Pin.OUT)
51-
p0.value(0)
52-
p0.value(1)
81+
For interrupts, the ``priority`` can take values in the range 1-7. And the
82+
``wake`` parameter has the following properties:
5383

54-
# create an input pin on GPIO2
55-
p2 = Pin(2, Pin.IN, Pin.PULL_UP)
56-
print(p2.value())
84+
- If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board.
85+
- If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
86+
``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1
87+
of this pins can be enabled as a wake source at the same time, so, only
88+
the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect.
89+
- If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
90+
``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the
91+
6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time.
5792

5893
Constructors
5994
------------
6095

61-
.. class:: Pin(id, ...)
96+
.. class:: Pin(id, mode=-1, pull=-1, \*, value, drive, alt)
6297

63-
Create a new Pin object associated with the id. If additional arguments are given,
64-
they are used to initialise the pin. See :meth:`Pin.init`.
98+
Access the pin peripheral (GPIO pin) associated with the given ``id``. If
99+
additional arguments are given in the constructor then they are used to initialise
100+
the pin. Any settings that are not specified will remain in their previous state.
65101

66-
Methods
67-
-------
102+
The arguments are:
68103

69-
.. only:: port_wipy
104+
- ``id`` is mandatory and can be an arbitrary object. Among possible value
105+
types are: int (an internal Pin identifier), str (a Pin name), and tuple
106+
(pair of [port, pin]).
70107

71-
.. method:: Pin.init(mode, pull, \*, drive, alt)
72-
73-
Initialise the pin:
108+
- ``mode`` specifies the pin mode, which can be one of:
74109

75-
- ``mode`` can be one of:
110+
- ``Pin.IN`` - Pin is configured for input. If viewed as an output the pin
111+
is in high-impedance state.
76112

77-
- ``Pin.IN`` - input pin.
78-
- ``Pin.OUT`` - output pin in push-pull mode.
79-
- ``Pin.OPEN_DRAIN`` - output pin in open-drain mode.
80-
- ``Pin.ALT`` - pin mapped to an alternate function.
81-
- ``Pin.ALT_OPEN_DRAIN`` - pin mapped to an alternate function in open-drain mode.
113+
- ``Pin.OUT`` - Pin is configured for (normal) output.
82114

83-
- ``pull`` can be one of:
115+
- ``Pin.OPEN_DRAIN`` - Pin is configured for open-drain output. Open-drain
116+
output works in the following way: if the output value is set to 0 the pin
117+
is active at a low level; if the output value is 1 the pin is in a high-impedance
118+
state. Not all ports implement this mode, or some might only on certain pins.
84119

85-
- ``None`` - no pull up or down resistor.
86-
- ``Pin.PULL_UP`` - pull up resistor enabled.
87-
- ``Pin.PULL_DOWN`` - pull down resistor enabled.
120+
- ``Pin.ALT`` - Pin is configured to perform an alternative function, which is
121+
port specific. For a pin configured in such a way any other Pin methods
122+
(except :meth:`Pin.init`) are not applicable (calling them will lead to undefined,
123+
or a hardware-specific, result). Not all ports implement this mode.
88124

89-
- ``drive`` can be one of:
125+
- ``Pin.ALT_OPEN_DRAIN`` - The Same as ``Pin.ALT``, but the pin is configured as
126+
open-drain. Not all ports implement this mode.
90127

91-
- ``Pin.LOW_POWER`` - 2mA drive capability.
92-
- ``Pin.MED_POWER`` - 4mA drive capability.
93-
- ``Pin.HIGH_POWER`` - 6mA drive capability.
128+
- ``pull`` specifies if the pin has a (weak) pull resistor attached, and can be
129+
one of:
94130

95-
- ``alt`` is the number of the alternate function. Please refer to the
96-
`pinout and alternate functions table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_
97-
for the specific alternate functions that each pin supports.
131+
- ``None`` - No pull up or down resistor.
132+
- ``Pin.PULL_UP`` - Pull up resistor enabled.
133+
- ``Pin.PULL_DOWN`` - Pull down resistor enabled.
98134

99-
Returns: ``None``.
135+
- ``value`` is valid only for Pin.OUT and Pin.OPEN_DRAIN modes and specifies initial
136+
output pin value if given, otherwise the state of the pin peripheral remains
137+
unchanged.
100138

101-
.. method:: Pin.id()
139+
- ``drive`` specifies the output power of the pin and can be one of: ``Pin.LOW_POWER``,
140+
``Pin.MED_POWER`` or ``Pin.HIGH_POWER``. The actual current driving capabilities
141+
are port dependent. Not all ports implement this argument.
102142

103-
Get the pin id.
143+
- ``alt`` specifies an alternate function for the pin and the values it can take are
144+
port dependent. This argument is valid only for ``Pin.ALT`` and ``Pin.ALT_OPEN_DRAIN``
145+
modes. It may be used when a pin supports more than one alternate function. If only
146+
one pin alternate function is supported the this argument is not required. Not all
147+
ports implement this argument.
104148

105-
.. only:: port_esp8266
149+
As specified above, the Pin class allows to set an alternate function for a particular
150+
pin, but it does not specify any further operations on such a pin. Pins configured in
151+
alternate-function mode are usually not used as GPIO but are instead driven by other
152+
hardware peripherals. The only operation supported on such a pin is re-initialising,
153+
by calling the constructor or :meth:`Pin.init` method. If a pin that is configured in
154+
alternate-function mode is re-initialised with ``Pin.IN``, ``Pin.OUT``, or
155+
``Pin.OPEN_DRAIN``, the alternate function will be removed from the pin.
106156

107-
.. method:: Pin.init(mode, pull=None, \*, value)
157+
Methods
158+
-------
108159

109-
Initialise the pin:
160+
.. method:: Pin.init(mode=-1, pull=-1, \*, value, drive, alt)
110161

111-
- `mode` can be one of:
162+
Re-initialise the pin using the given parameters. Only those arguments that
163+
are specified will be set. The rest of the pin peripheral state will remain
164+
unchanged. See the constructor documentation for details of the arguments.
112165

113-
- ``Pin.IN`` - input pin.
114-
- ``Pin.OUT`` - output pin in push-pull mode.
166+
Returns ``None``.
115167

116-
- `pull` can be one of:
168+
.. method:: Pin.value([x])
117169

118-
- ``None`` - no pull up or down resistor.
119-
- ``Pin.PULL_UP`` - pull up resistor enabled.
170+
This method allows to set and get the value of the pin, depending on whether
171+
the argument ``x`` is supplied or not.
120172

121-
- if `value` is given then it is the output value to set the pin
122-
if it is in output mode.
173+
If the argument is omitted then this method gets the digital logic level of
174+
the pin, returning 0 or 1 corresponding to low and high voltage signals
175+
respectively. The behaviour of this method depends on the mode of the pin:
123176

124-
.. method:: Pin.value([value])
177+
- ``Pin.IN`` - The method returns the actual input value currently present
178+
on the pin.
179+
- ``Pin.OUT`` - The behaviour and return value of the method is undefined.
180+
- ``Pin.OPEN_DRAIN`` - If the pin is in state '0' then the behaviour and
181+
return value of the method is undefined. Otherwise, if the pin is in
182+
state '1', the method returns the actual input value currently present
183+
on the pin.
125184

126-
Get or set the digital logic level of the pin:
185+
If the argument is supplied then this method sets the digital logic level of
186+
the pin. The argument ``x`` can be anything that converts to a boolean.
187+
If it converts to ``True``, the pin is set to state '1', otherwise it is set
188+
to state '0'. The behaviour of this method depends on the mode of the pin:
127189

128-
- With no argument, return 0 or 1 depending on the logic level of the pin.
129-
- With ``value`` given, set the logic level of the pin. ``value`` can be
130-
anything that converts to a boolean. If it converts to ``True``, the pin
131-
is set high, otherwise it is set low.
190+
- ``Pin.IN`` - The value is stored in the output buffer for the pin. The
191+
pin state does not change, it remains in the high-impedance state. The
192+
stored value will become active on the pin as soon as it is changed to
193+
``Pin.OUT`` or ``Pin.OPEN_DRAIN`` mode.
194+
- ``Pin.OUT`` - The output buffer is set to the given value immediately.
195+
- ``Pin.OPEN_DRAIN`` - If the value is '0' the pin is set to a low voltage
196+
state. Otherwise the pin is set to high-impedance state.
132197

133-
.. method:: Pin.__call__([value])
198+
When setting the value this method returns ``None``.
134199

135-
Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin.
136-
See :func:`Pin.value` for more details.
200+
.. method:: Pin.out_value()
137201

138-
.. method:: Pin.alt_list()
202+
Return the value stored in the output buffer of a pin, regardless of its mode.
139203

140-
Returns a list of the alternate functions supported by the pin. List items are
141-
a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)``
204+
Not all ports implement this method.
142205

143-
Availability: WiPy.
206+
.. method:: Pin.__call__([x])
144207

145-
.. only:: port_wipy
208+
Pin objects are callable. The call method provides a (fast) shortcut to set
209+
and get the value of the pin. It is equivalent to Pin.value([x]).
210+
See :meth:`Pin.value` for more details.
211+
212+
.. method:: Pin.toggle()
213+
214+
Toggle the output value of the pin. Equivalent to ``pin.value(not pin.out_value())``.
215+
Returns ``None``.
216+
217+
Not all ports implement this method.
146218

147-
.. method:: Pin.toggle()
219+
Availability: WiPy.
148220

149-
Toggle the value of the pin.
221+
.. method:: Pin.id()
150222

151-
.. method:: Pin.mode([mode])
223+
Get the pin identifier. This may return the ``id`` as specified in the
224+
constructor. Or it may return a canonical software-specific pin id.
152225

153-
Get or set the pin mode.
226+
.. method:: Pin.mode([mode])
154227

155-
.. method:: Pin.pull([pull])
228+
Get or set the pin mode.
229+
See the constructor documentation for details of the ``mode`` argument.
156230

157-
Get or set the pin pull.
231+
.. method:: Pin.pull([pull])
158232

159-
.. method:: Pin.drive([drive])
233+
Get or set the pin pull state.
234+
See the constructor documentation for details of the ``pull`` argument.
160235

161-
Get or set the pin drive strength.
236+
.. method:: Pin.drive([drive])
162237

163-
.. method:: Pin.irq(\*, trigger, priority=1, handler=None, wake=None)
238+
Get or set the pin drive strength.
239+
See the constructor documentation for details of the ``drive`` argument.
164240

165-
Create a callback to be triggered when the input level at the pin changes.
241+
Not all ports implement this method.
166242

167-
- ``trigger`` configures the pin level which can generate an interrupt. Possible values are:
243+
Availability: WiPy.
168244

169-
- ``Pin.IRQ_FALLING`` interrupt on falling edge.
170-
- ``Pin.IRQ_RISING`` interrupt on rising edge.
171-
- ``Pin.IRQ_LOW_LEVEL`` interrupt on low level.
172-
- ``Pin.IRQ_HIGH_LEVEL`` interrupt on high level.
173-
174-
The values can be *ORed* together, for instance mode=Pin.IRQ_FALLING | Pin.IRQ_RISING
245+
.. method:: Pin.irq(handler=None, trigger=(Pin.IRQ_FALLING | Pin.IRQ_RISING), \*, priority=1, wake=None)
175246

176-
- ``priority`` level of the interrupt. Can take values in the range 1-7.
177-
Higher values represent higher priorities.
178-
- ``handler`` is an optional function to be called when new characters arrive.
179-
- ``wakes`` selects the power mode in which this interrupt can wake up the
180-
board. Please note:
247+
Configure an interrupt handler to be called when the trigger source of the
248+
pin is active. If the pin mode is ``Pin.IN`` then the trigger source is
249+
the external value on the pin. If the pin mode is ``Pin.OUT`` then the
250+
trigger source is the output buffer of the pin. Otherwise, if the pin mode
251+
is ``Pin.OPEN_DRAIN`` then the trigger source is the output buffer for
252+
state '0' and the external pin value for state '1'.
181253

182-
- If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board.
183-
- If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
184-
``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1
185-
of this pins can be enabled as a wake source at the same time, so, only
186-
the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect.
187-
- If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
188-
``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the
189-
6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time.
190-
- Values can be ORed to make a pin generate interrupts in more than one power
191-
mode.
254+
The arguments are:
192255

193-
Returns a callback object.
256+
- ``handler`` is an optional function to be called when the interrupt
257+
triggers.
194258

195-
.. only:: port_esp8266
259+
- ``trigger`` configures the event which can generate an interrupt.
260+
Possible values are:
196261

197-
.. method:: Pin.irq(\*, trigger, handler=None)
262+
- ``Pin.IRQ_FALLING`` interrupt on falling edge.
263+
- ``Pin.IRQ_RISING`` interrupt on rising edge.
264+
- ``Pin.IRQ_LOW_LEVEL`` interrupt on low level.
265+
- ``Pin.IRQ_HIGH_LEVEL`` interrupt on high level.
198266

199-
Create a callback to be triggered when the input level at the pin changes.
267+
These values can be OR'ed together to trigger on multiple events.
200268

201-
- ``trigger`` configures the pin level which can generate an interrupt. Possible values are:
269+
- ``priority`` sets the priority level of the interrupt. The values it
270+
can take are port-specific, but higher values always represent higher
271+
priorities.
272+
273+
- ``wake`` selects the power mode in which this interrupt can wake up the
274+
system. It can be ``machine.IDLE``, ``machine.SLEEP`` or ``machine.DEEPSLEEP``.
275+
These values can also be OR'ed together to make a pin generate interrupts in
276+
more than one power mode.
277+
278+
This method returns a callback object.
279+
280+
.. only:: port_wipy
202281

203-
- ``Pin.IRQ_FALLING`` interrupt on falling edge.
204-
- ``Pin.IRQ_RISING`` interrupt on rising edge.
282+
.. method:: Pin.alt_list()
205283

206-
The values can be OR'ed together to trigger on multiple events.
284+
Returns a list of the alternate functions supported by the pin. List items are
285+
a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)``
207286

208-
- ``handler`` is an optional function to be called when the interrupt triggers.
287+
Availability: WiPy.
209288

210-
Returns a callback object.
211289

212290
Attributes
213291
----------
@@ -239,7 +317,8 @@ not all constants are available on all ports.
239317
.. data:: Pin.PULL_UP
240318
Pin.PULL_DOWN
241319

242-
Selects the whether there is a pull up/down resistor.
320+
Selects whether there is a pull up/down resistor. Use the value
321+
``None`` for no pull.
243322

244323
.. data:: Pin.LOW_POWER
245324
Pin.MED_POWER

0 commit comments

Comments
 (0)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy