One of the first things many people do with CircuitPython is blink an LED. We even consider it our version of "Hello, world!" It's fairly simple code with the little red LED - set the LED to True, wait for the desired on period, and set it to False for the desired off period. It gets a little more complicated with NeoPixels or DotStars - you have to set the LED to a color, wait, and then set the color to 0 to turn it off. Regardless, blinking is pretty easy. But what if you want to do more?

Creating a beautiful animated display on RGB LEDs, like NeoPixels and DotStars, is simple using the Adafruit CircuitPython LED Animation library. This library enables you to display a number of animations including comet, theatre chase, pulse, blink, color cycle, rainbow, sparkle and more.

This library also includes pixel mapping and animation group helpers. The pixel mapping helper allows you to work with strips of LEDs arranged in a grid or other shape to display animations across the grid or shape horizontally and vertically. It also allows you to combine multiple sets of LEDs, e.g. two matrices, and treat them as one for animation purposes. The animation group helper allows you to keep multiple animations synchronised, or to display two separate animations on two separate pixel objects, e.g. two separate strips.

This guide will walk you through the key features of each animation, such as timing and and other animation-specific customisations. It will cover the basics of pixel mapping to show you how to easily treat LEDs in a strip or series of strips as a grid to display animations, as well as the basics of animation groups to keep multiple animations in sync or display multiple animations across multiple sets of pixels.

Before we get animating, the first thing we'll do is look at what the basic import and setup looks like with the CircuitPython LED Animation library. Let's go!