FFX - FastFX library

<a id="markdown-ffx---fastfx-library" name="ffx---fastfx-library"></a>

Table of Contents

<a id="markdown-table-of-contents" name="table-of-contents"></a>

<!-- TOC depthfrom:2 withlinks:true -->

• Table of Contents
• Intro
• Version History
• Overview
  • Dependency
• Model
• Tutorial & Examples
  • FirstLight
    • Cycle and Phase
    • Initialization
    • Speed and Cross-fade
  • FirstLight 2
    • MovementType
    • Color
    • NamedPalettes
  • FirstLight 3
    • Segments
    • Overlay Effects
    • Timers

<!-- /TOC -->

Intro

<a id="markdown-intro" name="intro"></a>

Thanks for checking out FFX. This project grew out my desire to have a single code-base for several different LED Strips I have installed in various locations around my home. My goal was to have a single firmware image that could be downloaded on every controller, yet have the ability to change the colors/effects/etc. independently. That goal has been realized in a forthcoming framework that utilizes MQTT, JSON and a message based system for configuration and control of individual nodes (LED Controllers, sensors, relays, etc). The FFX library is the foundation for the LED controller used in that architecture.

The examples in the following sections illustrate the basics, but don't touch on everything. All of the coding and development was done on NodeMCU ESP8266 boards. While I haven't tested on anything else, outside of the FastLED initialization and pin selection, it doesn't do anything that is processor dependent, so it should run just as well on other platforms.

Final Note - The examples included in the framework are optimized for WS2811 strips (12v 3-LEDs per pixel). Some of the default parameters may need to be tweaked slightly to look best on other strip configurations.

Complete Documentation is available here: https://gmoehrke.github.io/FastFX

Version History

<a id="markdown-version-history" name="version-history"></a>

v1.0.0

• Initial release

v1.1.0

• Moved overlay effects to FFXSegment so can have multiple overlays running in parallel
• Added purple and teal named palettes
• Added CRGB* parameter to many of the virtual event handler methods in FFXBase
• Added overlay effect example ZipOverlayFX

Overview

<a id="markdown-overview" name="overview"></a>

FFX is an Arduino library that for creating LED Strip effects and animations. The principle idea behind the library is to provide a set of reusable classes/objects to create and display multiple colors/animations/etc. consistently in any sketch. Effects are written as classes/subclasses and displayed by a common controller object. By defining effects as objects, FFX is able to provide capabilities that are common to all effects without the need to custom code them for each individual effect. These capabilities include:

• Automatic crossfade between "frames" - useful for smoother transitions in slower moving sequences.
• Automatic crossfade between effects - gradual fade between effects when changing from one effect to another
• Segments - Multiple effects shown in different segments of the same Strip
• Transparency - One effect shown over the top of another with variable transparency (while both continue to animate)
• Common Color/Palette Management - Color object/interface to change the look of effects without custom coding each color/combination
• Independent timing - Each effect maintains its own independent Timer
• Overlay Sequences - Brief animation sequences that can be show over the top of looping effects (with variable transparency). Useful for indicating events, transitions, etc.
• Auto-faders for dimming and transparency - allows for smooth transitions when changing brightness and/or transparency levels. Timing can be set independently for each.

Dependency

<a id="markdown-dependency" name="dependency"></a>

The FastFX library requires the FastLED library: https://github.com/FastLED/FastLED. Users attempting to use this library should have a basic understanding of FastLED and have the library installed and working (version 3.3 or greater).

The library also makes use of 2 timer classes (StepTimer, FlexTimer). These are included in the repository, but may be released as a separate library at some time in the future.

Model

<a id="markdown-model" name="model"></a>

The programming model for using FastFX differs slightly from coding directly with FastLED. The following is a brief description of the classes needed to create a sketch using FastFX:

