Creating and Editing Code

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 load libraries, and create and edit your first CircuitPython program.

CircuitPython Libraries

The first thing you'll need to do is make sure you have the CircuitPython library bundle installed. 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. These files are called libraries. Some of them are built into CircuitPython. Others are stored on your CIRCUITPY drive in a folder called lib. Part of what makes CircuitPython so awesome is its ability to store code separately from the firmware itself. Storing code separately from the firmware makes it easier to update both the code you write and the libraries you depend.

Your board may ship with a lib folder already present. We're always updating and improving libraries, so it's best to download the latest version and replace the version that it shipped with!

Click on the link below to go to the CircuitPython Library Bundle Releases page. Download the 4.x bundle. You always want to download the bundle that matches the version of CircuitPython you're using.

Unzip the file you downloaded, open the folder, and then copy the lib folder to your CIRCUITPY drive. For a more detailed explanation, please see the CircuitPython Libraries page in this guide.

That's all there is to installing the CircuitPython library bundle!

Choosing an Editor

To create and edit code, all you'll need is an editor. There are many options. 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. If you choose to use one of these editors, make sure you do "Eject" or "Safe Remove" on Windows or "sync" on Linux after writing a file. (This is not a problem on MacOS.) However, here are some editors that write the file completely on save:

  • emacs is also an editor that will fulIy write files on save
  • vim / vi safely writes all changes
  • Sublime Text safely writes all changes
  • The PyCharm IDE is safe if "Safe Write" is turned on in Settings->System Settings->Synchronization (on 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.
  • Visual Studio Code appears to safely write all changes
  • gedit on Linux appears to safely write all changes

Creating Code

To create your first program, create a file called code.py on your CIRCUITPY drive using your editor. Copy and paste the following code into your code.py file and save. The first NeoPixel will start blinking red!

Download: file
import time
import adafruit_trellism4

trellis = adafruit_trellism4.TrellisM4Express()

while True:
    trellis.pixels[0, 0] = (100, 0, 0)
    time.sleep(0.5)
    trellis.pixels[0, 0] = (0, 0, 0)
    time.sleep(0.5)

There's one warning we have to give you before we continue...

Don't Click Reset or Unplug!

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.

You can avoid this in two ways:

  • Use an editor that writes fully on save, like the editors suggested int the list above.
  • Always eject or sync the after writing. 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.

Editing Code

Now that you've created and run your CircuitPython program, let's take a look at editing it. We'll make a simple change. Change the first 0.5 to 0.1. The code should look like this:

Download: file
import time
import adafruit_trellism4

trellis = adafruit_trellism4.TrellisM4Express()

while True:
    trellis.pixels[0, 0] = (100, 0, 0)
    time.sleep(0.1)
    trellis.pixels[0, 0] = (0, 0, 0)
    time.sleep(0.5)

Leave the rest of the code as-is. Save your file. See what happens to the NeoPixel 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:

Download: file
import time
import adafruit_trellism4

trellis = adafruit_trellism4.TrellisM4Express()

while True:
    trellis.pixels[0, 0] = (100, 0, 0)
    time.sleep(0.5)
    trellis.pixels[0, 0] = (0, 0, 0)
    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. These files are called libraries. Some of them are built into CircuitPython. Others are stored on your CIRCUITPY drive in a folder called lib.

Download: file
import time
import adafruit_trellism4

The import statements tells the board that you're going to use a particular library in your code. In this example, we imported two libraries: time and adafruit_trellism4time let's you pass time by 'sleeping', and adafruit_trellism4 lets you interact with the buttons and NeoPixels on the front of your board.

Setting Up The Trellis M4

The next line sets up Trellis M4 library.

Download: file
trellis = adafruit_trellism4.TrellisM4Express()

We assign trellis to allow us to use the features of the Trellis M4 library 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:

Download: file
while True:
    trellis.pixels[0, 0] = (100, 0, 0)
    time.sleep(0.5)
    trellis.pixels[0, 0] = (0, 0, 0)
    time.sleep(0.5)

First, we have trellis.pixels[0, 0] = (100, 0, 0). This line tells the first NeoPixel to turn on red. 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 NeoPixel red and off, the led will be on for 0.5 seconds.

The next two lines are similar. trellis.pixels[0, 0] = (100, 0, 0) tells the NeoPixel to turn off, and time.sleep(0.5) tells CircuitPython to pause for another 0.5 seconds. This occurs between turning the NeoPixel off and back on so the NeoPixel 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 NeoPixel on. So it blinks on really quickly before turning off!

Great job! You've edited code in a CircuitPython program!

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:

Download: file
while True:
    trellis.pixels[0, 0] = (100, 0, 0)
    time.sleep(0.1)
    trellis.pixels[0, 0] = (0, 0, 0)
    time.sleep(0.1)

Now it blinks really fast! You decreased the both time that the code leaves the NeoPixel on and off!

Now try increasing both of the 0.1 to 1. Your NeoPixel will blink much more slowly because you've increased the amount of time that the NeoPixel 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!

This guide was first published on Oct 31, 2018. It was last updated on Oct 31, 2018. This page (Creating and Editing Code) was last updated on Jul 20, 2019.