Built-in

Several animations are included in the module to cover some basic operations and serve as examples to get you started writing your own animations.

on

This simply turns all channels on every LED to maximum.

def anim_on(array: baseArray, cancel: threading.Event, **kwargs: t.Any) -> None:
    """
    Turns on the array
    """
    for i in range(array.count):
        array.setPixel(i, 0xFFFFFFFF)
    array.show()

Here we are just iterating over all the LEDs in the array and setting their RGBW values to maximum. array.count tells us how many pixels are in the array.

off

This does the same the operation as on but sets all channels to 0 on each pixel.

set.brightness

This sets the brightness value for the array and shows how to use an argument.

def anim_set_brightness(
    array: baseArray, cancel: threading.Event, **kwargs: t.Any
) -> None:
    """
    Sets the array brightness
    """
    brightness = kwargs.get("brightness", None)

    if brightness is None:
        log.warn("Missing argument 'brightness'")
        return

    array.setBrightness(int(brightness))
    array.show()

As you can see above we are verifying that we got the brightness argument. No argument checking is done by the LED module when calling animations, you must do this in the animation function.

Example message to trigger this animation:

{
    "anim": "set.brightness",
    "brightness": 128
}

set.array

Allows you to set the entire array to a specific color. Repeat values other than 1 have no effect. Color values can be provided as a list, a hex color, or the individual components.

# As list of components
    "color": [red, green, blue, white]

# As hex string (prefix '#' or '0x')
    "color": "#RRGGBB" # or "#WWRRGGBB"

# As color components, all optional with default 0
    "red": 255,
    "green": 255,
    "blue": 255,
    "white": 255

set.pixel

Allows you to set a pixel or range of pixels to the specified color. Color arguments are the same as set.array, the pixel argument may be a single pixel index, a range as string, or a list of indices, ranges, 2-tuples of [start, count], or any combination thereof.

# single index
    "pixel": 2

# range string
    "pixel": "4-6"

# list
    "pixel": [
        2,      # pixel 2
        "4-6",  # pixels 4, 5 and 6
        [10, 5] # pixels 10, 11, 12, 13, and 14
    ]

fade.on

Same as on animation, but fades each pixel from its current color to fully on. By providing the optional argument duration you can specify the length of the animation in fractional seconds, the step for each channel and frame length will be adjusted to fit the animation into the specified amount of time. If duration is not provided the animation will run with a frame count equal to the largest difference for any color channel in the entire array and the minimum frame length.

fade.off

Same as off animation but fades each pixel from its current color to fully off. See the duration argument in fade.on.

fade.brightness

This animation is the same as set.brightness but will fade the brightness to the new value. See the duration argument in fade.on.

fade.array

This sets a new color for the entire array, the same as set.array, but will fade each pixel from its current color to the new one. See the duration argument in fade.on.

fade.pixel

This sets a new color for the specified pixels, the same as set.pixel, but will fade each pixel from its current color to the new one. See the duration argument in fade.on.

test.order

This animation is used to help determine the byte order for the colors used by your LEDs. To use it, set your color order to 'RGBW' and trigger this animation via MQTT. It will turn on 10 pixels, if the color order is actually RGBW you will see one red, two green, three blue, and four white. If this is not what you see, then the number of pixels of each color tell you where in the color order that color goes.

Ex. If you have 1 green, 2 red, and 3 blue pixels on, then the color order is GRB.

test.array

This is an animation used to test the entire array. It draws a rainbow across the entire array and slides the colors along the array. It then quickly fades on then off the white channel, if present.

# fade white up then down
j, step = 1, 1
array.brightness = 255
while not cancel.is_set() and j > 0:
    for i in range(array.count):
        array.setPixelColorRGB(i, 0, 0, 0, j)
    array.show()
    time.sleep(0.01)
    j += step
    if j > 32: step = -1

array.anims["off"](array, cancel)

In the above excerpt we can see that each step is checking if cancel.is_set(). If you have an animation that is not a single step like the on or off animations, you need to check for it being cancelled. If cancel.is_set() returns True, your animation should stop what it is doing and return.