np-animation 1.0.0

A MicroPython library for driving NeoPixel animations with time functions and keyframes

np_animation

A MicroPython library for driving NeoPixel animations in a tight loop. It works like a mechanism, with time functions and keyframes, making it easy to create complex LED animations for robotics, wearables, and IoT projects.

This library provides a powerful animation framework that separates animation logic from LED control, allowing you to create smooth, time-based animations with minimal overhead. Perfect for robot lighting effects, indicator lights, and decorative patterns.

Table of Contents

• Features
• Installation
• Quick Start
• Projects & Tutorials
• Documentation
• Supported Platforms
• License
• Author

Features

• 🎨 Rich Animation Functions: Built-in effects like pulse, hue shift, knight rider, indicators, and brake lights
• ⏱️ Time-Based Animation: Smooth animations using time functions and keyframes
• 🎯 Function Matrix System: Map multiple animation functions to different LED positions
• 🚗 Vehicle Lighting: Ready-made functions for indicators, brake lights, and headlights
• 🌈 Color Utilities: HSL/RGB conversion and color manipulation helpers
• 💡 LED Control: Direct control over individual LEDs or groups
• 🔄 Keyframe Animation: Support for complex keyframe-based animation sequences
• 🎮 Dynamic Control: Pass runtime parameters to control animation behavior

Installation

On LMS-ESP32

The module should be included in the latest MicroPython firmware from https://www.antonsmindstorms.com. If not, use ViperIDE or Thonny and create a new file called np_animation.py. Copy the contents from the same file in this repository inside.

On MicroPython device using micropip from PyPI

import micropip
await micropip.install("np_animation")

Note: micropip must be available on the target board and may require an internet connection from the device.

Manual Installation

Copy np_animation.py to your MicroPython device's filesystem.

Quick Start

Basic Animation with Function Matrix

from np_animation import NPAnimation, hue_shift, switch, grb
from time import sleep_ms

# Define animation function matrix
funcs = [
    [[0, 1, 2, 3, 4, 5], hue_shift(period=5000)],  # Rainbow effect on LEDs 0-5
    [[6, 7], switch(on=grb.WHITE, off=grb.OFF, name="headlights")],  # Switchable headlights
]

# Create animation instance (default pin 24, auto-detect LED count)
npa = NPAnimation(funcs)

# Animation loop
try:
    while True:
        npa.update_leds(headlights=True)  # Update with headlights on
        sleep_ms(50)
except KeyboardInterrupt:
    npa.leds_off()

Vehicle Lighting Example

from np_animation import NPAnimation, indicators, brake_lights, switch, grb

# Create a complete vehicle lighting system
funcs = [
    [[0, 1], indicators(name="left_indicators")],   # Left turn signals
    [[10, 11], indicators(name="right_indicators")], # Right turn signals
    [[2, 3], switch(on=grb.WHITE, name="headlights")], # Headlights
    [[8, 9], brake_lights()],  # Brake lights (respond to speed parameter)
]

npa = NPAnimation(funcs, pin=24)

# In your control loop
while True:
    speed = get_motor_speed()  # Your speed function
    npa.update_leds(
        left_indicators=turn_left,
        right_indicators=turn_right,
        headlights=lights_on,
        speed=speed
    )
    sleep_ms(50)

Color Conversion

from np_animation import hsl_to_rgb, rgb_to_hsl, to_grb

# Convert HSL to RGB
rgb = hsl_to_rgb(120, 100, 50)  # Green: (0, 255, 0)

# Convert RGB to HSL
hsl = rgb_to_hsl(255, 0, 0)  # Red: (0, 100, 50)

# Convert RGB to GRB bytes for NeoPixel
grb_bytes = to_grb((255, 0, 0))  # b'\x00\xff\x00'

Knight Rider Effect

from np_animation import NPAnimation, knight_rider, grb

funcs = [
    [[0, 1, 2, 3, 4, 5], knight_rider(period=2000, width=6, color=grb.RED)]
]

npa = NPAnimation(funcs)

while True:
    npa.update_leds()
    sleep_ms(50)

Keyframe Animation

from np_animation import NPAnimation, keyframes, grb

