ErnieHorning: Created initial ZIPP Pixel Controller documentation including design goals, hardware, DDP operation, performance testing, xLights/Vixen compatibility, Wi-Fi testing, diagnostics, and development history.

2026-09-17T22:41:28Z

Created initial ZIPP Pixel Controller documentation including design goals, hardware, DDP operation, performance testing, xLights/Vixen compatibility, Wi-Fi testing, diagnostics, and development history.

New page

{{Warning|The ZIPP Pixel Controller is currently under active development. Hardware, firmware, configuration procedures, performance limits, and specifications described on this page may change as development and testing continue.}}

= ZIPP Pixel Controller =

The '''ZIPP''' ('''Zero-Overhead Intelligent Pixel Protocol''') Pixel Controller is a lightweight ESP8266-based wireless pixel controller developed for DIY Christmas and animated-lighting applications.

ZIPP was created to investigate how much pixel-control performance could be obtained from inexpensive ESP8266 hardware when unnecessary firmware overhead was removed.

The controller receives [[DDP]] pixel data from [[xLights]] over 2.4 GHz Wi-Fi and directly generates the data stream required by WS2811-compatible addressable pixels.

'''Project Status:''' Working prototype / active development.

== Design Goals ==

The original ZIPP project was developed around several basic goals:

* Use inexpensive ESP8266 hardware.
* Receive pixel data directly from xLights using DDP.
* Maintain a 40 FPS show frame rate.
* Minimize firmware processing overhead.
* Determine the practical pixel-output limits of the ESP8266.
* Provide simple distributed controllers that can be located near individual props.
* Minimize the amount of configuration required at each controller.
* Measure actual performance rather than relying only on theoretical limits.

The project subsequently became a test platform for investigating Wi-Fi loading, controller startup behavior, DDP timing, xLights output behavior, and long-distance wireless operation.

== Hardware ==

The primary ZIPP development hardware is an inexpensive ESP8266 D1 Mini style controller.

Typical hardware consists of:

* ESP8266 D1 Mini
* 5 V power supply
* WS2811-compatible pixels
* Wi-Fi network connection
* Pixel data output from the ESP8266

The controller is intentionally simple. Pixel data is received wirelessly and generated directly by the ESP8266 without requiring an additional dedicated pixel-controller IC.

Different ZIPP installations may use different power supplies, connectors, enclosures, and power-injection arrangements depending on the prop being controlled.

== Basic Architecture ==

A basic ZIPP installation operates as follows:

xLights
|
DDP
|
2.4 GHz Wi-Fi
|
ESP8266 ZIPP Controller
|
WS2811 Pixel Data
|
Addressable Pixels

xLights performs the sequencing and rendering.

The ZIPP controller receives the resulting DDP channel data and converts it directly into the serial waveform required by the pixels.

The objective is to perform as little additional processing as practical between receiving a completed frame and transmitting it to the pixels.

== Why ZIPP Was Developed ==

General-purpose pixel-controller firmware provides many useful features, but those features consume processor time, memory, and other resources.

ZIPP was developed to investigate a different approach:

'''What happens if an ESP8266 pixel controller does little more than receive DDP data and output pixels?'''

Testing showed that removing unnecessary overhead can significantly increase the number of pixels that an inexpensive ESP8266 can operate while maintaining the desired show frame rate.

The project is not intended to replace every general-purpose pixel controller. It is intended to provide a lightweight alternative for applications where the additional features are not required.

== WS2811 Timing ==

WS2811-compatible pixels require approximately 30 microseconds of transmission time per RGB pixel at the standard approximately 800 kHz data rate.

At a 40 FPS show rate:

1 / 40 = 25 milliseconds per frame

or:

25,000 microseconds per frame

This places a fundamental timing limit on the number of pixels that can be transmitted serially from a single output during each frame.

Controller firmware overhead, interrupt activity, Wi-Fi processing, reset/latch timing, and other delays reduce the practical limit.

One of the original objectives of ZIPP testing was to determine how close an ESP8266 could operate to this physical timing limit.

== 800 Pixel / 40 FPS Test ==

A major ZIPP development test used:

* ESP8266 D1 Mini
* 800 WS2811 pixels
* 2,400 channels
* DDP input
* 25 ms frame interval
* 40 FPS target
* Direct asynchronous pixel output

A long-duration test produced:

Pixels: 800
Channels: 2400
Target frame rate: 40 FPS
Target frame interval: 25,000 us
Frames tested: 183,966
Frame overruns: 0
Average frame interval: approximately 24,999 us

The test demonstrated sustained operation of '''800 pixels at 40 FPS''' on an ESP8266.

This result should not be interpreted as a guarantee that every ESP8266 installation can operate 800 pixels under every condition. Wi-Fi conditions, firmware changes, pixel-output method, network loading, and other factors can affect performance.

It does demonstrate that 800-pixel/40-FPS operation is technically practical when controller overhead is kept sufficiently low.

== Comparison With General-Purpose Firmware ==

