To get you started with how to program your Pico in CircuitPython, especially for those who may have started out with the official MicroPython setup, we've 'ported' the Getting Started with MicroPython on Pico book examples to CircuitPython. The book is awesome, please download/purchase it to support Raspberry Pi Press!

Printing "Hello, World!" is the traditional first program to write in any language. In CircuitPython, the Hello, World! equivalent is blinking an LED. This is easy to do with your Raspberry Pi Pico board and CircuitPython.

The Built-In LED

Your Pico board has a built in LED, labeled "LED", located to the left of the USB port at the top of the board. Like any other LED, it turns on when it is powered, and is otherwise off. The LED is connected to pin GP25. GP25 is dedicated to the LED, and therefore is not available as a pin along the edge of your Pico board. In CircuitPython, you can access this LED using board.LED.

Save the following as code.py on your CIRCUITPY drive.

"""Example for Pico. Turns on the built-in LED."""
import board
import digitalio

led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = True

So far, none of the examples have required importing anything. Most, if not all, hardware programming requires you to import built-in modules or libraries. CircuitPython libraries are not included in CircuitPython itself and require you to copy files or folders to the lib folder on your CIRCUITPY drive. The built-in modules, however, are included, and do not require any external files or folders. To see a list of available built-in modules for your Pico board, you can enter the REPL and type the following at the >>> prompt:

help("modules")

This example requires two modules: board and digitalio.

The first step to hardware programming is identifying the location of the hardware board. The board module contains all of the pin names of the pins available on your Pico board. These are not the pin names on the chip itself! They are the names of the pins provided to CircuitPython for use in your code.

One of the most basic parts of interfacing with hardware is managing digital inputs and outputs. This is where digitalio comes in. The digitalio module allows you to digitally control IO pins, as well as set the direction and pull of the pin.

So, you import both board and digitalio at the beginning of the file:

import board
import digitalio

Next, you set up the LED. You assign the variable led to the digitalio.DigitalInOut object. This will allow you to manipulate the LED object using the led variable, instead of having to type out the entire object every time you want to use it. The DigitalInOut object takes one argument - the pin object using the board module, board.LED. Then you set the pin direction to OUTPUT to tell your Pico board that it should be used as an output (versus an input).

led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT

This setup code tells your Pico board how to talk to the LED. The next step is to tell it to turn on. To do this, you'll need to start a while True: loop. Within the loop, set the led value to True with led.value = True. Remember, for code to be "in" a loop, it must be indented under the while True:.

while True:
    led.value = True

The green LED turns on!

It's worth noting, if you simply set the led value to True without a loop, it would flash quickly once, and then remain turned off. This is due to the way CircuitPython works, with regard to what happens when your program ends. When your code finishes running, CircuitPython resets your Pico board to prepare it for the next run of code. That means the set up you did earlier no longer applies, and the LED does not remain turned on. To that end, most CircuitPython programs involve some kind of loop, infinite or otherwise.

You'll notice the LED stays on. This is because you have not told it to turn off. To turn the LED off, you set led.value = False. Try adding that line of code to the end of your current code.py file.

"""Example for Pico. Turns the built-in LED on and off with no delay."""
import board
import digitalio

led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = True
    led.value = False

The LED still doesn't appear to turn off. It is turning off! Your Pico board processes code so quickly that, to the naked eye, the LED does not appear to be turning off. However, it is rapidly flashing on and off, faster than you are able to process. The solution is to add a delay. For that, you need to import a new module called time. Then, you add a time.sleep() after turning the LED on, and after turning the LED off.

Update your code.py to the following and save.

"""Example for Pico. Blinks the built-in LED."""
import time
import board
import digitalio

led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = True
    time.sleep(0.5)
    led.value = False
    time.sleep(0.5)

The LED begins blinking!

Including a sleep() in your code tells the program to pause for the given number of seconds. In this case, it pauses for half of one second, or 0.5 seconds. Try changing 0.5 to 1 and see what happens! The two sleep() times do not have to be the same - try making them different to see the results.

