ESPixelStick firmware turns an ESP8266 or ESP32 into a lighting controller

A lighting controller, not a general purpose firmware

The ESPixelStick firmware is the Arduino based firmware for ESP8266 and ESP32 platforms, and its job is control of clock-less pixels, DMX512 devices and relays depending on the hardware platform.

The scope matters. This is not an ESP32 firmware framework with a lighting module, it is a lighting controller that happens to run on an ESP. The README is explicit that although the firmware is open source and you are free to use it on the device of your choice, the code is written specifically for the ESPixelStick.

The hardware paragraph gives the reason. The ESPixelStick V3 uses a Wemos D1 Mini module and provides high current connectors, fusing, power filtering, reverse polarity protection, a differential output driver, an SD card reader and proper logic level buffering. Those are the things a WS281x output needs in order to be safe and long enough to reach the pixels, and they are the reason the code has assumptions about the board it runs on.

The README also notes that there is no pre-made ESP32 controller at this time, so it is up to the user to roll their own buffer for the WS281x output and add appropriate power connectors. A wide variety of ESP8266 and ESP32 platforms have been added to the supported devices list, 37 as of writing, all of which have artifacts created every build.

The primary language is C++, the default branch is main, the homepage is forkineye.com, and the last push was on 2026-09-22.

The protocols it speaks: E1.31, DDP, DMX512 and MQTT

The protocol support is the feature list in practice, and the README packs it into one paragraph.

For pixels, the firmware speaks E1.31, the standard for lighting data over IP, and DDP, the Display Data Protocol. The limit the README gives is tied to refresh rate: around 800 pixels for a 25ms E1.31 source rate using a single port controller like the ESPixelStick V3. That is a real engineering constraint rather than a soft warning, because the data rate per universe and the refresh interval together determine how many pixels a single serial line can carry before the refresh slips.

For DMX512, the classic serial lighting bus, the firmware drives DMX512 devices directly. Relays are supported as well, which is the bit that turns a lighting controller into a general stage controller.

For integration, there is Alexa and MQTT support for home automation systems, and MQTT is also one of the named input protocols in the repository topics alongside E1.31, sACN, WS2811 and pixels.

The xLights piece is the one worth explaining, because it is the reason the firmware is more than a bridge. On platforms with SD cards available, sequences from xLights can be uploaded for playback in either standalone or FPP Remote modes. So the controller can hold a show file and run it by itself, with no PC attached, which is what a permanent installation needs.

The full list of supported input protocols and outputs lives in the project wiki, and the repository carries the protocol documents themselves in the SupportingDocs directory, with datasheets and protocol formats.

Flashing: release archive, CI artifacts, or the browser

There are three ways to get firmware onto the device, and they differ in how much trust you place in the build.

The recommended method is to download the latest stable release and use ESPSFlashTool, which is inside the release archive, to flash a pre-compiled binary. Beta builds and release candidates are tagged as Pre-release in the releases list when they are available and ready for testing.

The second route is the CI builds. Automated builds are generated for every code push and are available as Artifact attachments on the ESPixelStick CI workflow runs, with the release archive toward the bottom of a successful run. The README notes that downloading artifacts requires being logged into GitHub.

The third is an experimental web based flash tool, hosted at a from-ct.com address on port 5000. The README says it will always have a few of the most recent CI builds available for flashing, which is a nice convenience for a device with no serial port handy, and it is labelled experimental.

If you want to compile the project yourself and modify the source, the README points at the build requirements section.

The release history in the repository record is a good reminder of the age of the stable artefacts: v4.0-beta3 from October 2021, v4.0-beta4 from November 2021, and v4.0-beta5 from December 2023. The most recent tagged build is a beta from more than two years ago, while the repository itself is being pushed to.

The hardware support split is also worth knowing before you start. ESP-01 modules, as used on the ESPixelStick V1 and V2, are no longer supported because there is not enough flash space, and v3.2 is the latest supported release for those controllers. At least 4MB of flash is required for ESP8266 platforms.

Building from source with PlatformIO, Gulp and a serial port

The recommended way to build is PlatformIO, and building from the Arduino IDE is no longer supported.

The setup sequence is a conventional Visual Studio Code and PlatformIO IDE workflow. You install Visual Studio Code, then PlatformIO IDE for it, then download or clone the repository. Node.js and Gulp are needed to build the web pages, with the instructions in the html README, and then the platform configuration file is created from its sample:

Copy `platformio_user.ini.sample` to `platformio_user.ini`.

You then open the project folder in Visual Studio Code, open platform_user.ini and define which serial port you are using for programming and monitoring your devices, select your target build environment in the status bar, where the default is Default (ESPixelStick), and use the compile and upload buttons.

The build environments are defined in platformio.ini, and the filesystem image is uploaded separately through the PlatformIO project tasks, with the important constraint that the web pages must be processed before the filesystem is built.

The repository layout shows the split between firmware and frontend. There is src/ and include/ for the firmware, html/ for the web interface with its own README, a dist/ directory holding the files used to create the binary distributions, including the binaries for flashing, ESPSFlashTool and firmware.json, and a tools/ directory. The web build is a Gulp project, with the package.json describing a Gulp based build system for the ESPixelStick web files, using gulp-concat, gulp-terser, gulp-clean-css, gulp-htmlmin, gulp-gzip and gulp-markdown-github-style, with a gulpfile.mjs as the entry point.

Input, output and service modules in the source tree

ESPixelStick is now a PlatformIO project and follows the standard PlatformIO directory structure, with all code in the relevant src and include sub-directories. Inside them are three categories of module, and the inheritance requirement is what makes the structure useful rather than decorative.

The input directory holds show input modules, which must inherit from c_InputCommon as defined in InputCommon.hpp. The output directory holds show output modules, which must inherit from c_OutputCommon as defined in OutputCommon.hpp. The service directory holds auxiliary services, and the README describes these as including non-show critical input mechanisms like FPP discovery and configuration mechanisms.

The README points at src/input/InputMgr.cpp and src/output/OutputMgr.cpp for adding modules to the system, which is the practical guide for anyone extending the firmware.

The two words in the directory names do the work here. An input module knows how to receive a particular protocol, and an output module knows how to drive a particular kind of hardware, and the common base classes in each category are the contract that the managers use to talk to them without knowing which concrete module is behind them.

The other notable directories are SupportingDocs for datasheets and protocol formats, boards/, and a tools/ directory for miscellaneous tooling. There is also generated doxygen source documentation at forkineye.github.io/ESPixelStick/doxy/, regenerated on every pipeline run, and a .doxygen/ directory in the repository. The partition layouts are visible too, as ESP8266_partitions.csv and ESP32_partitions.csv alongside an ESP32S3_InternalSD_partitions.csv, and a loader script ESP8266_loader.ld.

Configuration lives in the web interface, and it can be backed up

The configuration story is the least documented part of the README and the most useful to know about.

The device is configured through its own web interface, and the configuration backup and restore section explains how to preserve it. The current device configuration can be saved to a local drive using the Backup button on the Admin page, which results in a local file save to the default download directory. The file is named using the Device name from the device configuration page plus the ESP unique ID found on the admin page.

That is a small feature with a large consequence. A controller that runs xLights sequences from an SD card, with DMX and relays attached, holds state that is annoying to recreate. Having a named file you can keep is what makes a device portable between controllers, and the naming scheme including the ESP unique ID is what stops two backups from colliding.

The admin page is also where the ESP unique ID lives, so the same page covers both configuration and identity.

The README does not describe the rest of the configuration options in detail, so the practical route is to flash a build, open the interface and work through the admin pages. That is a fair expectation for a firmware with a web front end, and it is also the reason the project ships a whole Gulp toolchain for the pages: the configuration surface is HTML, and it is meant to be edited by a person on a phone.

The repository also carries a Changelog.md, an sdkconfig.defaults file for the ESP-IDF configuration, a platformio.ini with the build environments, a managed_components/ directory, and.ci/ and.scripts/ directories for the automation.

Editorial conclusion

Adopt the ESPixelStick firmware if you run lighting from a microcontroller and want E1.31, DDP, DMX512 and xLights sequence playback on hardware that costs a few dollars, and you are comfortable flashing firmware and configuring a web interface. Do not adopt it as a general purpose controller framework, since the code is written for the ESPixelStick and its module structure assumes a lighting use case, and check the licence situation yourself because the repository record could not classify it. Before you flash, confirm your board is on the supported list and has at least 4MB of flash, and expect to work from the Admin page rather than a config file.

Frequently asked questions

Official sources

1. forkineye/ESPixelStick on GitHub
2. Issues
3. Project website
4. README
5. Releases