Skip to content
Firmware for the ESPixelStick
C++ JavaScript C HTML CSS
Branch: master
Clone or download

Latest commit

forkineye Merge pull request #202 from penfold42/fix201
Fix #201 send ap_timeout as integer, not string
Latest commit 2d2f512 Feb 4, 2020


Type Name Latest commit message Commit time
Failed to load latest commit information.
.vscode Fixes for v3.1 Jan 11, 2020
data Revert AP Fallback to false Mar 19, 2019
dist Fixes for v3.1 Jan 11, 2020
html Fix #201 send ap_timeout as integer, not string Jan 28, 2020
travis Fixes for v3.1 Jan 11, 2020
.gitignore Update zcpp packet layout. priority added Apr 6, 2019
.sublimelinterrc Made Renard and DMX asynchronous. Added multi-universe and 480kbps Jul 12, 2016
.travis.yml Handle effects better via MQTT Jan 9, 2019 Fixes for v3.1 Jan 11, 2020
EFUpdate.cpp Fixes for v3.1 Jan 11, 2020
EFUpdate.h Finished OTA update handling. Sep 21, 2016
ESPAsyncDDP.cpp Add DDP support - Fixes #164 May 9, 2019
ESPAsyncDDP.h Add DDP support - Fixes #164 May 9, 2019
ESPAsyncZCPP.cpp Fix ZCPP in multicast mode Mar 23, 2019
ESPAsyncZCPP.h Add ZCPP Query response Mar 23, 2019
ESPixelStick.h Fixes for v3.1 Jan 11, 2020
ESPixelStick.ino Fixes for v3.1 Jan 11, 2020
EffectEngine.cpp Effects: webUI and MQTT now use speed from 1 to 10 (fastest) Jan 15, 2019
EffectEngine.h Effects: webUI and MQTT now use speed from 1 to 10 (fastest) Jan 15, 2019
FPPDiscovery.cpp Update FPPDiscovery.cpp Aug 12, 2019
FPPDiscovery.h Add FPP discovery pings so FPP and xLights can auto-discover pixel st… Mar 26, 2019
Mode.h Travis updates. Included distribution files. Jul 24, 2018
PixelDriver.cpp Removed boolean gamma enable/disable Jan 9, 2019
PixelDriver.h Removed boolean gamma enable/disable Jan 9, 2019 Some clarifications added to the readme for those less familiar with … Mar 19, 2019
SerialDriver.cpp Fixes for v3.1 Jan 11, 2020
SerialDriver.h Fixes for v3.1 Jan 11, 2020
ZCPP.h Minimise differences to xlights Apr 12, 2019
gamma.cpp Removed boolean gamma enable/disable Jan 9, 2019
gamma.h Add brightness setting to gamma calculation Nov 15, 2017
gulpfile.js Handle effects better via MQTT Jan 9, 2019
package.json Updated Gulp and cleaned up markdown files Jan 4, 2019
wshandler.h Fixes for v3.1 Jan 11, 2020

ESPixelStick Firmware

Join the chat at Donate Build Status

This is the Arduino firmware for the ESP8266 based ESPixelStick. The ESPixelStick is a small wireless E1.31 sACN pixel controller designed to control a single strand of pixels. Pixel limitations are mostly based upon your desired refresh rate, around 680 pixels (4 universes) for a 25ms E1.31 source rate. MQTT support is provided as well for integration into home automation systems where an E1.31 source may not be present.

Since this project began, the firmware has moved beyond just pixel support for those with other ESP8266 based devices. The ESPixelStick firmware now supports outputting E1.31 streams to serial links as well. Note this is not supported on the ESPixelStick hardware, but intended for other ESP8266 devices such as Bill's RenardESP.


Being open source, you are free to use the ESPixelStick firmware on the device of your choice. The code however is written specifically for the ESPixelStick. The ESPixelStick V2 utilizes an ESP-01 module and provides high current connectors, fusing, power filtering, a programming interface and proper logic level buffering. If you're in the US and would like to purchase an ESPixelStick, they are available via Amazon. The proceeds go towards things like keeping my wife happy so I can work on this project :)


Along with the Arduino IDE, you'll need the following software to build this project:

The following libraries are required:

Extract the folder in each of these zip files and place it in the "library" folder under your arduino environment

Important Notes on Compiling and Flashing

  • In order to upload your code to the ESP8266 you must put it in flash mode and then take it out of flash mode to run the code. To place your ESP8266 in flash mode your GPIO-0 pin must be connected to ground.
  • Device mode is now a compile time option to set your device type and is configured in the top of the main sketch file. Current options are ESPS_MODE_PIXEL and ESPS_MODE_SERIAL. The default is ESPS_MODE_PIXEL for the ESPixelStick hardware.
  • Web pages must be processed, placed into data/www, and uploaded with the upload plugin. Gulp will process the pages and put them in data/www for you. Refer to the html README for more information.
  • In order to use the upload plugin, the ESP8266 must be placed into programming mode and the Arduino serial monitor must be closed.
  • ESP-01 modules must be configured for 1M flash and 128k SPIFFS within the Arduino IDE for OTA updates to work.
  • For best performance, set the CPU frequency to 160MHz (Tools->CPU Frequency). You may experience lag and other issues if running at 80MHz.
  • The upload must be redone each time after you rebuild and upload the software

Supported Outputs

The ESPixelStick firmware can generate the following outputs from incoming E1.31 streams, however your hardware must support the physical interface.

Pixel Protocols

  • WS2811 / WS2812 / WS2812b
  • GE Color Effects

Serial Protocols

  • DMX512
  • Renard

MQTT Support

MQTT can be configured via the web interface. When enabled, a payload of "ON" will tell the ESPixelStick to override any incoming E1.31 data with MQTT data. When a payload of "OFF" is received, E1.31 processing will resume. The configured topic is used for state, and the command topic will be the state topic appended with /set.

For example, if you enter porch/esps as the topic, the state can be queried from porch/esps and commands can be sent to porch/esps/set

If using Home Assistant, it is recommended to enable Home Assistant Discovery in the MQTT configuration. Your ESPixelStick along with all effects will be automatically imported as an entity within Home Assistant utilzing "Device ID" as the friendly name. For manual configuration, you can use the following as an example. When disabling Home Assistant Discovery, ESPixelStick will attempt to remove its configuration entry from your MQTTT broker.

  - platform: mqtt
    schema: json
    name: "Front Porch ESPixelStick"
    state_topic: "porch/esps"
    command_topic: "porch/esps/set"
    brightness: true
    rgb: true
    effect: true
      - Solid
      - Blink
      - Flash
      - Rainbow
      - Chase
      - Fire flicker
      - Lightning
      - Breathe

Here's an example using the mosquitto_pub command line tool:

mosquitto_pub -t porch/esps/set -m '{"state":"ON","color":{"r":255,"g":128,"b":64},"brightness":255,"effect":"solid","reverse":false,"mirror":false}'



You can’t perform that action at this time.