Setup

LEDfx, in conjunction with the WS2812FX Arduino library, is used to create eye catching lighting effects using WS2812 programmable RGB LEDs. It is available as an Android app on the Google Play Store and as a web app hosted here on this server.

Note, if you use the web app (or the Android app outside of your local network), you'll need to configure your internet router to port-forward HTTP requests to your ESP8266. You'll likely want to change the HTTP_PORT setting in the ws2812fx_patterns_web sketch to something other then 80, so that the port-forwarding doesn't interfere with your router's built-in web interface.

You will need:

  1. a strip of WS2812 RGB LEDs
  2. an ESP8266 microcontroller
  3. the Arduino IDE and ESP8266 platform package
  4. the WS2812FX library
  5. an appropriate power supply and sundry electronic components

I'm going to assume you have some experience with the Arduino IDE, ESP8266 and WS2812 hardware. If not, Adafruit has some nice guides for their NeoPixel products and instructables.com has useful articles that describe the ESP8266/WS2812 hardware setup. Pay particular attention to Adafruit's Best Practices guide (link). It will save you some headaches.

Install the Arduino IDE and WS2812FX software as described on their web pages. We'll be using the ws2812fx_patterns_web sketch (include in the WS2812FX examples folder), so edit the WIFI_SSID and WIFI_PASSWORD settings there to suit your local network, then upload it to your ESP8266. If all is well, you should see the default scanning effect on your LEDs.



Using LEDfx

The initial LEDfx screen is where your create your devices, which represent an ESP8266/WS2812 setup. They can be separate hardware arrangements or a single arrangement for which you want to create a collection of lighting effects.



The screen shows several common elements that are used throughout the app.

  • Devices are created by touching the plus icon (+). After the device is created it will show up in the devices list.
  • Each device in the list has a drag-and-drop handle on the left, used to rearrange the devices in the list.
  • The play icon (▶) is used to upload the device configuration to the ESP8266 so you can see your design in action. If you have multiple devices, you can synchronize them by touching the Upload All icon, which will upload and start all devices simultaneously.
  • The trash can icon deletes the device from the list.

To get started, touch the plus icon to create a device.



Here you give a name and, optionally, a description of the device. You'll need to enter the IP address your ESP8266 is using on your local network, the GPIO data pin used to drive the WS2812 strip and the number of LEDs in the strip. The IP address can include a port number, otherwise the default HTTP port 80 will be used.

Note the SAVE button in the upper right. This is another common element used in the app. Pressing the SAVE button will save any changes you've made and return to the previous screen.

Now let's create a pattern by touching the plus icon.



A pattern is a collection of segments that span the length of your WS2812 strip. Like devices you give them a name and an optional description. You can set the brightness for each pattern and length of time (duration in seconds) the pattern will play before automatically playing the next pattern in the list. The "evenly distribute segments" feature will save you the trouble of manually setting the start and stop position of the LEDs in each segment of the pattern. With this checkbox checked, the pattern's segments will be evenly spread across the LED strip, i.e. if there are three segments defined, each segment will occupy a third of the LEDs in the strip.

So lets create our first segment by touching the plus icon.



Here you specify the segments position in the strip by entering the start LED position and the stop LED position. Specifying the start/stop positions is not necessary if you've checked the "evenly distribute segments" checkbox previously. Then you select one of the 50 effects bundled with the WS2812FX library, the animation speed, the colors you wish to use for the effect and whether you want to run the animation in the reverse direction.

That's it! You've created you first light show. Press the SAVE button a few times to save your segment/pattern/device. Then press the play icon to upload your creation to your ESP8266 and be dazzled. The patterns uploaded to your ESP8266 are stored in the microcontroller's EEPROM, so will persist even if it is powered off.



Firebase support

LEDfx can use Firebase for cloud storage to backup your hard work. Also, Firebase can be handy if you use LEDfx on multiple Android phones/tablets. Backup and restore your LEDfx data with Firebase and your data will always be in sync across all your Android devices.

To use Firebase go the Firebase web site and create an account, if you don't have one already. LEDfx stores a tiny amount of data, so their free "Spark Plan" provides more then enough cloud storage. You'll be storing your LEDfx data in a Firebase project, so go to the Firebase Console and click "Add a project". Enter a name for your project and select a country appropriate for your locale, then click "Create Project". Once the project is created, select it in the Firebase Console and look for a link that says "Add Firebase to your web app" and click it. There you'll see the Firebase configuration info that uniquely identifies your Firebase project. It will look something like this:



We're interested in everything between the curly braces of the config var, so copy all of that (including the curly braces). Back in LEDfx, open the Firebase page and paste your configuration info into the "Config" field.



Then enter a file name for your LEDfx data. If you have lots of different LEDfx content, you can store them all under different file names in Firebase.

That completes the Firebase setup. You should now be able to press the Backup and Restore buttons to save/load LEDfx data to/from Firebase.