Getting Started with Raspberry Pi Pico and CircuitPython (2024)

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.

# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries## SPDX-License-Identifier: MIT"""Example for Pico. Turns on the built-in LED."""import boardimport digitalioled = digitalio.DigitalInOut(board.LED)led.direction = digitalio.Direction.OUTPUTwhile True: led.value = True

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 boardimport digitalio

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

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.

# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries## SPDX-License-Identifier: MIT"""Example for Pico. Turns the built-in LED on and off with no delay."""import boardimport digitalioled = digitalio.DigitalInOut(board.LED)led.direction = digitalio.Direction.OUTPUTwhile 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.

# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries## SPDX-License-Identifier: MIT"""Example for Pico. Blinks the built-in LED."""import timeimport boardimport digitalioled = digitalio.DigitalInOut(board.LED)led.direction = digitalio.Direction.OUTPUTwhile 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.

# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries## SPDX-License-Identifier: MIT"""Example for Pico. Blinks the built-in LED."""import timeimport boardimport digitalioled = digitalio.DigitalInOut(board.LED)led.direction = digitalio.Direction.OUTPUTwhile 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.

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!

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.

# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries## SPDX-License-Identifier: MIT"""LED example for Pico. Blinks external LED on and off.REQUIRED HARDWARE:* LED on pin GP14."""import timeimport boardimport digitalioled = digitalio.DigitalInOut(board.GP14)led.direction = digitalio.Direction.OUTPUTwhile 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.

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.

# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries## SPDX-License-Identifier: MIT"""Button example for Pico. Prints button pressed state to serial console.REQUIRED HARDWARE:* Button switch on pin GP13."""import timeimport boardimport digitaliobutton = digitalio.DigitalInOut(board.GP13)button.switch_to_input(pull=digitalio.Pull.DOWN)while True: print(button.value) time.sleep(0.5)

import timeimport boardimport digitalio

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.

# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries## SPDX-License-Identifier: MIT"""Button example for Pico. Prints message to serial console when button is pressed.REQUIRED HARDWARE:* Button switch on pin GP13."""import timeimport boardimport digitaliobutton = 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)

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!

# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries## SPDX-License-Identifier: MIT"""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 boardimport digitalioled = digitalio.DigitalInOut(board.GP14)led.direction = digitalio.Direction.OUTPUTbutton = 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 boardimport digitalio

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

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

# SPDX-FileCopyrightText: 2021 Kattni Rembor for Adafruit Industries## SPDX-License-Identifier: MIT"""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 boardimport digitalioled = digitalio.DigitalInOut(board.GP14)led.direction = digitalio.Direction.OUTPUTbutton = digitalio.DigitalInOut(board.GP13)button.switch_to_input(pull=digitalio.Pull.DOWN)while True: led.value = button.value