Here’s a solution to a niche problem: what do you do if you have an animation written for the Adafruit NeoPixel library but want to use some of the more advanced features of the FastLED library?

In the past that would mean rewriting a significant portion of your code! You would need to research the corresponding FastLED command for every Adafruit NeoPixel function, then modify your program line by line. This requires a working understanding of how both libraries work and how LED data is managed and manipulated.

Now the answer is simple: you can use the FastLED NeoPixel library!

What is this?

The FastLED NeoPixel library is a wrapper around the FastLED library which gives it a similar structure to the Adafruit NeoPixel library. By replacing the Adafruit NeoPixel library in your code with the FastLED NeoPixel library, you can gain all of the benefits of FastLED without having to rewrite your animations!

To clarify: you do not need this library to write to NeoPixel LEDs using FastLED. FastLED supports NeoPixel (WS2812B) LEDs out of the box. This library just makes the programming interface for FastLED similar to the Adafruit NeoPixel library.

You also do not need this library if you are just getting started with addressable LEDs and don’t have existing code. If you are writing new code it’s better and faster to write in the format native to the library you’re using. I’m probably biased, but I recommend starting with the FastLED library.

You might want to use this if you already have existing Adafruit NeoPixel code or animations written for your project and want to seamlessly switch to the FastLED library to take advantage of features such as faster animations, dithering, non-destructive brightness, static memory allocation, and more. Because of this library you can get all of those features “for free” without needing to rewrite your code!

This library also lets you mix and match animation types. You can use an animation written for Adafruit NeoPixel alongside an animation written for FastLED without having duplicate copies of the LED data in memory. Neat, huh?

Using the Library

The library can be installed using the .zip file downloaded from GitHub or through the Arduino IDE libraries manager (search for “FastLED NeoPixel”). You must also install both the FastLED library and the Adafruit NeoPixel library.

I recommend trying one of the library examples (File -> Examples -> FastLED NeoPixel) to test that everything is working properly before modifying your code.

To switch your code over to FastLED NeoPixel, replace the #include statement for the library at the top, and then change the strip declaration to use FastLED_NeoPixel instead of Adafruit_NeoPixel:

Note that the FastLED_NeoPixel class definition uses template arguments and not function arguments for the LED count, pin number, and strip color order (<> before the object name instead of () after the object name). This is because of FastLED’s necessity for compile-time constants. Your code should match the format of the lines above.

And that’s it! Compile and upload the new version and everything should be running with the new library. I did say it was easy, didn’t I?

If the code doesn’t compile, you may have used one of the unimplemented functions. See the “Limitations” section below for more information.

New Functions

There are several new functions on top of the original Adafruit NeoPixel ones, related to how the internal FastLED data is stored and managed. This includes a function to get the CRGB array pointer (getLeds()), a function to get the CLEDController object pointer (getController()), and a function to get a packed uint32_t value for a given CRGB color (static Color()).

For fun I also added a setBlendWhite() function which will blend any RGBW color commands into the RGB colorspace. Simple RGBW animations should work with this option set, although animations that read from the white channel of the strip buffer will not work correctly.

For a full breakdown of the new functions and how they work, see the documentation.

Limitations

While the library is as comprehensive as possible it isn’t a perfect replacement. Due to the way the FastLED library uses compile-time constants for optimization, the run-time functions from Adafruit NeoPixel to change the strip data pin, strip length, and strip color order do not work and are unimplemented.

Because of differences in how the FastLED and Adafruit NeoPixel libraries treat color order in the underlying data, the getPixels() function to retrieve the color data array may not behave as expected. If your animation uses this function it may need to be rewritten.

Download

The library can be downloaded from GitHub or through the Arduino IDE libraries manager.

I hope someone out there finds it useful. If you do end up using this in your project, drop a comment below!


Leave a Reply

Avatar placeholder

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Would you like to know more?