There is a more concise but less clear way to do the same thing. Consider the following. Update your code.py to the following and save.

"""Example for Pico. Blinks the built-in LED."""
import time
import board
import digitalio

led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = not led.value
    time.sleep(0.5)

The LED blinks!

Remember that when the LED value is True, it is on, and when it is False, it is off. In this example, the not is a logic operator that reverses the result. So, it turns a True into a False, and a False into a True. With the 0.5 second sleep(), this causes the LED value to cycle between True and False every 0.5 seconds. It does exactly the same thing as explicitly setting the value, but saves a couple of lines of code!

An External LED

The first step to controlling an external LED is connecting one to your Pico board. For this example, you'll need your Pico board, a breadboard, male-to-male jumper wires, a resistor, and an LED. A 220Ω-1.0KΩ resistor will work; a 220Ω resistor is shown in the diagram.

This is a cute half-size breadboard, good for small projects. It's 2.2" x 3.4" (5.5 cm x 8.5 cm) with a standard double-strip in the middle and two power rails on both...
$5.00
In Stock
Handy for making wire harnesses or jumpering between headers on PCB's. These premium jumper wires are 3" (75mm) long and come in a 'strip' of 20 (2 pieces of each of ten rainbow...
$1.95
In Stock
Need some indicators? We are big fans of these diffused LEDs. They are fairly bright, so they can be seen in daytime, and from any angle. They go easily into a breadboard and will add...
$4.95
In Stock
ΩMG! You're not going to be able to resist these handy resistor packs! Well, axially, they do all of the resisting for you!This is a 25 Pack of...
$0.75
In Stock

Wire up the LED to your Pico board as shown below.

External LEDs must have a current-limiting resistor between the LED and your board. Without it, you can damage both the LED and your board!
  • Board GND to breadboard ground rail (using a jumper wire)
  • Board GP14 to 220Ω resistor
  • LED+ to 220Ω resistor
  • LED- to breadboard ground rail (using a jumper wire)

Now that you've wired up an LED to your Pico board, it's time to light it up. The code is almost exactly the same as the code used to turn on the built-in LED. The only change required is to update the pin provided in setup to the pin to which you connected your external LED. You connected the external LED to GP14. So, take the blink code from above, and change the pin to match the new pin assignment.

Update your code.py to the following and save.

"""
LED example for Pico. Blinks external LED on and off.

REQUIRED HARDWARE:
* LED on pin GP14.
"""
import time
import board
import digitalio

led = digitalio.DigitalInOut(board.GP14)
led.direction = digitalio.Direction.OUTPUT

while True:
    led.value = True
    time.sleep(0.5)
    led.value = False
    time.sleep(0.5)

The external LED begins blinking! That's all it takes to basically control an external LED.

Now it's time to take a look at using hardware as an input (instead of an output like an LED).

Using a Button as an Input

The IO in GPIO stands for input/output, which is to say that all GPIO pins can be used as both inputs and outputs. For this example, you'll need your current wiring setup, a button switch, and male-to-male jumper wires. The first step is connecting the button to your Pico board.

Wire up the button to your current setup as shown below. The button used in the diagram is a four-legged button. The legs are connected in pairs, so the simplest way to ensure you're wired up properly is to use the opposite legs. There are buttons that have only two legs, and in that case, you would still connect to the opposite legs.

Little clicky switches are standard input "buttons" on electronic projects. These work best in a PCB but
$2.50
In Stock
  • Board 3V3 to breadboard power rail (using jumper wire)
  • Board GP13 to leg of button (using jumper wire)
  • Opposite leg of button to breadboard power rail (using jumper wire)

Now that you have wired up your button, it's time to read status from it. Setup will look a lot like setting up the LED, with a couple of important differences.

Update your code.py to the following and save.

"""
Button example for Pico. Prints button pressed state to serial console.

REQUIRED HARDWARE:
* Button switch on pin GP13.
"""
import time
import board
import digitalio

button = digitalio.DigitalInOut(board.GP13)
button.switch_to_input(pull=digitalio.Pull.DOWN)

