8000 docs/library/machine.Pin: Update Pin docs to align with new HW API. · matthewelse/micropython@3e5e4f9 · GitHub
[go: up one dir, main page]
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
90
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 6D40 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``,
+
``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 10000 +
- ``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)
0