What's in this document
Firmware & API Reference > Pycom Modules > machine > Pin

Pin

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.

Quick Usage Example


from machine import Pin

# initialize `P9` in gpio mode and make it an output
p_out = Pin('P9', mode=Pin.OUT)
p_out.value(1)
p_out.value(0)
p_out.toggle()
p_out(True)

# make `P10` an input with the pull-up enabled
p_in = Pin('P10', mode=Pin.IN, pull=Pin.PULL_UP)
p_in() # get value, 0 or 1

Constructors

class machine.Pin(id, [mode=Pin.OUT, pull=None, alt])

Create a new Pin object associated with the string id. If additional arguments are given, they are used to initialise the pin. See pin.init()


from machine import Pin
p = Pin('P10', mode=Pin.OUT, pull=None, alt=-1)

Methods

pin.init(mode, pull, * , alt)

Initialise the pin:

  • mode can be one of:
    • Pin.IN - input pin.
    • Pin.OUT - output pin in push-pull mode.
    • Pin.OPEN_DRAIN - input or output pin 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 resistor enabled.
  • *
    • Pin value: 0 or 1
  • alt is the id of the alternate function.

Returns: None.

pin.id()

Get the pin id.

pin.value([value])

Get or set the digital logic level of the pin. This only works in Pin.OUT mode. Values can be:

  • True or 1: High
  • Falseor 0: Low

pin([value])

Pin objects are callable. The call method provides a (fast) shortcut to set and get the value of the pin.

Example:


from machine import Pin
pin = Pin('P12', mode=Pin.IN, pull=Pin.PULL_UP)
pin()   # fast method to get the value

See pin.value() for more details.

pin.toggle()

Toggle the value of the pin.

pin.mode([mode])

Get or set the pin mode. Modes can be:

  • Pin.IN
  • Pin.OUT
  • Pin.OPEN_DRAIN

pin.pull([pull])

Get or set the pin pull. Pull can be:

  • Pin.PULL_UP
  • Pin.PULL_DOWN
  • None

pin.hold([hold])

Get or set the pin hold. This functionality can be used to hold a pin’s state after deepsleep, machine.reset() or a watchdog timer reset. Passing True will hold the current value of the pin, False will release the hold state. When a pin is in hold state, its value cannot be changed by using Pin.value() or Pin.toggle(), until the hold is released. Only pins in the RTC power domain can retain their value through deep sleep or reset. These are: P2, P3, P4, P6, P8, P9, P10, P13, P14, P15, P16, P17, P18, P19, P20, P21, P22, P23

You can use the following example:

from machine import Pin
import machine
p3 = Pin('P3', mode=Pin.OUT)
p3.value(1) #can also be p3.value(0)
p3.hold(True) #hold the pin high
machine.reset()
# instead, you can use:
# machine.deepsleep(10000)

# P3 will still be high here

A few things to keep in mind when using the pin hold functionality:

  • This feature only preserves the pin value:
    • During a (deep)sleep
    • After waking up from deepsleep
    • After machine.reset()
    • After a WDT reset
  • The hold state itself is not preserved in Micropython after the above mentioned resets. This means that pin.hold() will return False after such reset, even though the pin is actually still held in hardware.
  • pin.hold() does not return the pin’s value. You can hold a pin high or low.
  • Applying a hard-reset, by for example pressing the reset button, will reset the pin value and release the hold.

pin.callback(trigger, [handler=None, arg=None])

Set a callback to be triggered when the input level at the pin changes.

  • trigger is the type of event that triggers the callback. 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 OR-ed together, for instance trigger=Pin.IRQ_FALLING | Pin.IRQ_RISING

  • handler is the function to be called when the event happens. This function will receive one argument. Set handler to None to disable it.
  • arg is an optional argument to pass to the callback. If left empty or set to None, the function will receive the Pin object that triggered it.

Example:


from machine import Pin

def pin_handler(arg):
    print("got an interrupt in pin %s" % (arg.id()))

p_in = Pin('P10', mode=Pin.IN, pull=Pin.PULL_UP)
p_in.callback(Pin.IRQ_FALLING | Pin.IRQ_RISING, pin_handler)

For more information on how Pycom’s products handle interrupts, see here.

Attributes

class pin.exp_board

Contains all Pin objects supported by the expansion board. Examples:


Pin.exp_board.G16
led = Pin(Pin.exp_board.G16, mode=Pin.OUT)
Pin.exp_board.G16.id()

class pin.module

Contains all Pin objects supported by the module. Examples:


Pin.module.P9
led = Pin(Pin.module.P9, mode=Pin.OUT)
Pin.module.P9.id()

Constants

The following constants are used to configure the pin objects. Note that not all constants are available on all ports.

  • Selects the pin mode: Pin.IN, Pin.OUT, Pin.OPEN_DRAIN
  • Enables the pull up or pull down resistor: Pin.PULL_UP, Pin.PULL_DOWN

 

Previous
Next