FastLEDHub allows you to manage all of your FastLED sketches on the ESP8266 and ESP32 with minimal changes to your existing code. It requires little knowledge about the ESP8266/ESP32 platform making it an ideal playground for beginners getting started with FastLED animations.
- Control multiple animations via an intuitive web interface
- Adjust brightness and animation speed globally
- Add widgets like color pickers or sliders to control complex animations
- Alarm: Be woken up to an animation slowly fading in
- Sunset: Automatically fade in an animation when the sun sets at your location
- Control animations and brightness using hardware inputs
- Incorporate audio spectrum data into your animations
- Control animations using HTTP requests for easy automation
- ArduinoJson ≥ 7.0
- ESPEssentials ≥ 2.1
- FastLED
- LinkedList
- WebSockets
- WiFiManager ≥ 2.0
- Open the Arduino IDE
- Navigate to "Sketch" → "Include Library" → "Manage Libraries..."
- Search for
FastLEDHuband install the desired version
- Make sure you have installed the dependencies above
- Download the desired version from the releases page
- Extract the contents of the downloaded zip file
- Rename the extracted folder to
FastLEDHub - Move this folder to your libraries directory
~/Arduino/libraries) - Restart your Arduino IDE
cd ~/Arduino/libraries
git clone https://github.com/srwi/FastLEDHub.gitTo update to the latest version of the library
cd ~/Arduino/libraries/FastLEDHub && git pullUsing FastLEDHub to manage your FastLED animations requires mainly four steps:
- Creating the main sketch to initialize your lightstrip with FastLEDHub
- Creating an animation or modifying an existing sketch to be compatible with FastLEDHub
- Registering your animations in the main sketch
- Uploading the web interface files to the flash storage
#include <FastLEDHub.h>
#define NUM_LEDS 100
#define LED_TYPE WS2812B
#define LIGHTSTRIP_PIN 5
CRGB leds[NUM_LEDS];
void setup()
{
FastLEDHub.initialize("Project Name");
FastLEDHub.addLeds<LED_TYPE, LIGHTSTRIP_PIN, GRB>(leds, NUM_LEDS);
}
void loop()
{
FastLEDHub.handle();
}Change NUM_LEDS, LED_TYPE and LIGHTSTRIP_PIN according to your hardware configuration. You may notice that this is not different than setting up a regular FastLED sketch apart from using FastLEDHub instead of FastLED.
Note: By default FastLEDHub will apply gamma correction to the brightness value. To disable this behavior call FastLEDHub.initialize("Project Name", false) instead.
Create a new animation file Animations/ExampleAnimation.h:
#pragma once
#include <FastLEDHub.h>
extern CRGB leds[];
class ExampleAnimation : public Animation
{
public:
using Animation::Animation;
// add variables and other functions if needed
void reset()
{
// set initial state variables
}
void loop()
{
// animate leds
}
};While creating your animation proceed as you usually would with FastLED by defining the reset and loop functions. reset will be called each time an animation gets started. Use this function to reset the state variables of your animation to its starting values. It will not be called when resuming the animation from the paused status. loop will be called repeatedly as long as the animation is running.
Keep in mind the following important differences to just using FastLED:
- The regular
setupfunction is calledresetto emphasize its purpose. - Since
ledshas already been defined in the main sketch, simply indicate its existence withextern CRGB leds[]. - Within your animation use
FastLEDHub[0].size()instead ofNUM_LEDSto get the number of leds. If you are using multiple lightstrips change the index accordingly. - Every time you may want to use
FastLEDuseFastLEDHubinstead. SinceFastLEDHubinherits fromFastLEDall member functions will be available just like before. FastLEDHub just adds some stuff on top of that.
If you want to convert an existing FastLED sketch (e.g. from atuline/FastLED-Demos), so it can be handled by FastLEDHub, generally those are the necessary changes you have to perform. Have a look at the examples for further insights.
In your main sketch include your animations and register them at the end of the setup function:
#include "Animations/ExampleAnimation.h"
...
FastLEDHub.registerAnimation(new ExampleAnimation("Example animation name"));The animation name can be any unique string and will be used to identify animations in the web interface.
To be able to access the web interface, several files have to be uploaded to the flash storage. They are located within the data folder inside FastLEDHub's library folder. To upload those files there are two easy options:
- Copy the whole
datafolder into your sketch directory and upload the files using the Arduino filesystem uploader (ESP8266, ESP32). - After the sketch has been flashed to the device upload each file within the
datafolder individually by accessinghttp://<device-ip>/edit.
FastLEDHub allows you to register multiple color pickers to use as parameters for your animations. This allows you to integrate custom colors, gradients and more.
To add a color picker use
FastLEDHub.registerColorPicker(new ColorPicker("Primary Color", CRGB(255, 0, 0)));
FastLEDHub.registerColorPicker(new ColorPicker("Secondary Color", CRGB(0, 255, 0), "paint-bucket"));Within the web interface FastLEDHub uses Bootstrap icons to allow you to further differentiate between color pickers. Here paint-bucket refers to the respective icon class.
To access those colors within your animation use
CRGB primaryColor = FastLEDHub.getColorPicker("Primary Color")->value; // access by name
CRGB secondaryColor = FastLEDHub.getColorPicker(1)->value; // access by indexYou can add custom numeric sliders of type int16_t to adjust variables of animations dynamically. FastLEDHub automatically adds two sliders for brightness (0-255, default: 127) and animation speed (0-255, default: 127). Both of these fixed sliders have been integrated tightly into FastLEDHub and don't require any further attention. By default changing the brightness will apply gamma correction automatically. Adjusting the speed will affect the effective delay of FastLEDHub.delay() to speed up or slow down animations. To prevent this explicitly use FastLED.delay().
To add more custom sliders simply register them in the main sketch via
FastLEDHub.registerSlider(new Slider("Hue", 0, 359, 180, 1));
FastLEDHub.registerSlider(new Slider("Saturation", 150, 255, 200, 1, "palette"));Again "palette" refers to an optional Bootstrap icon and the slider name can be any unique string identifying the slider in the web interface.
To access custom slider values inside of your animation use
int16_t hue = FastLEDHub.getSlider(2)->value; // access by index
int16_t saturation = FastLEDHub.getSlider("Saturation")->value; // access by nameRemember: Since FastLEDHub comes with two pre-defined sliders Brightness and Speed the first custom slider will have index 2.
FastLEDHub supports a potentiometer for brightness adjustments and push buttons to play/pause and cycle through animations. They have to be specifically enabled with
FastLEDHub.enablePotentiometer(potentiometerPin);
FastLEDHub.enableToggleButton(togglePin);
FastLEDHub.enableCycleButton(cyclePin);Setting up an alarm in the web interface will fade in a user defined animation over any period of time to wake you up in the morning. You can optionally set a different animation to be started after the fade in period has ended (i.e. full brightness has been reached).
Similarly the sunset feature will fade in an animation as soon as the sun sets at your location. Please configure latitude, longitude and time zone in the web interface beforehand.
FastLEDHub-AudioViz allows you to send audio spectrum data from a Windows audio device to your ESP32/ESP8266. The transmitted data consists of 16 bins corresponding to different frequency ranges in the audio spectrum. Data is transmitted via a websocket connection and can be used by accessing the FastLEDHub.spectrumData array from within your animation:
uint8_t lowFrequencies = FastLEDHub.spectrumData[0];
uint8_t highFrequencies = FastLEDHub.spectrumData[SPECTRUM_LENGTH - 1];SPECTRUM_LENGTH defines the number of bins (16). The Spectrogram example shows one way to use the spectrum data in your animations.
Most functions can be triggered via HTTP requests:
- Begin animation by name:
http://<device-ip>/begin?animation=<animation-name> - Begin animation by index:
http://<device-ip>/begin?index=<animation-index> - Stop animation:
http://<device-ip>/stop - Pause animation:
http://<device-ip>/pause - Resume animation:
http://<device-ip>/resume - Toggle animation:
http://<device-ip>/toggle - Restart animation:
http://<device-ip>/restart - Trigger sunset:
http://<device-ip>/sunset - Trigger alarm:
http://<device-ip>/alarm - Reset device:
http://<device-ip>/reboot
FastLEDHub is licensed under LGPL-2.1 and uses the sunrise-sunset.org api to retrieve sunset times.