The CircuitPython LED Animation library provides many animations. This section will cover the basic animations: solid, blink, colorcycle, chase, comet, and pulse. Most of these animations are displayed in a single color, with colorcycle cycling through a list of colors. Each animation has features you can adjust. We'll show the basics of using the animations, and look at the specific features for each one. Let's get animating!

Most animations will run individually on the SAMD21 (M0) microcontroller boards, but some combinations of animations and the most complex animations will not. Check out the FAQ for details. If you're interested in running all the animations, or many animations together, consider using at least a SAMD51 (M4) microcontroller.

Solid

Solid is the simplest of all the animations. It displays a single color. While this is easy enough to do alone without the LED Animation library, you may want to include a solid color in a series of animations, so we made it available.

First you import the Solid module and a color for it. See Import and Setup for the rest of the necessary imports and pixel object creation.

Download: file
from adafruit_led_animation.animation.solid import Solid
from adafruit_led_animation.color import PINK

Next, you create the Solid animation. Solid requires two arguments:

  • pixel_object: The pixel object, e.g. pixels.
  • color: The color to display, e.g. PINK. Can also be a color tuple, e.g. (255, 0, 0), or a hex color value, e.g. 0xFF0000.
Download: file
solid = Solid(pixels, color=PINK)

Then you need to display the animation.

Download: file
while True:
    solid.animate()

That's all there is to displaying a solid color using the LED Animation library! Let's take a look at the next animation.

Blink

The blink animation flashes a single color on and off at a specified speed.

First, you import the Blink module and a color for it. See Import and Setup for the rest of the necessary imports and pixel object creation.

Download: file
from adafruit_led_animation.animation.blink import Blink
from adafruit_led_animation.color import JADE

Next you create the Blink animation. Blink requires three arguments:

  • pixel_object: The pixel object, e.g. pixels.
  • speed: The speed of the blinking in seconds, e.g. 0.5.
  • color: The color to display, e.g. JADE. Can also be a color tuple, e.g. (255, 0, 0), or a hex color value, e.g. 0xFF0000.

Once created, you display the animation.

Download: file
blink = Blink(pixels, speed=0.5, color=JADE)

while True:
    blink.animate()

That's all there is to blinking a color on and off using the LED Animation library! Let's take a look at the next animation.

ColorCycle

The ColorCycle animation allows you to provide a list of colors to cycle through at a specified speed.

First you import the ColorCycle module and one or more colors for it. See Import and Setup for the rest of the necessary imports and pixel object creation.

Download: file
from adafruit_led_animation.animation.colorcycle import ColorCycle
from adafruit_led_animation.color import MAGENTA, ORANGE, TEAL

Next you create the ColorCycle animation. ColorCycle requires two arguments, and has an optional third. You'll likely want to specify the third, but the animation will run without specifying it.

Required:

  • pixel_object: The pixel object, e.g. pixels.
  • speed: The speed of color cycle in seconds, e.g. 0.5.

Optional:

  • colors: The list of colors to display, e.g. [MAGENTA, ORANGE, TEAL]. This must be a list! Lists are one or more items in []. If no colors are provided, it defaults to cycling through rainbow colors. Can also be a list of color tuples, e.g. (255, 0, 0), or a list of hex color values, e.g. 0xFF0000.

Once created, you display the animation.

Download: file
colorcycle = ColorCycle(pixels, 0.5, colors=[MAGENTA, ORANGE, TEAL])

while True:
    colorcycle.animate()

That's all there is to cycling through a list of colors using the LED Animation library! Let's take a look at the next animation.

Chase

This is a theatre marquee type chase animation, with definable length of lit LEDs and dark gap between lit LEDs.

First you import the Chase module and a color for it. See Import and Setup for the rest of the necessary imports and pixel object creation.

Download: file
from adafruit_led_animation.animation.chase import Chase
from adafruit_led_animation.color import WHITE

Next you create the Chase animation. Chase requires three arguments, and has an optional three more. This animation will run without the optional arguments, but you'll likely want to specify size and spacing as well.

Required:

  • pixel_object: The pixel object, e.g. pixels.
  • speed: The speed of the chase movement in seconds, e.g. 0.1.
  • color: The color to display, e.g. WHITE. Can also be a color tuple, e.g. (255, 0, 0), or a hex color value, e.g. 0xFF0000.

Optional:

  • size: The number of pixels to turn on in a row, e.g. 3. Defaults to 2 if no size is provided.
  • spacing: The number of pixels to turn off in a row, e.g. 6. Defaults to 3 if no size is provided.
  • reverse: Optionally reverses the movement of the animation. Set to True to enable. Defaults to False.

Once created, you display the animation.

Download: file
chase = Chase(pixels, speed=0.1, color=WHITE, size=3, spacing=6)

while True:
    chase.animate()

That's all there is to creating your own theatre chase animation using the LED Animation library! Let's take a look at the next animation.

Comet

This animation creates a comet of a specified speed, with a dimming tail of specified length.

First you import the Comet module and a color for it. See Import and Setup for the rest of the necessary imports and pixel object creation.