During development, WLED was also tested as a reference point.

A WLED installation configured for 641 pixels reported an operating rate of approximately 33 FPS and displayed a warning related to the pixel count.

This comparison helped motivate investigation into how much performance could be obtained when the ESP8266 was dedicated primarily to receiving DDP and generating pixel data.

The comparison is not intended to imply that ZIPP and WLED provide equivalent features.

WLED is a general-purpose lighting-control system with substantially more functionality. ZIPP intentionally removes much of that functionality in exchange for a smaller and more specialized workload.

== DDP ==

ZIPP uses [[DDP]] (Distributed Display Protocol) to receive pixel data.

DDP is particularly suitable for this application because xLights can transmit channel data directly to network controllers without requiring the ZIPP controller to understand sequences or effects.

The controller is concerned primarily with:

* Receiving DDP packets
* Validating packet information
* Placing received channel data into the appropriate frame buffer
* Detecting complete frames
* Transmitting completed frames to the pixels

The ESP8266 does not render xLights effects.

== xLights ==

[[xLights]] is the primary sequencing software used during ZIPP development and testing.

xLights creates the sequences and transmits pixel data to ZIPP controllers using DDP.

ZIPP supports xLights controller auto-discovery by emulating the discovery information expected from a WLED controller. This allows xLights to automatically discover a ZIPP controller using its existing WLED discovery mechanism rather than requiring a ZIPP-specific discovery implementation.

Once configured, xLights sends DDP pixel data directly to the ZIPP controller.

During ZIPP development, testing revealed that controller behavior could be affected by how xLights generated and transmitted network data.

This resulted in investigation of xLights frame timing and DDP output behavior.

Experimental modifications to xLights were used during development to investigate timing and packet-delivery behavior.

A timing-related issue was reported to the xLights project during this work.

A separate issue involving the xLights Butterfly effect was also identified and reported during the same general development period.

These investigations became an important part of ZIPP development because controller performance cannot be evaluated independently of the software generating the incoming network traffic.

== Vixen 3 ==

[[Vixen 3]] should also be capable of operating a ZIPP Pixel Controller.

Vixen 3 includes native support for DDP output. Because ZIPP receives standard DDP pixel data, no ZIPP-specific output module should be required.

Unlike the xLights configuration described above, automatic controller discovery should not be necessary. A ZIPP controller can be manually configured in Vixen as a DDP controller using the ZIPP controller's IP address and the required number of output channels.

The expected data path is:

Vixen 3
|
DDP
|
2.4 GHz Wi-Fi
|
ESP8266 ZIPP Controller
|
WS2811 Pixel Data

In principle, ZIPP should operate equally well with Vixen 3 because the controller is receiving DDP data and is not dependent on xLights for pixel-data generation.

'''Vixen 3 operation has not yet been tested with ZIPP.'''

Until actual hardware testing has been completed, Vixen 3 compatibility should be considered expected but unverified.

Testing with Vixen 3 is planned for future development.

== Other Sequencing Software ==

ZIPP is not dependent on xLights or Vixen 3 for normal pixel operation.

ZIPP is fundamentally a DDP pixel controller. Any sequencing or show-player software capable of transmitting compatible DDP pixel data should potentially be able to control a ZIPP Pixel Controller.

The basic requirement is simply:

Sequencer / Show Player
|
DDP
|
2.4 GHz Wi-Fi
|
ESP8266 ZIPP Controller
|
WS2811 Pixel Data

xLights has been used extensively during ZIPP development and testing.

Vixen 3 includes native DDP support and is expected to operate with ZIPP, although this combination has not yet been tested.

Other sequencing and show-player applications that support DDP may also be compatible. Unless specifically identified as tested on this page, compatibility with other software should be considered expected but unverified.

Because ZIPP receives standard DDP channel data rather than sequence files or software-specific effects, the ZIPP controller does not need to know which sequencing application generated the data.

== Wi-Fi Controller Loading ==

An unexpected result of ZIPP development involved Wi-Fi startup and association behavior when many ESP8266 controllers were used simultaneously.

Individual controllers could associate with the access point quickly when little or no show traffic was present.

When xLights was already transmitting substantial amounts of DDP traffic, newly powered ESP8266 controllers could require much longer to successfully associate with the Wi-Fi network.

Testing included groups of ESP8266 controllers powered simultaneously under different network conditions.

This behavior led to experiments involving:

* Randomized startup delays
* Wi-Fi association retries
* Watchdog recovery
* Controller reset timing
* Wi-Fi signal strength
* DDP traffic during startup
* Access-point loading
* Staggered controller startup
* Reducing the total number of Wi-Fi controllers

The results helped motivate later ZIPP-family work involving master/satellite architectures and ESP-NOW for devices that do not require full DDP bandwidth.

== Distributed Controllers ==

One of the advantages of inexpensive ESP8266 controllers is that controllers can be distributed throughout a display.

Instead of one large controller operating many unrelated props, an individual prop or small group of props can have its own controller.

