256 lines
7.8 KiB
ReStructuredText
256 lines
7.8 KiB
ReStructuredText
.. currentmodule:: machine
|
|
|
|
class Pin -- control I/O pins
|
|
=============================
|
|
|
|
A pin is the basic object to control I/O pins (also known as GPIO -
|
|
general-purpose input/output). It has methods to set
|
|
the mode of the pin (input, output, etc) and methods to get and set the
|
|
digital logic level. For analog control of a pin, see the ADC class.
|
|
|
|
Usage Model:
|
|
|
|
.. only:: port_wipy
|
|
|
|
Board pins are identified by their string id::
|
|
|
|
from machine import Pin
|
|
g = machine.Pin('GP9', mode=Pin.OUT, pull=None, drive=Pin.MED_POWER, alt=-1)
|
|
|
|
You can also configure the Pin to generate interrupts. For instance::
|
|
|
|
from machine import Pin
|
|
|
|
def pincb(pin):
|
|
print(pin.id())
|
|
|
|
pin_int = Pin('GP10', mode=Pin.IN, pull=Pin.PULL_DOWN)
|
|
pin_int.irq(trigger=Pin.IRQ_RISING, handler=pincb)
|
|
# the callback can be triggered manually
|
|
pin_int.irq()()
|
|
# to disable the callback
|
|
pin_int.irq().disable()
|
|
|
|
Now every time a falling edge is seen on the gpio pin, the callback will be
|
|
executed. Caution: mechanical push buttons have "bounce" and pushing or
|
|
releasing a switch will often generate multiple edges.
|
|
See: http://www.eng.utah.edu/~cs5780/debouncing.pdf for a detailed
|
|
explanation, along with various techniques for debouncing.
|
|
|
|
All pin objects go through the pin mapper to come up with one of the
|
|
gpio pins.
|
|
|
|
.. only:: port_esp8266
|
|
|
|
::
|
|
|
|
from machine import Pin
|
|
|
|
# create an output pin on GPIO0
|
|
p0 = Pin(0, Pin.OUT)
|
|
p0.value(0)
|
|
p0.value(1)
|
|
|
|
# create an input pin on GPIO2
|
|
p2 = Pin(2, Pin.IN, Pin.PULL_UP)
|
|
print(p2.value())
|
|
|
|
Constructors
|
|
------------
|
|
|
|
.. class:: Pin(id, ...)
|
|
|
|
Create a new Pin object associated with the id. If additional arguments are given,
|
|
they are used to initialise the pin. See :meth:`Pin.init`.
|
|
|
|
Methods
|
|
-------
|
|
|
|
.. only:: port_wipy
|
|
|
|
.. method:: Pin.init(mode, pull, \*, drive, alt)
|
|
|
|
Initialise the pin:
|
|
|
|
- ``mode`` can be one of:
|
|
|
|
- ``Pin.IN`` - input pin.
|
|
- ``Pin.OUT`` - output pin in push-pull mode.
|
|
- ``Pin.OPEN_DRAIN`` - output pin in open-drain mode.
|
|
- ``Pin.ALT`` - pin mapped to an alternate function.
|
|
- ``Pin.ALT_OPEN_DRAIN`` - pin mapped to an alternate function in open-drain mode.
|
|
|
|
- ``pull`` can be one of:
|
|
|
|
- ``None`` - no pull up or down resistor.
|
|
- ``Pin.PULL_UP`` - pull up resistor enabled.
|
|
- ``Pin.PULL_DOWN`` - pull down resitor enabled.
|
|
|
|
- ``drive`` can be one of:
|
|
|
|
- ``Pin.LOW_POWER`` - 2mA drive capability.
|
|
- ``Pin.MED_POWER`` - 4mA drive capability.
|
|
- ``Pin.HIGH_POWER`` - 6mA drive capability.
|
|
|
|
- ``alt`` is the number of the alternate function. Please refer to the
|
|
`pinout and alternate functions table. <https://raw.githubusercontent.com/wipy/wipy/master/docs/PinOUT.png>`_
|
|
for the specific alternate functions that each pin supports.
|
|
|
|
Returns: ``None``.
|
|
|
|
.. method:: Pin.id()
|
|
|
|
Get the pin id.
|
|
|
|
.. only:: port_esp8266
|
|
|
|
.. method:: Pin.init(mode, pull=None, \*, value)
|
|
|
|
Initialise the pin:
|
|
|
|
- `mode` can be one of:
|
|
|
|
- ``Pin.IN`` - input pin.
|
|
- ``Pin.OUT`` - output pin in push-pull mode.
|
|
|
|
- `pull` can be one of:
|
|
|
|
- ``None`` - no pull up or down resistor.
|
|
- ``Pin.PULL_UP`` - pull up resistor enabled.
|
|
|
|
- if `value` is given then it is the output value to set the pin
|
|
if it is in output mode.
|
|
|
|
.. 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.__call__([value])
|
|
|
|
Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin.
|
|
See :func:`Pin.value` for more details.
|
|
|
|
.. method:: Pin.alt_list()
|
|
|
|
Returns a list of the alternate functions supported by the pin. List items are
|
|
a tuple of the form: ``('ALT_FUN_NAME', ALT_FUN_INDEX)``
|
|
|
|
Availability: WiPy.
|
|
|
|
.. only:: port_wipy
|
|
|
|
.. method:: Pin.toggle()
|
|
|
|
Toggle the value of the pin.
|
|
|
|
.. method:: Pin.mode([mode])
|
|
|
|
Get or set the pin mode.
|
|
|
|
.. method:: Pin.pull([pull])
|
|
|
|
Get or set the pin pull.
|
|
|
|
.. method:: Pin.drive([drive])
|
|
|
|
Get or set the pin drive strength.
|
|
|
|
.. method:: Pin.irq(\*, trigger, priority=1, handler=None, wake=None)
|
|
|
|
Create a callback to be triggered when the input level at the pin changes.
|
|
|
|
- ``trigger`` configures the pin level which can generate an interrupt. Possible values are:
|
|
|
|
- ``Pin.IRQ_FALLING`` interrupt on falling edge.
|
|
- ``Pin.IRQ_RISING`` interrupt on rising edge.
|
|
- ``Pin.IRQ_LOW_LEVEL`` interrupt on low level.
|
|
- ``Pin.IRQ_HIGH_LEVEL`` interrupt on high level.
|
|
|
|
The values can be *ORed* together, for instance mode=Pin.IRQ_FALLING | Pin.IRQ_RISING
|
|
|
|
- ``priority`` level of the interrupt. Can take values in the range 1-7.
|
|
Higher values represent higher priorities.
|
|
- ``handler`` is an optional function to be called when new characters arrive.
|
|
- ``wakes`` selects the power mode in which this interrupt can wake up the
|
|
board. Please note:
|
|
|
|
- If ``wake_from=machine.Sleep.ACTIVE`` any pin can wake the board.
|
|
- If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
|
|
``GP11``, GP17`` or ``GP24`` can wake the board. Note that only 1
|
|
of this pins can be enabled as a wake source at the same time, so, only
|
|
the last enabled pin as a ``machine.Sleep.SUSPENDED`` wake source will have effect.
|
|
- If ``wake_from=machine.Sleep.SUSPENDED`` pins ``GP2``, ``GP4``, ``GP10``,
|
|
``GP11``, ``GP17`` and ``GP24`` can wake the board. In this case all of the
|
|
6 pins can be enabled as a ``machine.Sleep.HIBERNATE`` wake source at the same time.
|
|
- Values can be ORed to make a pin generate interrupts in more than one power
|
|
mode.
|
|
|
|
Returns a callback object.
|
|
|
|
.. only:: port_esp8266
|
|
|
|
.. method:: Pin.irq(\*, trigger, handler=None)
|
|
|
|
Create a callback to be triggered when the input level at the pin changes.
|
|
|
|
- ``trigger`` configures the pin level which can generate an interrupt. Possible values are:
|
|
|
|
- ``Pin.IRQ_FALLING`` interrupt on falling edge.
|
|
- ``Pin.IRQ_RISING`` interrupt on rising edge.
|
|
|
|
The values can be OR'ed together to trigger on multiple events.
|
|
|
|
- ``handler`` is an optional function to be called when the interrupt triggers.
|
|
|
|
Returns a callback object.
|
|
|
|
Attributes
|
|
----------
|
|
|
|
.. class:: Pin.board
|
|
|
|
Contains all ``Pin`` objects supported by the board. Examples::
|
|
|
|
Pin.board.GP25
|
|
led = Pin(Pin.board.GP25, mode=Pin.OUT)
|
|
Pin.board.GP2.alt_list()
|
|
|
|
Availability: WiPy.
|
|
|
|
Constants
|
|
---------
|
|
|
|
The following constants are used to configure the pin objects. Note that
|
|
not all constants are available on all ports.
|
|
|
|
.. data:: Pin.IN
|
|
Pin.OUT
|
|
Pin.OPEN_DRAIN
|
|
Pin.ALT
|
|
Pin.ALT_OPEN_DRAIN
|
|
|
|
Selects the pin mode.
|
|
|
|
.. data:: Pin.PULL_UP
|
|
Pin.PULL_DOWN
|
|
|
|
Selects the whether there is a pull up/down resistor.
|
|
|
|
.. data:: Pin.LOW_POWER
|
|
Pin.MED_POWER
|
|
Pin.HIGH_POWER
|
|
|
|
Selects the pin drive strength.
|
|
|
|
.. data:: Pin.IRQ_FALLING
|
|
Pin.IRQ_RISING
|
|
Pin.IRQ_LOW_LEVEL
|
|
Pin.IRQ_HIGH_LEVEL
|
|
|
|
Selects the IRQ trigger type.
|