This project is coded using CircuitPython which makes it super simple to edit. There are a number of customisations you can update to make this project fit your needs. If you also want to change the style and type of LED animations, there is a guide on using the CircuitPython LED Animation library that covers all the features.

This page will show you how to customise a few things about the three included animations, including LED colors. However, before the code will run, you need to load the LED Animation library onto your CIRCUITPY drive.

If you're having difficulty running this example, it could be because your MagTag CircuitPython firmware or library needs to be upgraded! Please be sure to follow to install the latest CircuitPython firmware and then also replace/update ALL the MagTag-specific libraries mentioned here

Installing Project Code

To use with CircuitPython, you need to first install a few libraries, into the lib folder on your CIRCUITPY drive. Then you need to update with the example script.

Thankfully, we can do this in one go. In the example below, click the Download Project Bundle button below to download the necessary libraries and the file in a zip file. Extract the contents of the zip file, open the directory MagTag_CIrcuitPython_Smart_Holiday_Lights/ and then click on the directory that matches the version of CircuitPython you're using and copy the contents of that directory to your CIRCUITPY drive.

Your CIRCUITPY drive should now look similar to the following image:

# SPDX-FileCopyrightText: 2020 Kattni Rembor for Adafruit Industries
# SPDX-License-Identifier: MIT

import board
import digitalio
import neopixel
from adafruit_magtag.magtag import MagTag

from adafruit_led_animation.animation.comet import Comet
from adafruit_led_animation.animation.sparkle import Sparkle
from adafruit_led_animation.animation.solid import Solid
from adafruit_led_animation.animation.colorcycle import ColorCycle
from adafruit_led_animation.sequence import AnimationSequence, AnimateOnce
from import AnimationGroup
from adafruit_led_animation.color import RED, GREEN, BLUE, WHITE, GOLD

# =============== CUSTOMISATIONS ================
# The pin to which you connected your NeoPixel strip.
strip_pin = board.D10
# The number of NeoPixels on the strip.
strip_num = 30

# The MagTag LED brightness, where 0.0 is 0% (off) and 1.0 is 100% brightness, e.g. 0.3 is 30%.
pixel_brightness = 0.5
# The strip LED brightness, where 0.0 is 0% (off) and 1.0 is 100% brightness, e.g. 0.3 is 30%.
strip_brightness = 1

# The colors to cycle through. Can be any number of colors.
color_cycle_colors = (RED, GREEN)
# The speed of the color cycle in seconds. Decreasing speeds it up, increasing slows it down.
cycle_speed = 0.5

# The sparkle color.
sparkle_color = GOLD
# The sparkle speed in seconds. Decreasing speeds it up, increasing slows it down.
sparkle_speed = 0.1

# The comet colors.
comet_one_color = WHITE
comet_two_color = BLUE

# The speed of the comet on the MagTag NeoPixels.
magtag_comet_speed = 0.06
# The length of the comet tail on the MagTag NeoPixels.
magtag_comet_tail = 3
# The speed of the comet on the strip of NeoPixels.
strip_comet_speed = 0.03
# The length of the comet tail on the strip of NeoPixels.
strip_comet_tail = 15
# ===============================================

# Setup MagTag library.
magtag = MagTag()

# Setup pixels.
pixels = magtag.peripherals.neopixels
pixels.brightness = pixel_brightness
magtag.peripherals.neopixel_disable = False
strip = neopixel.NeoPixel(strip_pin, strip_num, brightness=strip_brightness, auto_write=False)