# Define keyframes: (time_ms, [led_colors])
EMERGENCY = [
    (0, [grb.RED]*3 + [grb.OFF]*3),
    (150, [grb.OFF]*6),
    (200, [grb.RED]*3 + [grb.OFF]*3),
    (350, [grb.OFF]*6),
    (500, [grb.OFF]*3 + [grb.BLUE]*3),
    (650, [grb.OFF]*6),
    (1000, [grb.OFF]*6)
]

funcs = [
    [[0, 1, 2, 3, 4, 5], keyframes(EMERGENCY)]
]

npa = NPAnimation(funcs)

while True:
    npa.update_leds()
    sleep_ms(50)

Projects & Tutorials

See np_animation in action! Check out these project tutorials and videos showcasing real-world applications.

📝 Blog Tutorials

Creating a Knight Rider NeoPixel Animation Learn how to recreate the iconic KITT scanner effect from the Knight Rider TV series using the knight_rider() function. Includes detailed code explanation and implementation tips.

Lighting Astro Boy with a Radar Sensor Add interactive lighting to brick models using a radar proximity sensor. Astro Boy lights up only when someone waves at him, combining multiple animation effects with sensor input.

🎥 Video Tutorials

Knight Rider Animation Video Tutorial Watch the KITT scanner effect in action on a LEGO Technic car with step-by-step implementation guide.

Extreme Off-Roader LED Effects See the np_animation library in full action with complex lighting effects on an off-road vehicle build.

🔗 More Projects

Explore more NeoPixel projects and tutorials on the NeoPixel tag page at Anton's Mindstorms.

Documentation

Core Class

NPAnimation(light_funcs, pin=24, n_leds=0)

Main animation class that manages LED updates based on a function matrix.

• light_funcs: List of [led_positions, animation_function] pairs
• pin: GPIO pin for NeoPixel data line
• n_leds: Number of LEDs (auto-detected from function matrix if 0)

Methods:

• update_leds(time=None, **kwargs): Update all LEDs based on current time and parameters
• leds_off(): Turn off all LEDs

Animation Functions

All animation functions return a function that takes (time, **kwargs) and returns color data.

hue_shift(period=1000, offset=0)
Continuously shifts through the color spectrum.

pulse(color=grb.WHITE, period=5000, offset=0, min_pct=0, max_pct=100)
Pulsing brightness effect with configurable color and range.

knight_rider(period=2000, width=6, color=grb.RED)
Classic scanning effect like KITT from Knight Rider.

indicators(on=grb.ORANGE, off=grb.OFF, interval=500, name="indicators")
Blinking indicator lights with on/off control.

brake_lights(drive=grb.DARK_RED, brake=grb.RED, reverse=grb.WHITE)
Vehicle brake lights that respond to speed parameter.

switch(on=grb.WHITE, off=grb.OFF, name="switch")
Simple on/off switch controlled by a boolean parameter.

delayed_switch(on=grb.RED, off=grb.OFF, delay=2000)
Switch that turns off after a delay.

keyframes(frames)
Play a list of (time, colors) keyframes in a loop.

keyframes_dict(frames_dict, name="animation")
Switch between multiple keyframe animations at runtime.

Color Utilities

hsl_to_rgb(h, s, l) - Convert HSL (0-359, 0-100, 0-100) to RGB (0-255)

rgb_to_hsl(r, g, b) - Convert RGB to HSL

to_grb(rgb) - Convert RGB tuple to GRB bytes

from_grb(grb) - Convert GRB bytes to RGB tuple

Color Constants

grb class - Pre-defined colors in GRB byte format:

• ORANGE, BLACK/OFF/NONE, WHITE, RED, DARK_RED, BLUE, YELLOW, GREEN, CYAN, VIOLET, MAGENTA, GRAY

rgb class - Same colors in RGB tuple format

Supported Platforms

• ESP32 with MicroPython
• LEGO SPIKE Prime/Essential (with MicroPython firmware)
• LEGO MINDSTORMS Robot Inventor
• Raspberry Pi Pico/Pico W
• Any MicroPython board with NeoPixel support

License

MIT License

Author

Anton Vanhoucke