Prerequisites

A Raspberry Pi 3B+ or 4 with Raspbian Buster installed and connected to an Adafruit Circuit Playground Express via a micro USB to USB cable and with CircuitPython installed on the Circuit Playground Express (see working with the adafruit circuit playground express using the raspberry pi 4).

Setting Up and Tearing Down the REPL

Attach the Circuit Playground Express (CPE) to the Raspberry Pi. The CIRCUITPY storage device icon will appear on the desktop and a dialog will appear simultaneously asking if you want to open removable media in a file manager. You can click OK if you wish, or Cancel to remove the dialog. If you cancel the dialog but wish to open the removable media portion you can double click on the desktop icon. If you open the file manager you’ll see the following:

It’s fairly empty at the moment. Now, open an LXTerminal and type ‘screen /dev/ttyACM0 115200‘ at the prompt.

Auto-reload is on. Simply save files over USB to run them or enter REPL to disable.Press any key to enter the REPL. Use CTRL-D to reload.

Don’t type anything. Instead, using the mouse, click the up arrow that has appeared on the upper right task bar. This is the media eject control. Clicking it will produce a menu with at least the CIRCUITPY as an entry (you may have more depending on what other removable media you have plugged in. Select the CIRCUITPY entry to remove accessibility to CIRCUITPY. Then physically disconnect the CPE. Your console will now display the following:

pi@raspberrypi:~ $ screen /dev/ttyACM0 115200[screen is terminating]pi@raspberrypi:~ $

I’ve just shown how to set up and tear down the serial port into the CPE. For writing code in an editor and saving it on the CPE as main.py, it will print out any syntax errors and other data as needed to the terminal.

Circuit Python Programming Example 1

In this example I’ll show you how syntax errors will appear on the terminal. If you’ve detached the CPE, plug it back in so that it’s seen as removable media. Restart the screen utility so that you see the intro text in the terminal. Now start a text editor (VIM, gedit, text editor, whatever). Type a single line into the editor, ‘import fubar‘. Then save what you just typed as main.py onto CIRCUITPY and then look at your terminal.

Auto-reload is on. Simply save files over USB to run them or enter REPL to disable.main.py output:Traceback (most recent call last):  File "main.py", line 1, in <module>ImportError: no module named 'fubar'Press any key to enter the REPL. Use CTRL-D to reload.

There obviously is no fubar module, and Circuit Python prints out that fact as an error message on the terminal.

Circuit Python Programming Example 2

Let’s print something on the terminal. Replace the import statement with ‘print('Hello terminal')‘ and save the file. Now the terminal will show:

Auto-reload is on. Simply save files over USB to run them or enter REPL to disable.main.py output:Hello terminalPress any key to enter the REPL. Use CTRL-D to reload.

The Circuit Python is waiting for changes to main.py. Every time you save it you change it (you change the file’s timestamp, the last time the file was modified), CPE will attempt to run it. Either it’ll run, or it will stop with errors. You can use print statements to debug a program as it runs and see those print statements on the terminal.

Circuit Python Programming Example 3

Now lets code something a bit more ambitious. Let’s copy the following code into your editor and then save it out as main.py again.

import board, neopixel, timepixels = neopixel.NeoPixel(board.NEOPIXEL, 10, brightness=.2)RED = (63, 0, 0)pixels.fill(RED)time.sleep(1)GREEN = (0, 63, 0)pixels.fill(GREEN)time.sleep(1)BLUE = (0, 0, 63)pixels.fill(BLUE)time.sleep(1)BLACK = (0, 0, 0)pixels.fill(BLACK)

If you’ll recall this is essentially the same code we typed in by hand at the end of the last post, except this time we’re going to write it into main.py and save it. When you do, you’ll see all the NeoPlixel LEDs light up in red, then green, then blue, then go dark. We’ve added three sleep commands for one second so that it doesn’t run through all the fill commands. Save this version of main.py and watch the NeoPixels light up.

What if you want to have the application repeat? You can save it again, or you can hit any key in the terminal to enter the REPL and then [Ctrl] D to exit, and the CPE will execute main.py all over again. This might be useful for simple programs, or you might want to get a bit more sophisticated for repetitive applications.

Circuit Python Programming Example 4

Let’s add to our existing application. Let’s add some looping and some print statements.

import board, neopixel, timepixels = neopixel.NeoPixel(board.NEOPIXEL, 10, brightness=.2)for letter in "ABCDE":print(" %c loop" % letter)RED = (63, 0, 0)pixels.fill(RED)time.sleep(0.5)GREEN = (0, 63, 0)pixels.fill(GREEN)time.sleep(0.5)BLUE = (0, 0, 63)pixels.fill(BLUE)time.sleep(0.5)BLACK = (0, 0, 0)pixels.fill(BLACK)

I’ve changed the sleep time, lowering it to 1/2 second so the loop will go faster than the single pass used in example 3. I’m using simple iteration of a string of characters. In every loop I print out the letter of each loop. Save the file and watch the NeoPixels cycle through red, green, and blue five times. Here’s what the terminal looks like.

Auto-reload is on. Simply save files over USB to run them or enter REPL to disable.main.py output: A loop B loop C loop D loop E loopPress any key to enter the REPL. Use CTRL-D to reload.

You’ve now got an application that manipulates some of the CPE’s devices (the NeoPixels) as well as printing out what loop it’s in on the terminal while it’s running.

The CPE is a powerful little board, with a lot more than just NeoPixels to manipulate. Perhaps next time I’ll dive in and add both CPE input and output, and find a way to feed some of the CPE’s inputs back to the Raspberry Pi.

Attach the Circuit Playground Express

Physically and electrically attach the Adafruit Circuit Playground Express (CPE) to the Raspberry Pi 4 via one of its USB ports. It doesn’t matter if it’s USB 2 or USB 3. The CPE should begin to operate; a little green power light next to the micro USB port will light, and all 10 of its NeoPixel LEDs will turn on in a continuous counter-clockwise sequence, starting at the micro USB port. For an extra sanity check you can see if the Raspberry Pi can see the USB connection as a serial TTY device:

pi@raspberrypi:~ $ ls -AlFh /dev/ttyACM0 crw-rw---- 1 root dialout 166, 0 Jul 31 22:58 /dev/ttyACM0pi@raspberrypi:~ $

We’ll talk about the ttyACM0 device later on.

Download the Circuit Python Interpreter

We want to program the CPE using Python, but unfortunately the CPE doesn’t come with Python, or more specificly, Circuit Python installed. That means we’ll need to install the Circuit Python interpreter maintained by Adafruit. As of the date of this posting I’m using Circuit Python version 4.1.0 RC1. First let me list several key web locations you’ll want to remember.

1. Circuit Python Git releases location – https://github.com/adafruit/circuitpython/releases
2. Circuit Python download location – https://circuitpython.org/board/circuitplayground_express/

The first location has a full list, and is the area where all active development and support takes place. You can even download the Circuit Python interpreter for the CPE from there, although it’s a bit crowded to read, and thus find. Instead, go to 2, and select either the stable or the so-called unstable release. In our case, the RC1, or release candidate #1, is as good as stable. That will be the second selection on the right. Pick your language (it defaults to English) then download it into ~/Download in your login area on the Raspberry Pi. When I downloaded it the file name was adafruit-circuitpython-circuitplayground_express-en_US-4.1.0-rc.1.uf2. The file name will change over time, but the extension, uf2, will not.

Update 3 August

The official CircuitPython version 4.1.0 was released on 2 August 2019. Now when you go to the download site, 4.1 is the default download. When downloaded it will have the same file name, minus ‘-rc.1’, in the file name. Just be aware that over time these release versions will continue to increase, so adjust these instructions accordingly as you follow along.

Put the Circuit Playground Express in Bootloader Mode

Unlike the micro:bit, the CPE does not come with Adafruit’s equivalent to MicroPython, CircuitPython, installed. However it’s very easy to install it. With the CPE still connected to the Raspberry Pi 4 click the reset button ONCE. If your CPE is like one of mine, then a new file device named CPLAYBOOT will appear on your Raspbian desktop. You’ll also get  a dialog asking if you want to open or execute. Chose to open, or if you close the dialog, double click on the CPLAYBOOT device on the desktop.

Once the CPLAYBOOT file explorer is open, this is what you’ll see.

Now open up another file explorer to where you downloaded the CircuitPython interpreter file to.

Drag that file, ending in UF2, from the download area and drop it onto the CPE. The CPE will briefly reset after the file is copied, and then reappear as a different attached file device named CIRCUITPY.

At this point, the only lit LED is the power on LED to the left of the micro USB socket. On the CIRCUITPY device there is an empty lib folder and a text file. Opening the text file shows the following single line:

Adafruit CircuitPython 4.1.0-rc.1 on 2019-07-19; Adafruit CircuitPlayground Express with samd21g18

That single line shows the release version and the build date. That should match what you copied onto the CPE earlier, and it shows that the CPE booted into the interpreter. You’re now ready for the next stage.

Using CircuitPython

Writing CircuitPython applications is as simple as writing a Python application and dropping it onto CIRCUITPY. The file must be named main.py for it to execuite. But before you do that you can work directly with CircuitPython via REPL (read-eval-print loop). There is a Raspbian utility that can be used to work with the REPL as well as act as a debug port. It’s called screen.

You can tell if screen is installed with which screen. If it prints out a full path to the utility, then it’s installed. If it returns nothing, then install screen with sudo apt install screen -y.

To start screen open a console window and type screen /dev/ttyACM0 115200. The terminal will clear and you’ll see the following:

Auto-reload is on. Simply save files over USB to run them or enter REPL to disable.Press any key to enter the REPL. Use CTRL-D to reload.

Now just press Enter to enter the REPL. Type a simple Python command at the REPL prompt.

Adafruit CircuitPython 4.1.0-rc.1 on 2019-07-19; Adafruit CircuitPlayground Express with samd21g18>>> print('Hello')Hello>>>

Everything is continuing to check out, and you now have a way to work directly with the CPE. Now let’s type something more ambitious.

>>> import board, neopixel>>> pixels = neopixel.NeoPixel(board.NEOPIXEL, 10, brightness=.2)>>> RED = (63, 0, 0)>>> pixels.fill(RED)>>> GREEN = (0, 63, 0)>>> pixels.fill(GREEN)>>> BLUE = (0, 0, 63)>>> pixels.fill(BLUE)>>>

If you’ve been looking over at your Circuit Playground Express after each pixel.fill() command you’ll see that all the NeoPixels have been lighting up respectively as red, green, and blue. This tiny bit should whet your appetite to dig in deeper and work with the Circuit Playground Express via CircuitPython. In the next post we’ll add an application the the Circuit Playground Express and show how to use the screen as a debugging aid. Until the next time.