If your CLUE board isn’t already running CircuitPython…
- Head to the CircuitPython download page for CLUE nRF52840 Express and fetch the latest build.
- Then go to the CircuitPython libraries download page and fetch the corresponding “bundle” for that version.
- If using Windows 7, you’ll also need a USB driver. This and other setup basics are covered in the Welcome to CircuitPython and Introducing Adafruit CLUE guides…if things behave oddly, start there.
- Connect a USB cable from CLUE to your computer and double-tap CLUE’s reset button on the back. When the CLUEBOOT drive appears, drag-and-drop the CircuitPython .UF2 file to that drive. Any program currently on the board (Arduino, earlier CircuitPython or anything else) will be overwritten.
Next steps after CircuitPython is installed…
- Unzip the CircuitPython bundle and copy two folders — adafruit_display_shapes and adafruit_display_text — to the CIRCUITPY drive lib folder.
- Download the code and images for this project from GitHub:
- Unzip the project and copy the folder bmps-72px to the CIRCUITPY drive.
- Do not copy any of the Python files to the drive until the following is understood:
To edit or remove files, make this connection between PIN 0 and GND and boot or reset the board. Now you can edit, but the light painter code won’t run.
Remove the connection and boot/reset and the light painter code runs, but you can’t edit. This is normal, it’s just part of how CircuitPython interacts with the flash filesystem and a USB-connected computer.
If you misplace the alligator cable, it is possible to get back into the board, but this involves accessing the CircuitPython REPL (e.g. from a terminal program) and entering some commands to remove or rename the boot.py file, as documented in this guide.
Copy the four .py files to the CIRCUITPY drive:
- bmp2led.py — this processes BMP image files into a format that our light-painting code can read quickly. It’s in a separate file so we have the option to use it in other projects later.
- boot.py — this runs when the board initially boots or is reset, and sets the flash filesystem to write-enabled mode if the alligator jumper is not present.
- code.py — the main light-painting application, using the CLUE’s display and buttons to provide a barebones user interface.
- richbutton.py — a CircuitPython library that processes button inputs to distinguish taps, double-taps and long holds.
Once these files are installed, you may want to edit the code.py file (using your text editor of preference) to configure some things for your particular setup. Remember, the PIN 0 to GND jumper must be in place when you boot or reset the board to edit files. Then remove the jumper and reset to test the changes. You might be going back and forth a few times like this.
Near the top of code.py, look for this section:
NUM_PIXELS = 72 # LED strip length PIXEL_PINS = board.SDA, board.SCL # Data, clock pins for DotStars PIXEL_ORDER = 'bgr' # Pixel color order PATH = '/bmps-72px' # Folder with BMP images (or '' for root path) TEMPFILE = '/led.dat' # Working file for LED data (will be clobbered!) FLIP_SCREEN = False # If True, turn CLUE screen & buttons upside-down GAMMA = 2.4 # Correction for perceptually linear brightness BRIGHTNESS_RANGE = 0.15, 0.75 # Min, max brightness (0.0-1.0)
NUM_PIXELS is the length of the DotStar strip — 72 or 60 pixels are both well suited to the performance of this board, but you’re welcome to try building something a different size.
PIXEL_PINS are the DotStar data and clock pins, respectively. Comma-separated. By default these are the board.SDA and board.SCL pins of the STEMMA QT socket (blue and yellow wires, respectively). If you’ve gone with a more temporary build, using ’gator clips to the board edge connector, you can use board.P1 and board.P2 here (avoid P0, already in use in boot.py).
PIXEL_ORDER is the sequence in which DotStar LEDs process the red, green and blue values of each pixel. Currently-shipping DotStar strips use 'bgr' order (blue, green, red)…but older DotStars, and compatible APA-102 LEDs from other sources, may use a different sequence ('gbr' was previously common).
PATH is the folder where the code looks for BMP images. See the “Pixel Art” page for requirements.
FLIP_SCREEN can be set True or False. If True, the display and buttons are flipped 180°…sometimes the physical assembly of the light stick just works out easier with the board turned around, and this compensates for it.
BRIGHTNESS_RANGE, two comma-separated values from 0.0 (off) to 1.0 (brightest), are the minimum and maximum LED brightness to use when light painting (a setting in the UI). 0.0 isn’t very useful, since that’s just off, so the default minimum is 0.15. The maximum is set below 1.0 (0.85 by default) because the LEDs coming on full brightness can cause a voltage sag…the CLUE board may lock up and, in severe situations, may even require reinstalling CircuitPython. If you see this happen, dial back the maximum value until the DotStars, battery and CLUE all play nice.
TEMPFILE and GAMMA can be ignored, probably won’t need to change these.
If you make changes but can’t save the file: the alligator jumper wasn’t in place when booting. Connect P0 and GND, reset before editing files. Remove the jumper and reset to run the code.
