Using the Pyboard's Digital Pins with 'machine.Pin'

Contents

Introduction

The STM32F405RGT6 microcontroller on the Pyboard V1.1 board has six I/O ports labelled Ports A, B, C, D, E and H. Port H is only a 2-bit port while the other five ports are 16-bit wide. With the limitations of the 64-pin package there are 51 of these port bits exposed as useable external pins on the chip.

In order to keep the Pyboard to a manageable size the designers chose to provide 34 digital pins on the board. However not all of these pins are readily available for I/O:

  • Anytime use: X1..X12, X19..X22, Y1..Y12
  • Only if really needed: X17, X18
  • Avoid: P2, P3, P4, P5

Pin X17 is pulled to GND via a 4.7kΩ resistor if the onboard user switch USR is pressed. Use pyb.Switch class to manage this switch.

Pin X18 has serious current limitations. It shouldn't be used to drive a load such as an LED.

Pins P2, P3, P4 and P5 are connected to the onboard 4 x LEDs. Don't use these pins for general I/O. Use the pyb.LED class to control these onboard LEDs.

Here is a link to the Pyboard V1.1 pinout. We print these pinouts in colour, laminate them and keep them on the workbench for easy reference.

The 'machine.Pin' Class

The GPIO pins on the Pyboard may be controlled by the machine.Pin class. This article will cover the most used options but for a complete discussion the official MicroPython documentation should be read.

The alternative pyb.Pin class is specific to the Pyboard. For further details see this article, Using the Pyboard's Digital Pins with 'pyb.Pin'. It's simply a personal choice which class to use for pin control.

Creating a Pin object

A pin object is created and configured for the type of use required:


Syntax:
<pin_variable> = machine.Pin(id,
                             mode=-1,
                             pull=-1, *,
                             value=None)

Example
# This example defines pin X1 for digital input.
my_pin = machine.Pin('X1', machine.Pin.IN)
id

The pin name uses the Pyboard GPIO pin naming scheme with the Pyboard pin name as a string e.g. 'X1', 'Y1'.

mode

The mode   options are:

  • machine.Pin.IN : Configure the pin for input.
  • machine.Pin.OUT : configure the pin for output, with push-pull control[1].
  • machine.Pin.OPEN_DRAIN : configure the pin for output, with open-drain control[2].
  • machine.Pin.ANALOG : configure the pin for analog. The pin must be capable of analog operation (see pinout). This is discussed in Using the Pyboard's Analog Pins for ADC and Using the Pyboard's Analog Pins for DAC.
pull

The pull options are:

  • machine.Pin.NONE : no pull-up or pull-down resistors.
  • machine.Pin.PULL_UP : enable the pull-up resistor[3].
  • machine.Pin.PULL_DOWN : enable the pull-down resistor[3].
value

The value option if not None will set the pin output value before the pin is enabled. Valid only for Pin.OUT and Pin.OPEN_DRAIN modes.


Examples:
from machine import Pin

# Pin Y11 configured for output
# with push-pull control.
# Initial value of High i.e. 1
pin1 = Pin('Y11', Pin.OUT, value=1)

# Pin Y1 configured for input with
# the pull-up resistor enabled.
pin2 = Pin('Y1', Pin.IN, pull=Pin.PULL_UP)

# Pin X1 configured for analog.
pin3 = Pin('X1', Pin.ANALOG)

# Get the pin configurations
print(pin1)
print(pin2)
print(pin3)

Output:
Pin(Pin.cpu.B0, mode=Pin.OUT)
Pin(Pin.cpu.C6, mode=Pin.IN, pull=Pin.PULL_UP)
Pin(Pin.cpu.A0, mode=Pin.ANALOG)

Reading & Writing a Pin Value

Digital pins can have one of two logic values: 1 (High) or 0 (Low). Reading or writing a value to a digital pin is done with the Pin.value() method.

The methods Pin.on() and Pin.off() sets pin to 1 or to 0 respectively.


Syntax:
Pin.value([value])

If no argument is passed to the method then
a 0 or 1 depending on the logic level of the
pin is returned.

If an argument value is given then that is
used to set the logic level of the pin.
It must be 0 or 1.

Pin.on()
Sets the value of pin configured for output to 1.

Pin.off()
Sets the value of pin configured for output to 0.

Example
from machine import Pin

# Set pin X12 to logic 1 (High)
pin1 = Pin('X12', Pin.OUT)
pin1.value(1)
# Set pin X12 to logic 0 (Low)
pin1.off()

# Read logic level of pin Y1
my_pin = Pin('Y1', Pin.IN)
print(my_pin.value())

Notes: