neopixel-animate

neopixel-animate is a small flexible micropython framework for easily creating animations to run on NeoPixel arrays. neopixel-animate has been tested to run on the ESP8266 port of micropython and should run on other boards that support micropython.

Getting Started

This project includes an Animator Base class and multiple animation classes that add individual animations. The Animator Base and animation files can be found in the src directory. Each animation is a separate python file. This allows you to save space on your device by only loading the animations you use.

Loading files

To get started, you will need to load animator_base.py and any animation files you plan to use onto your device. They should reside in the same directory as your main python script. Pushing files to your device can be done with whatever tool you normally to move files to your micropython board (ex. Ampy).

Using Animations

Using animations in your main script is easy. Check out the examples directory for specific animation examples.

1. Import the specific animation(s) you want to use in your script.
2. Initialize a NeoPixel Object.
3. Initialize a animation and pass it the NeoPixel object you created as well as any other arguments. The required arguments will differ slightly from one animation to another. Check the examples or the animations README for more details.
4. To start the animation call start() on the animation object you created.
5. To stop the animation call stop().

Known Issues (READ THIS!)

Running animations can interfere with file uploads

Due to the behavior of the timers used to update the animations in the background, leaving animations running can cause reliability issues with file uploads and cause difficulty accessing the REPL. It is recommended that that you catch exceptions and stop all running animations. This allows file uploads to stop running animations and allows the user to use Ctrl-C to access the REPL. See the examples directory for how this can be done.

Creating New Animations

The Animator Base

The 'Animator Base' is the base class for al animations. It servers two main purposes.

1. It provides functions to start and stop the animation.
2. It also calls the update function at predefined intervals. This update function should be overridden by each animation. Any animation updates should be done in this update function. The time interval that this update function runs at can be configured by setting the period argument to the base __init__. The default interval is every 10ms.

Creating a new animation is relatively simple. A great starting point is to copy the bare_minimum.py script in the animations directory. This files acts as a starting template you can modify to create your own animation. Follow the steps below to modify the bare minimum template into your own animation.

1. Copy the bare_minimum.py and rename it to the name of your animation.
2. Open up the template file you just renamed. You can see that the class already imports and extends AnimatorBase.
3. Rename the class name to the name of your animation.
4. Modify the __init__ function. The np argument is required. You can add any other arguments you need for your animation. Some examples of additional arguments might be colors or speeds. At the end of your __init__ function you must call super().__init__(np) to pass the NeoPixel object to the animator base.
5. Optionally, you can also pass a period argument to the animator base __init__. This period defines how often the update function is called. This argument must be an integer and is in milliseconds.
6. Finally, fill in the update function. This function is where you make updates to the NeoPixels. This function will be called by the base automatically. When you want to display a new pattern be sure to call np.write().

Things to keep in mind

• Try to keep the update function short because it does interrupt the user code. Setting it to run too frequently or taking too long to update your animation can impact performance.
• Caution should be used if you override the start or stop functions in your animation. It may cause user's code to break.
• If you are trying to turn off LEDs, you should check the bpp of the NeoPixel object that is passed into the animation. Hardcoding (0,0,0) can have unexpected results for users with RGBW LEDs. Ex: tuple([0] * self.np.bpp) generates an 'off' color for both RGB and RGBW LEDs.