One of the best things about CircuitPython is how simple it is to get code up and running. This section covers how to create and edit your first CircuitPython program.
To create and edit code, all you'll need is an editor. There are many options. Adafruit strongly recommends using Mu! It's designed for CircuitPython, and it's really simple and easy to use, with a built in serial console!
If you don't or can't use Mu, there are a number of other editors that work quite well. The Recommended Editors page has more details. Otherwise, make sure you do "Eject" or "Safe Remove" on Windows or "sync" on Linux after writing a file if you aren't using Mu. (This was formerly not a problem on macOS, but see the warning below.)
macOS Sonoma 14.1 introduced a bug that delays writes to small drives such as CIRCUITPY drives. This caused errors when saving files to CIRCUITPY. There is a workaround. The bug was fixed in Sonoma 14.4, but at the cost of greatly slowed writes to drives 1GB or smaller.
Installing CircuitPython generates a code.py file on your CIRCUITPY drive. To begin your own program, open your editor, and load the code.py file from the CIRCUITPY drive.
If you are using Mu, click the Load button in the button bar, navigate to the CIRCUITPY drive, and choose code.py.
Copy and paste the following code into your editor:
import board
import digitalio
import time
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 KB2040, QT Py , Qualia, and the Trinkeys do not have a built-in little red LED! There is an addressable RGB NeoPixel LED. The above example will NOT work on the KB2040, QT Py, Qualia, or the Trinkeys!
If you're using a KB2040, QT Py, Quaila, or a Trinkey, or any other board without a single-color LED that can blink, please download the NeoPixel blink example.
It will look like this. Note that under the while True: line, the next four lines begin with four spaces to indent them, and they're indented exactly the same amount. All the lines before that have no spaces before the text.
The little LED should now be blinking. Once per half-second.
Congratulations, you've just run your first CircuitPython program!
On most boards you'll find a tiny red LED. On the ItsyBitsy nRF52840, you'll find a tiny blue LED. On QT Py M0, QT Py RP2040, Qualia, and the Trinkey series, you will find only an RGB NeoPixel LED.
To edit code, open the code.py file on your CIRCUITPY drive into your editor.
Â
Make the desired changes to your code. Save the file. That's it!
Your code changes are run as soon as the file is done saving.
There's one warning before you continue...
The CircuitPython code on your board detects when the files are changed or written and will automatically re-start your code. This makes coding very fast because you save, and it re-runs. If you unplug or reset the board before your computer finishes writing the file to your board, you can corrupt the drive. If this happens, you may lose the code you've written, so it's important to backup your code to your computer regularly.
There are a couple of ways to avoid filesystem corruption.
1. Use an editor that writes out the file completely when you save it.
Check out the Recommended Editors page for details on different editing options.
2. Eject or Sync the Drive After Writing
If you are using one of our not-recommended-editors, not all is lost! You can still make it work.
On Windows, you can Eject or Safe Remove the CIRCUITPY drive. It won't actually eject, but it will force the operating system to save your file to disk. On Linux, use the sync command in a terminal to force the write to disk.
You also need to do this if you use Windows Explorer or a Linux graphical file manager to drag a file onto CIRCUITPY.
Don't worry! Corrupting the drive isn't the end of the world (or your board!). If this happens, follow the steps found on the Troubleshooting page of every board guide to get your board up and running again.
If you are having trouble saving code on Windows 10, try including this code snippet at the top of code.py:
import supervisor supervisor.runtime.autoreload = False
Back to Editing Code...
Now! Let's try editing the program you added to your board. Open your code.py file into your editor. You'll make a simple change. Change the first 0.5 to 0.1. The code should look like this:
import board
import digitalio
import time
led = digitalio.DigitalInOut(board.LED)
led.direction = digitalio.Direction.OUTPUT
while True:
led.value = True
time.sleep(0.1)
led.value = False
time.sleep(0.5)
Leave the rest of the code as-is. Save your file. See what happens to the LED on your board? Something changed! Do you know why?
You don't have to stop there! Let's keep going. Change the second 0.5 to 0.1 so it looks like this:
while True:
led.value = True
time.sleep(0.1)
led.value = False
time.sleep(0.1)
Now it blinks really fast! You decreased the both time that the code leaves the LED on and off!
Now try increasing both of the 0.1 to 1. Your LED will blink much more slowly because you've increased the amount of time that the LED is turned on and off.
Well done! You're doing great! You're ready to start into new examples and edit them to see what happens! These were simple changes, but major changes are done using the same process. Make your desired change, save it, and get the results. That's really all there is to it!
CircuitPython looks for a code file on the board to run. There are four options: code.txt, code.py, main.txt and main.py. CircuitPython looks for those files, in that order, and then runs the first one it finds. While code.py is the recommended name for your code file, it is important to know that the other options exist. If your program doesn't seem to be updating as you work, make sure you haven't created another code file that's being read instead of the one you're working on.
Page last edited July 08, 2024
Text editor powered by tinymce.