Advantages can include:

* Shorter pixel data wiring
* Simplified power distribution
* Fewer long pixel-data extensions
* Easy prop replacement
* Low controller cost
* Flexible display layout

The disadvantage is that a sufficiently large display may contain many independent Wi-Fi devices.

ZIPP development therefore includes investigation of both controller performance and overall network behavior.

== Long-Range Testing ==

ZIPP has also been used for long-distance wireless testing.

During one field test, a 28-pixel candy cane controlled by ZIPP successfully operated at approximately '''1,800 feet''' from the transmitting system.

This was substantially farther than the approximately 300-foot distance commonly associated with ordinary 2.4 GHz Wi-Fi expectations.

The test demonstrated that useful communication distance can be considerably greater under favorable line-of-sight and RF conditions.

The result should not be treated as a guaranteed ZIPP operating range. Actual range depends heavily on antennas, access points, interference, terrain, obstructions, orientation, and other RF conditions.

== Pixel Output Development ==

Several methods of generating the WS2811 data stream were investigated during development.

Testing included conventional and asynchronous output techniques.

One asynchronous UART-based method successfully supported the 800-pixel/40-FPS test.

A DMA-based experiment was also attempted but did not produce satisfactory results in the tested configuration.

Unsuccessful experiments are considered useful parts of the ZIPP development record because they help identify approaches that may not be worth repeating.

== Diagnostics ==

Development firmware has included extensive diagnostic information to help distinguish pixel-output problems from DDP, Wi-Fi, and timing problems.

Diagnostics have included measurements or counters for:

* DDP packets received
* DDP packets accepted
* Rejected packets
* Complete frames
* Incomplete frames
* Bad offsets
* Bad packet lengths
* Invalid packet versions
* Frame timing
* Pixel-output timing
* Frame overruns
* Wi-Fi RSSI
* Wi-Fi channel
* Startup timing

Diagnostic firmware versions may contain substantially more instrumentation than a future production ZIPP firmware release.

== Startup Behavior ==

Reliable startup became an important ZIPP development objective.

A display controller should not require manual intervention simply because it was powered while show data was already being transmitted.

Development firmware has therefore investigated methods of recovering automatically when initial Wi-Fi association is unsuccessful.

Another requirement is that pixels should remain off until valid show data has been received. Watchdog or recovery operations should not cause visible unwanted pixel flashes during startup.

These requirements remain areas of active development.

== Relationship to the ZIPP Family ==

The original ZIPP pixel controller led to several related projects.

* [[ZIPP-R]] - Distributed relay control using ESP-NOW.
* [[ZIPP-I]] - Distributed incandescent-light control and dimming.
* [[ZIPP-M]] - Distributed motion sensing and interactive control.
* [[ZIPP-A]] - Experimental network audio distribution.

The later projects do not necessarily use the original pixel protocol directly. They share the ZIPP philosophy of inexpensive distributed hardware and efficient communications appropriate to the task.

See the main [[ZIPP]] page for an overview of the complete project family.

== Future Development ==

Possible future ZIPP Pixel Controller development includes:

* Continued reduction of controller overhead
* Improved automatic Wi-Fi recovery
* Improved startup behavior
* Additional controller consolidation
* ESP32 and ESP32-S3 performance testing
* Multiple parallel pixel outputs
* Higher-throughput DDP testing
* Improved diagnostics
* Easier configuration
* Integration with other ZIPP-family devices

An ESP32-S3 high-throughput pixel-controller benchmark has also been proposed to investigate how many parallel WS2811 outputs can be supported when general-purpose firmware overhead is removed.

== Firmware ==

ZIPP firmware is currently under development.

Development versions should not be assumed to be final releases.

Firmware downloads, source code, installation instructions, and configuration information will be added when suitable versions are available for general use.

== Safety ==

Pixel installations may involve high current even when operating at low voltage.

Appropriate wire sizes, fusing, connectors, power supplies, power injection, weather protection, and electrical construction practices should be used.

The ZIPP controller does not eliminate the electrical requirements associated with safely powering large numbers of pixels.

== Project Author ==

The ZIPP Pixel Controller is a DIY Christmas member project developed by '''Ernest Horning'''.

The project is being documented during development so that test results, design decisions, successful approaches, and unsuccessful experiments can be preserved for future reference.

== See Also ==

* [[ZIPP]]
* [[ZIPP-R]]
* [[ZIPP-I]]
* [[ZIPP-M]]
* [[ZIPP-A]]
* [[Controllers]]
* [[Pixel Controllers]]
* [[DDP]]
* [[ESP8266]]
* [[ESP32]]
* [[xLights]]

[[Category:Controllers]]
[[Category:Pixels]]

ZIPP Pixel Controller - Revision history

ErnieHorning: Created initial ZIPP Pixel Controller documentation including design goals, hardware, DDP operation, performance testing, xLights/Vixen compatibility, Wi-Fi testing, diagnostics, and development history.