while True:
    print(button.value)
    time.sleep(0.5)

You import the same three modules: time, board and digitalio.

import time
import board
import digitalio

Then, as with the LED, you assign the variable button to a digitalio.DigitalInOut object, and provide it the pin you used to connect it to your Pico board - GP13. Then, unlike the LED, you set it to an input, and you set the pull to DOWN.

button = digitalio.DigitalInOut(board.GP13)
button.switch_to_input(pull=digitalio.Pull.DOWN)

This type of button is called a momentary button switch. When the button is not pressed, the opposite legs are not connected, and when you press the button, it makes a connection between the opposite legs. Pulling the pin down registers 0V when it is not connected to anything, so connecting it to 3.3V, e.g. pressing the button, registers a button press.

To check whether or not the button is pressed, you'll print the button.value in a loop. The sleep() is included to keep the serial output readable - without a delay, the serial output would be incredibly fast!

while True:
    print(button.value)
    time.sleep(0.5)

Perhaps you would rather print a message only when the button is pressed.

Update your code.py to the following and save.

"""
Button example for Pico. Prints message to serial console when button is pressed.

REQUIRED HARDWARE:
* Button switch on pin GP13.
"""
import time
import board
import digitalio

button = digitalio.DigitalInOut(board.GP13)
button.switch_to_input(pull=digitalio.Pull.DOWN)

while True:
    if button.value:
        print("You pressed the button!")
        time.sleep(0.5)

Now, check the serial console. Nothing is happening because you a have not pressed the button. Try pressing the button.

If you continue to press the button, it will display the message every 0.5 seconds until you let go. Now it's time to mix things up!

Control an External LED with a Button

Most electronics examples involve multiple components, which is why your Pico board has so many GPIO pins on it. You've learned about controlling an external LED, and reading the input from a button. You can combine those two concepts and control the LED using the button!

Now you understand why you left the LED connected to your Pico board when the previous example didn't involve it. You've already connected everything needed for this example!

 

 

Your hardware setup should still look like this.

Update your code.py to the following and save.

"""
Button and LED example for Pico. Turns on LED when button is pressed.

REQUIRED HARDWARE:
* Button switch on pin GP13.
* LED on pin GP14.
"""
import board
import digitalio

led = digitalio.DigitalInOut(board.GP14)
led.direction = digitalio.Direction.OUTPUT
button = digitalio.DigitalInOut(board.GP13)
button.switch_to_input(pull=digitalio.Pull.DOWN)

while True:
    if button.value:
        led.value = True
    led.value = False

Press the button. The LED turns on! Let it go, and the LED turns off.

You only need to import two modules this time: board and digitalio.

import board
import digitalio

Setup is the same for the LED and the button as it was previous, however, this time you include both.

led = digitalio.DigitalInOut(board.GP14)
led.direction = digitalio.Direction.OUTPUT
button = digitalio.DigitalInOut(board.GP13)
button.switch_to_input(pull=digitalio.Pull.DOWN)

Finally, in your loop, you check to see if the button is pressed, and if so, you turn on the LED. Otherwise, you turn off the LED.

while True:
    if button.value:
        led.value = True
    led.value = False

Alternatively, you can simply set the LED value equal to the button value, and you get the same results. Remember, when the button is pressed, it returns True, and when it's not, it returns False. When the LED is set to True, it turns on, and when it's set to False, it turns off. It's a quick way to control an LED with a button press!

"""
Button and LED example for Pico. Turns on LED when button is pressed.

REQUIRED HARDWARE:
* Button switch on pin GP13.
* LED on pin GP14.
"""
import board
import digitalio

led = digitalio.DigitalInOut(board.GP14)
led.direction = digitalio.Direction.OUTPUT
button = digitalio.DigitalInOut(board.GP13)
button.switch_to_input(pull=digitalio.Pull.DOWN)

while True:
    led.value = button.value

This guide was first published on Jan 21, 2021. It was last updated on 2021-03-03 12:34:49 -0500.

This page (Blinky and a Button) was last updated on Oct 15, 2021.

Text editor powered by tinymce.