Beginner / 2–3 hours
Give the matrix a little movement
A moving pixel is a good first project. Writing your own fade, comet tail, and animation playlist is a bigger job. Adafruit's LED Animation library gives us those pieces so we can spend our time deciding what the display should communicate.
We'll start with effects along the LED chain, then make an effect move across whole columns. That second step makes a big difference: a library written for a strip can still be useful on a matrix.
Install the library
Keep the NeoPixel libraries and copy the whole adafruit_led_animation folder from your matching CircuitPython bundle into CIRCUITPY/lib/. Copying just the animation file you want can leave out shared modules it needs.
Build an animation playlist
Replace code.py with this complete program:
import board
import neopixel
from adafruit_led_animation.animation.blink import Blink
from adafruit_led_animation.animation.comet import Comet
from adafruit_led_animation.animation.rainbow import Rainbow
from adafruit_led_animation.sequence import AnimationSequence
pixels = neopixel.NeoPixel(
board.NEOPIXEL, 50, brightness=0.05,
auto_write=False, pixel_order=neopixel.GRB
)
blink = Blink(pixels, speed=0.5, color=(255, 80, 0))
comet = Comet(pixels, speed=0.04, color=(0, 150, 255),
tail_length=8, bounce=True)
rainbow = Rainbow(pixels, speed=0.05, period=3)
animations = AnimationSequence(
blink, comet, rainbow, advance_interval=6, auto_clear=True
)
while True:
animations.animate()
The matrix should blink amber, run a blue comet, then cycle through rainbow colors. Each effect gets about six seconds before the sequence advances.
The animation object remembers its own progress. Calling animate() repeatedly gives it opportunities to update when its next frame is due. AnimationSequence selects the active effect and advances it. The LED Animation API documents the available effects and constructor options.
Which setting changes what?
speed is the interval between updates, in seconds. Smaller values generally make an effect update faster. Try changing the comet from 0.04 to 0.12; its movement should slow down.
color sets the effect's RGB color where the effect supports a fixed color. tail_length controls how many positions make up the comet's trail. bounce=True makes it reverse at the ends. Rainbow's period controls its color-cycle duration. advance_interval belongs to the sequence and controls when we change effects, rather than how fast an individual effect moves.
auto_clear=True clears pixels when switching animations, helping avoid leftovers from the previous effect. The animation code handles showing frames; we don't need a separate pixels.show() after every call to animations.animate().
Change one setting at a time. A very long comet tail can look good on 50 individual pixels and much less distinct on ten logical columns.
Turn five LEDs into one animation position
On a strip, a comet follows the wire. On this board, that means it walks across a row and jumps to the next one. What if we want a vertical bar sweeping across the whole display?
PixelMap lets us group physical LEDs into logical pixels. For this effect, one logical pixel will be a column of five LEDs. Replace code.py with:
import board
import neopixel
from adafruit_led_animation.animation.comet import Comet
from adafruit_led_animation.helper import PixelMap
WIDTH = 10
HEIGHT = 5
pixels = neopixel.NeoPixel(
board.NEOPIXEL, WIDTH * HEIGHT, brightness=0.05,
auto_write=False, pixel_order=neopixel.GRB
)
def xy(x, y):
return y * WIDTH + x
column_indices = [
[xy(x, y) for y in range(HEIGHT)]
for x in range(WIDTH)
]
columns = PixelMap(pixels, column_indices, individual_pixels=True)
comet = Comet(columns, speed=0.12, color=(0, 150, 255),
tail_length=3, bounce=True)
while True:
comet.animate()
Use the xy() mapping verified on the NeoPixel page; replace this version if your board needs the alternate map.
column_indices is a list of ten lists. The first contains 0, 10, 20, 30, 40: the five LEDs in column zero. individual_pixels=True tells PixelMap that these are explicit pixel numbers. Without that option, the helper expects start/stop ranges instead. Adafruit's pixel mapping guide shows more ways to group a matrix.
The comet now sees ten positions. Setting its first position changes all five physical LEDs in the first column. No physical wiring changed; we changed how the animation sees it.
Try grouping rows instead. Build one group for every y, containing all ten xy(x, y) values. The effect will have only five logical positions, so shorten the tail to two and slow it down enough to see each step.
Leave room for the rest of your project
Keep calling animate() often. Adding time.sleep(2) to the loop leaves the animation waiting for two seconds, even if its configured speed is much faster. When you add other tasks, use time.monotonic() to decide when those tasks need attention instead of putting a long sleep between frames.
Also choose one owner for the matrix at a time. If an animation and your own drawing function both write the same pixels on every pass, the last writer wins. A sensor can select an animation or change its color; the active animation can then do the drawing.
If an effect doesn't move, check that the loop actually calls animate(). If imports fail, recopy the whole library folder. If the column effect scatters pixels around the board, return to the walking-pixel test and correct xy().