One of the best things about CircuitPython is how simple it is to get code up and running. In this section, we're going to cover 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. We strongly recommend 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 basic text editors built into every operating system such as Notepad on Windows, TextEdit on Mac, and gedit on Linux. However, many of these editors don't write back changes immediately to files that you edit. That can cause problems when using CircuitPython. See the Editing Code section below. If you want to skip that section for now, 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 is not a problem on MacOS.)
|
|
Open your editor, and create a new file. If you are using Mu, click the New button in the top left |
Copy and paste the following code into your editor:
import board
import digitalio
import time
led = digitalio.DigitalInOut(board.D13)
led.direction = digitalio.Direction.OUTPUT
while True:
led.value = True
time.sleep(0.5)
led.value = False
time.sleep(0.5)
If you're using QT Py, please download the QT Py blink example.
For Adafruit CLUE, you'll need to use board.D17 instead of board.D13. The rest of the code remains the same. Make the following change to the led = line:
led = digitalio.DigitalInOut(board.D17)
For Adafruit ItsyBitsy nRF52840, you'll need to use board.BLUE_LED instead of board.D13. The rest of the code remains the same. Make the following change to the led = line:
led = digitalio.DigitalInOut(board.BLUE_LED)
|
|
It will look like this - note that under the |
|
|
Save this file as code.py on your CIRCUITPY drive. |
On each board (except the ItsyBitsy nRF52840) you'll find a tiny red LED. On the ItsyBitsy nRF52840, you'll find a tiny blue LED.
The little LED should now be blinking. Once per second.
Congratulations, you've just run your first CircuitPython program!
|
|
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 just one warning we have to give you before we 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.
However, you must wait until the file is done being saved before unplugging or resetting your board! On Windows using some editors this can sometimes take up to 90 seconds, on Linux it can take 30 seconds to complete because the text editor does not save the file completely. Mac OS does not seem to have this delay, which is nice!
This is really important to be aware of. 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 few ways to avoid this:
1. Use an editor that writes out the file completely when you save it.
Recommended editors:
- mu is an editor that safely writes all changes (it's also our recommended editor!)
- emacs is also an editor that will fulIy write files on save
- Sublime Text safely writes all changes
- Visual Studio Code appears to safely write all changes
- gedit on Linux appears to safely write all changes
- IDLE, in Python 3.8.1 or later, was fixed to write all changes immediately
- thonny fully writes files on save
Recommended only with particular settings or with add-ons:
-
vim / vi safely writes all changes. But set up vim to not write swapfiles (.swp files: temporary records of your edits) to CIRCUITPY. Run vim with
vim -n, set theno swapfileoption, or set thedirectoryoption to write swapfiles elsewhere. Otherwise the swapfile writes trigger restarts of your program. - The PyCharm IDE is safe if "Safe Write" is turned on in Settings->System Settings->Synchronization (true by default).
- If you are using Atom, install the fsync-on-save package so that it will always write out all changes to files on
CIRCUITPY. - SlickEdit works only if you add a macro to flush the disk.
We don't recommend these editors:
- notepad (the default Windows editor) and Notepad++ can be slow to write, so we recommend the editors above! If you are using notepad, be sure to eject the drive (see below)
- IDLE in Python 3.8.0 or earlier does not force out changes immediately
- nano (on Linux) does not force out changes
- geany (on Linux) does not force out changes
- Anything else - we haven't tested other editors so please use a recommended one!
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.
Back to Editing Code...
Now! Let's try editing the program you added to your board. Open your code.py file into your editor. We'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.D13)
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? Let's find out!
Exploring Your First CircuitPython Program
First, we'll take a look at the code we're editing.
Here is the original code again:
import board
import digitalio
import time
led = digitalio.DigitalInOut(board.D13)
led.direction = digitalio.Direction.OUTPUT
while True:
led.value = True
time.sleep(0.5)
led.value = False
time.sleep(0.5)
Imports & Libraries
Each CircuitPython program you run needs to have a lot of information to work. The reason CircuitPython is so simple to use is that most of that information is stored in other files and works in the background. The files built into CircuitPython are called modules, and the files you load separately are called libraries. Modules are built into CircuitPython. Libraries are stored on your CIRCUITPY drive in a folder called lib.
import board import digitalio import time
The import statements tells the board that you're going to use a particular library in your code. In this example, we imported three modules: board, digitalio, and time. All three of these modules are built into CircuitPython, so no separate library files are needed. That's one of the things that makes this an excellent first example. You don't need any thing extra to make it work! board gives you access to the hardware on your board, digitalio lets you access that hardware as inputs/outputs and time let's you pass time by 'sleeping'
led = digitalio.DigitalInOut(board.D13) led.direction = digitalio.Direction.OUTPUT
Your board knows the red LED as D13. So, we initialise that pin, and we set it to output. We set led to equal the rest of that information so we don't have to type it all out again later in our code.
Loop-de-loops
The third section starts with a while statement. while True: essentially means, "forever do the following:". while True: creates a loop. Code will loop "while" the condition is "true" (vs. false), and as True is never False, the code will loop forever. All code that is indented under while True: is "inside" the loop.
Inside our loop, we have four items:
while True:
led.value = True
time.sleep(0.5)
led.value = False
time.sleep(0.5)
First, we have led.value = True. This line tells the LED to turn on. On the next line, we have time.sleep(0.5). This line is telling CircuitPython to pause running code for 0.5 seconds. Since this is between turning the led on and off, the led will be on for 0.5 seconds.
The next two lines are similar. led.value = False tells the LED to turn off, and time.sleep(0.5) tells CircuitPython to pause for another 0.5 seconds. This occurs between turning the led off and back on so the LED will be off for 0.5 seconds too.
Then the loop will begin again, and continue to do so as long as the code is running!
So, when you changed the first 0.5 to 0.1, you decreased the amount of time that the code leaves the LED on. So it blinks on really quickly before turning off!
Great job! You've edited code in a CircuitPython program!
What Happens When My Code Finishes Running?
When your code finishes running, CircuitPython resets your microcontroller board to prepare it for the next run of code. That means any set up you did earlier no longer applies, and the pin states are reset.
For example, try reducing the above example to led.value = True. The LED will flash almost too quickly to see, and turn off. This is because the code finishes running and resets the pin state, and the LED is no longer receiving a signal.
To that end, most CircuitPython programs involve some kind of loop, infinite or otherwise
If you don't have the loop, the code will run to the end and exit. This can lead to some unexpected behavior in simple programs like this since the "exit" also resets the state of the hardware. This is a different behavior than running commands via REPL. So if you are writing a simple program that doesn't seem to work, you may need to add a loop to the end so the program doesn't exit.
The simplest loop would be:
while True:
pass
And remember - you can press to exit the loop.
See also the Behavior section in the docs.
More Changes
We 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 we suggest using code.py as 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.
