This project runs on an Espressif ESP32 microcontroller. It is designed to accept incoming HTTP messages from WiFi and drives up to 4 independent channels of LED strips, strings or panels. It currently supports WS2811, WS2812b, WS2813 and WS2815 compatible LEDs (others can be used if compatible with one of these). HTTP messages sent by the web interface can also be scripted, so that displays can be automated and controlled from a host computer.
The project serves a web page for simple control and experimenting with combinations of displays and effects. The console log outputs every message sent to help with script creation. Note that message tokens can be combined in many ways, allowing much more flexibility than the web page provides.
Please refer to the following text files for detailed information:
connecting_to_wifi.txt - description of how to connect to WiFi and also OTA information.
http_cmd_reference.txt - description of HTTP messages, token functionality and channel config.
install_build_notes.txt- detailed notes for setting up the ESP-IDF + Arduino build environment.
christmas.ps1 - an example automated Powershell script, with usage instructions.
Designed to be efficient, well organized and easy to follow. Want to find the display code? It's in display.cpp. Want to trace the program flow from the start? Start in main.cpp.
The program serves a simple web page for real-time control and configuration. Also supports scripting so that a computer on the local WiFi may send HTTP commands. A script can configure complex displays not possible via the web page.
LED animation is performed in a two pass process. The first pass sets the color and brightness of each display LED as determined by the display type. The second pass operates on the results of the first pass, applying an independent brightness-based animation effect overlay.
Designed to natively support 2D arrays of pixels as well as 1D strips and strings. 2D arrays must be wired in serpentine order, either row-first or column-first. The program allows for the display to be flipped vertically and/or horizontally.
Supports 4 independent channels of LEDs, each driven by a separate GPIO. This allows each channel to use a different type of LED (eg. WS2811 vs WS2812b), and each channel can simultaneously run a different display type and effect overlay.
Supports over-the-air (OTA) flash updates. This requires initial flashing either with micro USB cable or flashing with another tool (Google search: "how to flash an ESP32 without the build environment")
Stores all configuration settings in flash which are loaded at power up. The web page acts as a subordinate in this regard - refreshing the web page will cause all settings to be reloaded from the device.
First, install the ESP-IDF environment as described here:
https://docs.espressif.com/projects/esp-idf/en/v4.4.2/esp32/get-started/index.html
This will result in a C:\Espressif folder and a shortcut.
Next, clone this git repo to your machine. cd to the root folder (you will see this README.md there).
This project uses Arduino libraries for other things, since they are simpler to use than ESP-IDF. The install process is described here: (more notes in install_build_notes.txt)
When done, you will have a /components/arduino folder containing the Arduino libs.
To configure or build/flash, you must be running the ESP-IDF environment. The install process will create an ESP-IDF shortcut; just double-click it and cd to the project's root folder.
Note: If you clone this project, it will already be configured.
To run the project's configuration menu, run idf.py menuconfig from the root folder. This creates or updates the file sdkconfig. This should not be necessary unless updating to new tool versions as the version in the repo has the correct settings.
For new projects, run idf.py set-target esp32 prior to idf.py menuconfig.
To do a first time full build, run idf.py build from the root folder. To do subsequent builds of the changes only, cd to build and run ninja.
To flash the first time, you can run idf.py -p COM# flash from the root folder, where COM# is COM3 if the board's COM port is 3. Or, from the build folder, run ninja flash. Subsequent flashing is best done by browsing to <device's local IP address>/update.
Without the build environment, Google search: "how to flash an ESP32 without the build environment" for the best method available to your situation.
Once flashed and correctly setup to connect to your local WiFi (see connecting_to_wifi.txt), you can then navigate to <device's local IP address>/update in your browser and flash using OTA, which is much easier and quicker.
Once flashed and correctly setup to connect to your local WiFi, you can then navigate to in your browser and scroll to the bottom of the web page. First, fill in the number of LED strings/strips/2D panels you plan to connect, then fill in the specifics for each channel. See http_cmd_reference.txt for details.
For the Novice:
QuinLED-Dig-Quad ESP32 board: https://quinled.info/quinled-esp32/
For the experienced DIYer:
*Driving LEDs is somewhat an art as well as science and much is written about it. There are many things that can go wrong, and very often the cause is not obvious. The need for a level shifter is one of those things. Much of the time, the 3.3v GPIO output is not enough to drive the first LED. The purpose of a level shifter is to raise the 3.3v GPIO signal to the same voltage as the LED's voltage, usually 5 or 12 volts. The need for a level shifter can sometimes be avoided by using a dummy pixel mounted within a few inches of the ESP32.