The first part of interfacing with hardware is being able to manage digital inputs and outputs. With CircuitPython, it's super easy!

This example shows how to use both a digital input and output. You can use a switch input with pullup resistor (built in) to control a digital output - the built in red LED.

Copy and paste the code into code.py using your favorite editor, and save the file to run the demo.

"""CircuitPython Essentials Digital In Out example"""
import time
import board
from digitalio import DigitalInOut, Direction, Pull

# LED setup.
led = DigitalInOut(board.D13)
# For QT Py M0. QT Py M0 does not have a D13 LED, so you can connect an external LED instead.
# led = DigitalInOut(board.SCK)
led.direction = Direction.OUTPUT

# For Gemma M0, Trinket M0, Metro M0 Express, ItsyBitsy M0 Express, Itsy M4 Express, QT Py M0
switch = DigitalInOut(board.D2)
# switch = DigitalInOut(board.D5)  # For Feather M0 Express, Feather M4 Express
# switch = DigitalInOut(board.D7)  # For Circuit Playground Express
switch.direction = Direction.INPUT
switch.pull = Pull.UP

while True:
    # We could also do "led.value = not switch.value"!
    if switch.value:
        led.value = False
    else:
        led.value = True

    time.sleep(0.01)  # debounce delay

Note that we made the code a little less "Pythonic" than necessary. The if/else block could be replaced with a simple led.value = not switch.value but we wanted to make it super clear how to test the inputs. The interpreter will read the digital input when it evaluates switch.value.

For Gemma M0, Trinket M0, Metro M0 Express, Metro M4 Express, ItsyBitsy M0 Express, ItsyBitsy M4 Express, no changes to the initial example are needed.

Note: To "comment out" a line, put a # and a space before it. To "uncomment" a line, remove the # + space from the beginning of the line.

For Feather M0 Express and Feather M4 Express, comment out switch = DigitalInOut(board.D2) (and/or switch = DigitalInOut(board.D7) depending on what changes you already made), and uncomment switch = DigitalInOut(board.D5).

For Circuit Playground Express, you'll need to comment out switch = DigitalInOut(board.D2) (and/or switch = DigitalInOut(board.D5) depending on what changes you already made), and uncomment switch = DigitalInOut(board.D7).

QT Py M0 does not have a D13 LED built in. Therefore, you must connect an external LED for this example to work. See below for a wiring diagram illustrating how to connect an external LED to a QT Py M0.

For QT Py M0, you'll need to comment out led = DigitalInOut(board.D13) and uncomment led = DigitalInOut(board.SCK). The switch code remains the same.

To find the pin or pad suggested in the code, see the list below. For the boards that require wiring, wire up a switch (also known as a tactile switch, button or push-button), following the diagram for guidance. Press or slide the switch, and the onboard red LED will turn on and off.

Note that on the M0/SAMD based CircuitPython boards, at least, you can also have internal pulldowns with Pull.DOWN and if you want to turn off the pullup/pulldown just assign switch.pull = None.

Find the pins!

The list below shows each board, explains the location of the Digital pin suggested for use as input, and the location of the D13 LED.

Circuit Playground Express

 

We're going to use the switch, which is pin D7, and is located between the battery connector and the reset switch on the board. D13 is labeled D13 and is located next to the USB micro port.

 

To use D7, comment out the current pin setup line, and uncomment the line labeled for Circuit Playground Express. See the details above!

Trinket M0

 

D2 is connected to the blue wire, labeled "2", and located between "3V" and "1" on the board. D13 is labeled "13" and is located next to the USB micro port.

Gemma M0

 

D2 is an alligator-clip-friendly pad labeled both "D2" and "A1", shown connected to the blue wire, and is next to the USB micro port. D13 is located next to the "GND" label on the board, above the "On/Off" switch.

 

Use alligator clips to connect your switch to your Gemma M0!

QT Py M0

D2 is labeled A2, shown connected to the blue wire, and is near the USB port between A1 and A3.

There is no D13 LED on the QT Py M0. Therefore, you must connect an external LED for this example to work.

To wire up an external LED:

  • LED + to QT Py SCK
  • LED - to 470Ω resistor
  • 470Ω resistor to QT Py GND

The button and the LED share the same GND pin.

To use the external LED, comment out the current LED setup line, and uncomment the line labeled for QT Py M0. See the details above!

Feather M0 Express and Feather M4 Express

 

D5 is labeled "5" and connected to the blue wire on the board. D13 is labeled "#13" and is located next to the USB micro port.

 

To use D5, comment out the current pin setup line, and uncomment the line labeled for Feather M0 Express. See the details above!

ItsyBitsy M0 Express and ItsyBitsy M4 Express

 

D2 is labeled "2", located between the "MISO" and "EN" labels, and is connected to the blue wire on the board. D13 is located next to the reset button between the "3" and "4" labels on the board.

Metro M0 Express and Metro M4 Express

 

D2 is located near the top left corner, and is connected to the blue wire. D13 is labeled "L" and is located next to the USB micro port.

Read the Docs

For a more in-depth look at what digitalio can do, check out the DigitalInOut page in Read the Docs.

This guide was first published on Apr 18, 2018. It was last updated on Apr 18, 2018.

This page (CircuitPython Digital In & Out) was last updated on Jan 15, 2021.