# Create animations in sequences and groups.
animations = AnimationSequence(
        ColorCycle(pixels, cycle_speed, color_cycle_colors),
        ColorCycle(strip, cycle_speed, color_cycle_colors),
        Sparkle(pixels, sparkle_speed, sparkle_color, 15),
        Sparkle(strip, sparkle_speed, sparkle_color, 1),
                Comet(pixels, magtag_comet_speed, comet_one_color, tail_length=magtag_comet_tail),
                Comet(strip, strip_comet_speed, comet_one_color, tail_length=strip_comet_tail),
                Comet(pixels, magtag_comet_speed, comet_two_color, tail_length=magtag_comet_tail),
                Comet(strip, strip_comet_speed, comet_two_color, tail_length=strip_comet_tail),
        # Turn the LEDs off.
        Solid(pixels, 0),
        Solid(strip, 0),

# Set the background image.

# Add lines of text including button labels.
magtag.add_text(text_color=0xFFFFFF, text_position=(0, 10), text_scale=2)
magtag.set_text("Button functions:", auto_refresh=False)
magtag.add_text(text_color=0xFFFFFF, text_position=(0, 65))
magtag.set_text(" Button A: Color Cycle\n"
                " Button B: Sparkle\n"
                " Button C: Comet\n"
                " Button D: LEDs off",
magtag.add_text(text_color=0xFFFFFF, text_position=(0, 120))
magtag.set_text("    A           B           C           D", index=2)

# Main loop.
while True:
    if magtag.peripherals.button_a_pressed:
    elif magtag.peripherals.button_b_pressed:
    elif magtag.peripherals.button_c_pressed:
    elif magtag.peripherals.button_d_pressed:

The code loads the background image and the three separate text elements. The display will refresh, and there will be a pause before the LEDs begin color cycling. This is expected behavior.

There are a few things that you can easily update to customise this project to fit your aesthetic and hardware setup. Let's take a look!


Hardware Setup

The first thing you can set is the pin to which you connected your NeoPixel strip and the number of NeoPixels on the strip.

strip_pin = board.D10
strip_num = 30

The code defaults to pin D10 (which is the JST port on the left side of the bottom of the MagTag if you're looking at it from the back), and 30 pixels (which matches the two JST-ready NeoPixel strips carried in the Adafruit shop).

You can also set the pixel brightness for both the MagTag LEDs and the LED strip separately. Depending on how you mounted the LED strip, you may want to make it brighter than the MagTag LEDs.

pixel_brightness = 0.5
strip_brightness = 1

NeoPixels can get really bright. The code defaults to 0.5, or 50% brightness, for the MagTag LEDs, and 1, or 100% brightness, for the strip. The strip cannot get any brighter than 100%, however you can increase the MagTag LED brightness number to make them brighter. You can decrease either of the numbers to make them dimmer, however, be aware that the gold color used for the sparkle animation looks different when the LEDs are very dim.

Available Colors

The colors available by default are RED, GREEN, BLUE, WHITE, and GOLD. The LED Animation library has more colors available, however, if you wish to use them, you must also import them at the top of the file. If, for example, you wanted to add MAGENTA, you would need to change the following import.

from adafruit_led_animation.color import RED, GREEN, BLUE, WHITE, GOLD, MAGENTA

Once imported at the top, it is available for you to use in any of the animations.

Color Cycle Settings

The first animation cycles between two colors - red and green. You can change this easily by updating the following.

color_cycle_colors = (RED, GREEN)

To cycle between RED and WHITE instead, update it to the following.

color_cycle_colors = (RED, WHITE)

You can also cycle between more than two colors by adding more colors to the list.

color_cycle_colors = (RED, GREEN, BLUE, WHITE)

To change the speed in seconds at which the colors change, update the following line. Increasing the number slows down the change, decreasing it speeds it up.

cycle_speed = 0.5

Sparkle Settings

The sparkle animation defaults to GOLD. You can change this by updating the following.

sparkle_color = GOLD

To change the sparkle speed in seconds, update the following. Increasing it slows down the animation, decreasing it speeds it up.

sparkle_speed = 0.1

Comet Settings

There are two alternating comets. They default to WHITE and BLUE. You can change this by updating the following.

comet_one_color = WHITE
comet_two_color = BLUE

The comets display differently on the strip and the MagTag LEDs, so there are separate settings for each set of LEDs.

First, you set the speed in seconds of the comet on the MagTag LEDs, and the tail length. The speed defaults to 0.06 and the tail length defaults to 3. You can change this by updating the following.

magtag_comet_speed = 0.06
magtag_comet_tail = 3

Finally, you set the speed in seconds of the comet on the strip, and the tail length. The speed defaults to 0.03 and the tail length defaults to 15. You can change this by updating the following.

strip_comet_speed = 0.03
strip_comet_tail = 15

That's all there is to customising your MagTag CircuitPython Smart Holiday Lights!

This guide was first published on Dec 02, 2020. It was last updated on Nov 24, 2020.

This page (Code) was last updated on May 19, 2023.

Text editor powered by tinymce.