The fastled_helper library provides some “wrapper” functions around FancyLED that can simplify bringing over existing projects and data from FastLED.
This is imported separately and in addition to adafruit_fancyled:
import adafruit_fancyled.adafruit_fancyled as fancy import adafruit_fancyled.fastled_helpers as helper
Some things don’t require the helper functions at all, just some formatting changes to conform to Python syntax. For example, consider this 16-element RGB palette from one of the FastLED Arduino examples. Each palette entry is a single “packed” RGB value:
// Rainbow colors with alternatating stripes of black
#define RainbowStripesColors_p RainbowStripeColors_p
extern const TProgmemRGBPalette16 RainbowStripeColors_p FL_PROGMEM =
{
0xFF0000, 0x000000, 0xAB5500, 0x000000,
0xABAB00, 0x000000, 0x00FF00, 0x000000,
0x00AB55, 0x000000, 0x0000FF, 0x000000,
0x5500AB, 0x000000, 0xAB0055, 0x000000
};
In FancyLED for CircuitPython, the palette data itself can be kept exactly the same, but it’s wrapped up in a Python list (surrounded in [square brackets]). None of the “PROGMEM” stuff is needed:
RainbowStripeColors = [
0xFF0000, 0x000000, 0xAB5500, 0x000000,
0xABAB00, 0x000000, 0x00FF00, 0x000000,
0x00AB55, 0x000000, 0x0000FF, 0x000000,
0x5500AB, 0x000000, 0xAB0055, 0x000000]
Meanwhile, other FastLED capabilities simply aren’t present in FancyLED, even with helper functions. Color by name (such as “CRGB::DarkBlue” in FastLED) are not currently supported in FancyLED. Palettes must be specified numerically.
Gradient Palettes
Here’s how a gradient palette would be specified in FastLED for Arduino, and it’s converted to a “regular” palette (16 elements in this case) simply with an assignment:
DEFINE_GRADIENT_PALETTE( heatmap_gp ) {
0, 0, 0, 0, //black
128, 255, 0, 0, //red
224, 255,255, 0, //bright yellow
255, 255,255,255 }; //full white
CRGBPalette16 myPal = heatmap_gp;
We can keep the list of numbers itself exactly the same with the FancyLED helpers, but the operations around it are changed.
First, the gradient palette data must be declared as a Python bytearray using the bytes() keyword…and the list itself is in both parenthesis and square brackets.
Second, we call loadDynamicGradientPalette(), passing the bytearray and desired palette length (in FastLED this is traditionally 16, 32 or 256, but in FancyLED can be any length, RAM permitting). This is slightly different from the same function in FastLED, where the second argument is a preallocated destination color palette rather than a list length):
heatmap_gp = bytes([
0, 0, 0, 0,
128, 255, 0, 0,
224, 255, 255, 0,
255, 255, 255, 255])
palette = helper.loadDynamicGradientPalette(heatmap_gp, 16)
Reading Colors From Palettes
Although the palette concept is similar between the two libraries, how things are indexed is a little different.
FastLED palettes typically have 16, 32 or 256 elements. But rather than a floating-point range, they use a fixed-point integer scale. Fetching “color 0” from a FastLED palette will return the first entry, 16 returns the second palette entry, 32 is the third and so forth. For values between these, an interpolated color between the two nearest palette entries can be returned…for example, an index of 8 will return a color about midway between the first and second palette entries. So, a 16-element palette will expect a range from 0 to 255 (values above 240 will “wrap around” to the first color when interpolating), 256-element palettes expect a range of 0 to 4095.
color = helper.ColorFromPalette(palette, index, brightness, blend)
First two arguments — palette and index — have been explained above.
Third argument is a brightness adjustment from 0 (minimum) to 255 (maximum). This is optional…the default value will be 255 (full brightness). Whatever LED library you’re using (e.g. NeoPixel) will usually have its own brightness setting, which is compounded (e.g. if 50% brightness in both libraries, the result will be 25% bright). If using FancyLED’s gamma controls, it’s best to handle brightness there and leave everything else at full brightness.
Fourth argument is a flag to enable (True) or disable (False) color blending for values between multiples of 16. Default is False…pass True to enable blending between palette indices.
Return value is a CRGB color, which can then be handled with other FancyLED functions.
color2 = applyGamma_video(color1, gamma_red, gamma_green, gamma_blue, inplace)
This is simply a wrapper around FancyLED’s gamma_adjust() function to give it a similar syntax to FastLED. It function performs gamma correction (making brightness gradients appear more uniform) on a single brightness value, a single CRGB or CHSV color, or a list of CRGB or CHSV colors.
In the single-value case, only the value passed and the first gamma value are used; any other arguments are ignored. If no gamma value is specified, the default curve (2.5) will be used.
In the CRGB, CHSV, or list cases, separate red, green and blue gamma values can be specified. If only a single gamma value is supplied, this will be used across all three color components. If no gamma values are given, the default value (2.5) will be used.
Also in the CRGB/CHSV and list cases, the last argument — inplace — determines whether the value passed in will be modified “in place” (overwriting the original value(s) in that tuple or list) (True), or if the original data is left as-is and a new tuple or list (with gamma correction applied) is returned (False).
The color returned is always CRGB (or a list of CRGBs), even if the input was CHSV.
napplyGamma_video(n, gamma_red, gamma_green, gamma_blue)
Similar to the above function, but always modifies data in-place. For compatibility with FastLED code that uses the function of this name rather than the “inplace” flag.
hsv2rgb_spectrum(hue, saturation, value)
Given hue, saturation and value, returns an equivalent CRGB color. Roughly equivalent to the same function in FastLED.
Accepts three arguments: hue, saturation and value, each in the range 0 to 255.