Skip to content

Commit c17f47b

Browse files
stnklstnkl
committed
Update README.md
1 parent fbf0497 commit c17f47b

File tree

1 file changed

+189
-50
lines changed

1 file changed

+189
-50
lines changed

‎README.md‎

Lines changed: 189 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,66 +1,205 @@
11
# FastLED Manager
22

3-
Control multiple FastLED lightstrip animations on the ESP8266 without reuploading and more...
3+
[![MIT license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/stnkl/EverythingToolbar/blob/master/LICENSE)
44

5-
![FastLEDManager web app screenshot](screenshots/screenshot.png "FastLED Manager web app")
5+
FastLEDManager allows you to manage all of your FastLED sketches on the ESP8266 with minimal changes to your existing code. FastLEDManager is compatible with most of the demo sketches at https://github.com/atuline/FastLED-Demos. It requires minimal knowledge about the ESP8266 platform making in an ideal playground for beginners getting started with FastLED animations.
66

77
## Features
88

9-
- Start/stop/pause multiple animations
10-
- Set custom static color
11-
- Set animation speed and brightness
9+
- Control multiple animations via an intuitive web interface
10+
- Use hardware inputs to cycle through animations and adjust brightness
11+
- Adjust the animation speed globally
12+
- Select any constant color via the web interface
13+
- Define custom numeric sliders to parameterize your animations
1214
- Alarm: Be woken up to an animation slowly fading in
1315
- Sunset: Automatically fade in an animation when the sun sets at your location
14-
- Compatible with [ha-bridge](https://github.com/bwssytems/ha-bridge) via [http requests](https://github.com/stnkl/FastLEDManager/blob/master/Webserver.cpp)
16+
- Control animations using HTTP requests for easy automation
17+
18+
## Web interface
19+
20+
![FastLEDManager web app screenshot](screenshots/screenshot.png "FastLED Manager web app")
21+
22+
## Installation
23+
24+
### Library dependencies
25+
26+
- ArduinoJson
27+
- LinkedList
28+
- WebSockets
29+
- FastLED
30+
- ESPEssentials
31+
- WiFiManager (≥ 2.0.0)
32+
33+
<!--
34+
### Official releases via the Arduino IDE v1.8+
35+
1. Open the Arduino IDE
36+
2. Navigate to _"Sketch"_ &#8594; _"Include Library"_ &#8594; _"Manage Libraries..."_
37+
3. Search for `FastLEDManager` and install the desired version
38+
-->
39+
40+
### Manual Installation
41+
42+
1. Make sure you have installed the dependencies above
43+
2. Download the desired version from the _"[releases](https://github.com/stnkl/FastLEDManager/releases)"_ page
44+
3. Extract the contents of the downloaded zip file
45+
4. Rename the extracted folder to _"FastLEDManager"_
46+
5. Move this folder to your libraries directory. (under Windows: `C:\Users\<username>\Documents\Arduino\libraries\`)
47+
6. Restart your Arduino IDE
48+
49+
### Using Git
50+
51+
```
52+
cd ~/Arduino/libraries
53+
git clone https://github.com/stnkl/FastLEDManager.git
54+
```
55+
56+
To update to the latest version of the library
57+
58+
```
59+
cd ~/Arduino/libraries/FastLEDManager && git pull
60+
```
1561

16-
## Requirements
62+
## Usage
1763

18-
- Arduino libraries
19-
- ArduinoJson
20-
- LinkedList
21-
- WebSockets
22-
- FastLED
23-
- ESPEssentials
24-
- WiFiManager (&ge; 2.0.0)
64+
Using FastLEDManager to manage your FastLED animations requires mainly three steps:
2565

26-
## Compile
66+
- Creating the main sketch to initialize your lightstrip with FastLEDManager
67+
- Creating an animation or modifying an existing sketch to be compatible with FastLEDManager
68+
- Registering your animations in the main sketch
2769

28-
1. Download FastLED Manager from the [releases](https://github.com/stnkl/FastLEDManager/releases) page.
29-
2. Rename the folder containing the `FastLEDManager.ino` to `FastLEDManager`
30-
3. Make sure you have installed all the above libraries (Install Arduino libraries with the Arduino IDE. Download custom libraries from github and extract them into your Arduino/libraries folder)
31-
4. Select your board and flash size (we need about 50kb of SPIFFS)
32-
5. Upload sketch
33-
6. Upload SPIFFS data using the [data upload plugin](https://github.com/esp8266/arduino-esp8266fs-plugin)
70+
### Creating the main sketch
3471

35-
## Add a new animation
72+
```cpp
73+
#include <FastLEDManager.h>
74+
#include <ESPEssentials.h>
3675

37-
- Create a new animation `ExampleAnimation.h` file in `/Animations/`
38-
```cpp
39-
#pragma once
76+
#define NUM_LEDS 6
77+
#define LED_TYPE WS2812B
78+
#define LIGHTSTRIP_PIN 5
4079

41-
class ExampleAnimation : public Animation
80+
void setup()
81+
{
82+
initESPEssentials("Project Name");
83+
FastLEDManager.initialize(NUM_LEDS);
84+
FastLEDManager.addLeds<LED_TYPE, LIGHTSTRIP_PIN, GRB>(FastLEDManager.hardwareLeds, NUM_LEDS);
85+
}
86+
87+
void loop()
88+
{
89+
handleESPEssentials();
90+
FastLEDManager.handle();
91+
}
92+
```
93+
94+
Change `NUM_LEDS`, `LED_TYPE` and `LIGHTSTRIP_PIN` according to your hardware configuration. `initESPEssentials("Project Name")` will initialize ESPEssentials which sets up all of the prerequisites for FastLEDManager. You may notice that this is not different than setting up a regular FastLED sketch apart from using `FastLEDManager` instead of `FastLED`.
95+
96+
### Adding a new animation
97+
98+
Create a new animation file `Animations/ExampleAnimation.h`:
99+
100+
```cpp
101+
#pragma once
102+
103+
#include <FastLEDManager.h>
104+
105+
class ExampleAnimation : public Animation
106+
{
107+
public:
108+
using Animation::Animation;
109+
110+
// add variables and other functions if needed
111+
112+
void reset()
113+
{
114+
// set initial state variables
115+
}
116+
117+
void loop()
42118
{
43-
public:
44-
using Animation::Animation;
45-
46-
// other functions and variables if needed
47-
48-
void reset()
49-
{
50-
// your standard reset function
51-
}
52-
53-
void loop()
54-
{
55-
// your standard loop function
56-
}
57-
};
58-
```
59-
- Include and register animation in `FastLEDManager.ino`
60-
```cpp
61-
#include "Animations/ExampleAnimation.h"
62-
63-
...
64-
65-
registerAnimation(new ExampleAnimation("Example animation name"));
66-
```
119+
// animate FastLEDManager.leds
120+
}
121+
};
122+
```
123+
124+
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.
125+
126+
Keep in mind the following important differences to just using FastLED:
127+
- The regular `setup` function is called `reset` to emphasize its purpose
128+
- Instead of creating your own `leds` array use the existing `FastLEDManager.leds`
129+
- Within your animation use `FastLEDManager.numLeds` instead of `NUM_LEDS`
130+
- Every time you may want to use `FastLED` use `FastLEDManager` instead. Since `FastLEDManager` inherits from `FastLED` all member functions will be available just like before. FastLEDManager just adds some stuff on top of that.
131+
132+
If you want to convert an existing FastLED sketch (e.g. from https://github.com/atuline/FastLED-Demos), so it can be handled by FastLEDManager, those are the necessary changes you have to perform.
133+
134+
### Registering animations
135+
136+
In your main sketch include your animations and register them at the end of the `setup` function:
137+
138+
```cpp
139+
#include "Animations/ExampleAnimation.h"
140+
141+
...
142+
143+
registerAnimation(new ExampleAnimation("Example animation name"));
144+
```
145+
146+
The animation name can be any unique string and will be used to identify animations in the web interface.
147+
148+
## Additional features
149+
150+
### Static color display
151+
152+
FastLEDManager allows you to display a static color in the web interface. It will be handled as a separate animation and will always have animation index `0`. This is important if you want to trigger animations using HTTP requests.
153+
154+
### Pre-defined and custom sliders
155+
156+
You can add custom numeric sliders of type `int16_t` to adjust variables of animations dynamically. FastLEDManager automatically adds two sliders for brightness (0-255, default: 255) and animation speed (0-255, default: 127). Both of these fixed sliders have been integrated tightly into FastLEDManager and don't require any further attention. Changing the brightness will apply gamma correction automatically. Adjusting the speed will affect the effective delay of `FastLEDManager.delay()` to speed up or slow down animations. To prevent this explicitly use `FastLED.delay()` or Arduino's standard `delay()`.
157+
158+
To add more custom sliders simply register them in the main sketch via
159+
160+
```cpp
161+
FastLEDManager.registerSlider(new Slider("Saturation", 150, 255, 200, 1));
162+
```
163+
164+
This example registers a slider with a range of `150-255` and step size `1` defaulting to the value `200`. Again the slider name `"Saturation"` can be any unique string identifying the slider in the web interface.
165+
166+
To access custom slider values inside of your animation use
167+
168+
```cpp
169+
int16_t saturation = FastLEDManager.getSlider("Saturation")->value;
170+
```
171+
172+
### Hardware inputs
173+
174+
FastLEDManager supports a potentiometer for brightness adjustments and a push button to cycle through animations. They have to be specifically enabled with
175+
176+
```cpp
177+
FastLEDManager.enablePotentiometer(potentiometerPin);
178+
```
179+
180+
and
181+
182+
```cpp
183+
FastLEDManager.enableToggleButton(togglePin);
184+
```
185+
186+
### Alarm and sunset
187+
188+
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).
189+
190+
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.
191+
192+
### Control via HTTP requests
193+
194+
Most functions can be triggered via HTTP requests:
195+
196+
- Begin animation by name: `http://<device-ip>/begin?animation=<animation-name>`
197+
- Begin animation by index: `http://<device-ip>/begin?index=<animation-index>`
198+
- Stop animation: `http://<device-ip>/stop`
199+
- Pause animation: `http://<device-ip>/pause`
200+
- Resume animation: `http://<device-ip>/resume`
201+
- Toggle animation: `http://<device-ip>/toggle`
202+
- Restart animation: `http://<device-ip>/restart`
203+
- Trigger sunset: `http://<device-ip>/sunset`
204+
- Trigger alarm: `http://<device-ip>/alarm`
205+
- Reset ESP8266: `http://<device-ip>/reboot`

0 commit comments

Comments
 (0)