• FFXBase - Each effect is written as a subclass of the FFXBase class. FFXBase has its own timing parameters that determine how many milliseconds each "frame" will last. The smaller the interval, the faster the animation. FFXBase provides two virtual methods that may be overridden. The most important is the WriteNextFrame() method. This method is used to make changes to a FastLED CRGB array (*CRGB[]) that represents the pixels to draw. The FastFX framework includes several pre-built effect classes, including the default SolidFX class, which represents a single static color (see FXXCoreEffects.h)

• FFXSegment - A single LED strip is represented by a set of one or more segments. Each strip contains a Primary segment, which represents the entire strip. If effects will only be displayed along the entire strip, this is the only segment that needs to be present. If multiple effects are desired, then additional secondary segments may be defined. These segments may each have a different effect and each has its own opacity setting (0-255, 0=100% transparent, 255=100% opaque). The secondary segments do not need to cover the entire length of the primary segment. Pixels in the primary segment will always be visible unless they are covered by a secondary segment (and the secondary segment's opacity is greater than 0).

  Each secondary segment is given a name or Tag, which is used to reference that segment on the controller. The controller provides 2 methods to access the individual segments - getPrimarySegment() and findSegment(String tag), each returns a pointer to the appropriate segment. Note that these pointers can be dereferenced safely without checking for NULLs, if an invalid segment name is specified for findSegment, a pointer to the primary segment will be returned.

  

  Each segment maintains a FFXFrameProvider object that is responsible for returning the frames to be drawn for each update. The frame provider manages the cross fading, allocating extra buffers when needed.

• FFXController - This is the main interface for the FastFX framework. Every FastFX sketch will create an FFXController object and then use that object to define segments, start/stop effects and set various other parameters (brightness, opacity, speed, etc).

Tutorial & Examples

<a id="markdown-tutorial-%26-examples" name="tutorial-%26-examples"></a>

FirstLight

<a id="markdown-firstlight" name="firstlight"></a>

Since each effect is a standalone class, creating a new one is a straightforward task. Taking from the "FirstLight" example code in the FastLED library, we will create a FastFX version and see how we gain additional functionality with FastFX. First we'll construct the effect class, which is always a descendant of FFXBase:

class FirstLightFX : public FFXBase {
  public:    
    // Constructor - provides defaults for interval, minInterval, and maxInterval
    FirstLightFX(uint16_t initSize) : FFXBase( initSize, 10UL, 10UL, 100UL ) {
      // currColor holds the FFXColor object used to manage colors in effects - this is a
      // simple single-color effect using RGB colors, so we set the mode to singleCRGB
      currColor.setColorMode( FFXColor::FXColorMode::singleCRGB );
      // then supply it the color
      currColor.setCRGB( CRGB::White );
      // effect is running on a segment of the strip.
    }

    // Override initLeds - this method is called only once, right before the first frame is drawn
    // Note that anything done here is not "shown" until after the first call to writeNextFrame()
    virtual void initLeds( CRGB *bufLeds ) override {
      // Clear the field
      fill_solid( bufLeds, getNumLeds(), CRGB::Black );
    }

    // Override writeNextFrame - this is what is called for each change.  Note that the controller
    // will only call this once for each frame, so we don't need to track anything about the Timing
    // or coordination with other effects...just write the frame data into the passed CRGB array
    virtual void writeNextFrame( CRGB *bufLeds ) override {
      // fade any lit pixels to leave a trail behind the moving colored pixel
      fadeToBlackBy( bufLeds, numLeds, 50 );
      // set the next pixel to the current value in our FFXColor object (white, in this case)
      bufLeds[getCurrPhase()-1] = currColor.getCRGB();
    }
};

Cycle and Phase

<a id="markdown-cycle-and-phase" name="cycle-and-phase"></a>

Note the use of getCurrPhase() here. All effects have running counters for Phase and Cycle. The Phase counter starts at 1, and increments for each step until it reaches the number of pixels covered by that effect. This is considered one cycle. Once a cycle is completed, the phase is reset to 1. The getCurrCycle() method returns the count of how many times this has been repeated. For an effect running at an interval of 10 (milliseconds) with 100 pixels, a single phase will take 10 milliseconds, wh