Download: file
from adafruit_led_animation.animation.comet import Comet
from adafruit_led_animation.color import PURPLE

Next you create the Comet animation. Comet requires three arguments, and has an optional three more. You'll likely want to specify at least tail_length.

Required:

  • pixel_object: The pixel object, e.g. pixels.
  • speed: The speed of the comet in seconds, e.g. 0.1.
  • color: The color to display, e.g. PURPLE. Can also be a color tuple, e.g. (255, 0, 0), or a hex color value, e.g. 0xFF0000.

Optional:

  • tail_length: The length of the comet in pixels. Defaults to 25% of the length of the pixel_object if no length is provided. Automatically compensates for a minimum length of 2 and a maximum of the length of the pixel_object.
  • reverse: Optionally reverses the movement of the animation. Set to True to enable. Defaults to False.
  • bounce: Optionally "bounces" the comet along the strip by displaying it from the beginning of the strip to the end, and then reversing the movement once it reaches the end of the strip. Set to True to enable. Defaults to False.

Once created, you display the animation.

Download: file
comet = Comet(pixels, speed=0.01, color=PURPLE, tail_length=10, bounce=True)

while True:
    comet.animate()

That's all there is to displaying a comet using the LED Animation library! Let's take a look at the next animation.

Pulse

This animation pulses all of the LEDs simultaneously a single color at a specified speed.

First you import the Pulse module and a color for it. See Import and Setup for the rest of the necessary imports and pixel object creation.

Download: file
from adafruit_led_animation.animation.pulse import Pulse
from adafruit_led_animation.color import AMBER

Next you create the Pulse animation. Pulse requires three arguments, and has an optional fourth.

Required:

  • pixel_object: The pixel object, e.g. pixels.
  • speed: The speed of the pulse in seconds, e.g. 0.1.
  • color: The color to display, e.g. AMBER. Can also be a color tuple, e.g. (255, 0, 0), or a hex color value, e.g. 0xFF0000.

Optional:

  • period: The number of seconds over which to pulse the LEDs. Defaults to 5 if no period is provided.

Once created, you display the animation.

Download: file
pulse = Pulse(pixels, speed=0.1, color=AMBER, period=3)

while True:
    pulse.animate()

That's all there is to pulsing a single color using the LED Animation library!

Next up, we'll look at running multiple animations in a sequence. Let's go!

Full Example Code

This is the simpletest example from the LED Animation library.

"""
This simpletest example displays the Blink animation.

For NeoPixel FeatherWing. Update pixel_pin and pixel_num to match your wiring if using
a different form of NeoPixels.
"""
import board
import neopixel
from adafruit_led_animation.animation.blink import Blink
from adafruit_led_animation.color import RED

# Update to match the pin connected to your NeoPixels
pixel_pin = board.D6
# Update to match the number of NeoPixels you have connected
pixel_num = 32

pixels = neopixel.NeoPixel(pixel_pin, pixel_num, brightness=0.5, auto_write=False)

blink = Blink(pixels, speed=0.5, color=RED)

while True:
    blink.animate()

This is an example that runs all of the basic animations in a sequence.

"""
This example displays the basic animations in sequence, at a five second interval.

For NeoPixel FeatherWing. Update pixel_pin and pixel_num to match your wiring if using
a different form of NeoPixels.

This example may not work on SAMD21 (M0) boards.
"""
import board
import neopixel

from adafruit_led_animation.animation.solid import Solid
from adafruit_led_animation.animation.colorcycle import ColorCycle
from adafruit_led_animation.animation.blink import Blink
from adafruit_led_animation.animation.comet import Comet
from adafruit_led_animation.animation.chase import Chase
from adafruit_led_animation.animation.pulse import Pulse
from adafruit_led_animation.sequence import AnimationSequence
from adafruit_led_animation.color import (
    PURPLE,
    WHITE,
    AMBER,
    JADE,
    TEAL,
    PINK,
    MAGENTA,
    ORANGE,
)

# Update to match the pin connected to your NeoPixels
pixel_pin = board.D6
# Update to match the number of NeoPixels you have connected
pixel_num = 32

pixels = neopixel.NeoPixel(pixel_pin, pixel_num, brightness=0.5, auto_write=False)

solid = Solid(pixels, color=PINK)
blink = Blink(pixels, speed=0.5, color=JADE)
colorcycle = ColorCycle(pixels, speed=0.4, colors=[MAGENTA, ORANGE, TEAL])
chase = Chase(pixels, speed=0.1, color=WHITE, size=3, spacing=6)
comet = Comet(pixels, speed=0.01, color=PURPLE, tail_length=10, bounce=True)
pulse = Pulse(pixels, speed=0.1, color=AMBER, period=3)


animations = AnimationSequence(
    solid, blink, colorcycle, chase, comet, pulse, advance_interval=5, auto_clear=True,
)

while True:
    animations.animate()
This guide was first published on May 27, 2020. It was last updated on May 27, 2020.
This page (Basic Animations) was last updated on Oct 24, 2020.