ErnieHorning: Initial ZIPP-R documentation – ZIPP-R1 hardware, ESP-NOW architecture, addressing, master/satellite operation, testing, and planned development.

2026-09-17T23:02:22Z

Initial ZIPP-R documentation – ZIPP-R1 hardware, ESP-NOW architecture, addressing, master/satellite operation, testing, and planned development.

New page

{{Warning|ZIPP-R is currently under active development. Hardware designs, firmware, communications protocols, addressing, configuration procedures, and specifications described on this page may change as development and testing continue.}}

= ZIPP-R Relay Controller =

'''ZIPP-R''' (pronounced '''"zipper"''') is the relay-control branch of the [[ZIPP]] project family.

ZIPP-R is intended to provide very inexpensive distributed ON/OFF control for Christmas, Halloween, and other animated-display applications.

Rather than locating many relay outputs on one large centralized controller, small ZIPP-R controllers can be placed wherever switched power is required.

The first implementation, '''ZIPP-R1''', provides one remotely controlled relay output using an inexpensive ESP-01S and a readily available single-channel relay module.

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

== Design Goals ==

The ZIPP-R project was developed around several goals:

* Very low cost per controlled output
* Small physical size
* Simple remote hardware
* Distributed installation near the controlled load
* ESP-NOW wireless communication
* Centralized control through an ESP32 master
* Logical device addressing
* Identical firmware in multiple remote controllers where practical
* Automatic recovery from communication interruptions
* Future automatic wireless-channel selection and roaming
* Integration with DDP-based sequencing software

The intention is that ZIPP-R controllers can be inexpensive enough to install wherever a switched output is useful rather than requiring every possible controller location to be planned in advance.

== ZIPP-R1 ==

'''ZIPP-R1''' is the first ZIPP-R hardware implementation.

The "1" indicates that the controller provides one relay output.

The initial prototype consists of:

* ESP-01S ESP8266 module
* Inexpensive single-channel 5 V relay module
* Onboard 5 V to 3.3 V regulator
* Optically isolated relay-drive circuitry
* Compact enclosure
* ESP-NOW communications

The relay module uses GPIO0 of the ESP-01S to control the relay.

The tested hardware uses active-low relay control:

GPIO0 LOW = Relay ON
GPIO0 HIGH = Relay OFF

Because GPIO0 is also an ESP8266 boot-strapping pin, the hardware and firmware must ensure that the controller can boot normally while maintaining predictable relay operation.

== ZIPP-R1 Hardware ==

The relay module used for the initial prototype accepts a 5 V supply and contains the circuitry required to power the ESP-01S.

The module includes a 3.3 V regulator for the ESP-01S and a PC817 optocoupler in the relay-control circuit.

This allows a very small complete remote controller to be constructed using only the relay board, ESP-01S, enclosure, and appropriate power and load wiring.

The initial ZIPP-R1 enclosure was 3D printed and designed to contain the electronics and associated wiring as a compact inline controller.

Future versions may use different relay boards, enclosures, connectors, or switching devices while retaining the same ZIPP-R communications architecture.

== Basic Architecture ==

ZIPP-R uses a master/satellite architecture.

A typical system is expected to operate as follows:

Sequencer / Show Player
|
DDP
|
Wi-Fi
|
ESP32 ZIPP Master
|
ESP-NOW
|
+----+----+----+----+
| | |
ZIPP-R1 ZIPP-R1 ZIPP-R1
#1 #2 #3
| | |
Relay Relay Relay

The ESP32 master performs the higher-level network processing.

The individual ESP-01S satellites perform only the relatively simple tasks required for remote relay control.

This allows the satellite firmware and hardware to remain small and inexpensive.

== Why ESP-NOW? ==

A relay requires extremely little communications bandwidth compared with a pixel controller.

Maintaining a separate conventional Wi-Fi/DDP connection for every single relay would therefore create unnecessary network traffic and Wi-Fi association overhead.

ZIPP-R instead uses ESP-NOW between the master and the remote relay controllers.

The ESP32 master can maintain the higher-level connection to the show system while communicating with many inexpensive ESP8266 satellites using short ESP-NOW messages.

This architecture is intended to reduce the number of conventional Wi-Fi clients required in a large display.

It also allows the ZIPP-R communications protocol to be optimized specifically for simple distributed control.

== Current ESP-NOW Packet ==

The initial development firmware uses a compact six-byte command packet.

The packet currently contains:

* Packet identification/magic value
* Protocol version
* Logical device ID
* Relay command
* Sequence number

The initial development structure is:

struct ZippRelayPacket
{
uint16_t magic;
uint8_t version;
uint8_t deviceId;
uint8_t command;
uint8_t sequence;
};

The current relay command values are:

0 = OFF
1 = ON

The packet format is experimental and may change as development continues.

== Logical Device Addressing ==

ZIPP-R is intended to use simple logical addresses rather than requiring users to maintain lists of ESP8266 MAC addresses.

For example:

ZIPP-R #1
ZIPP-R #2
ZIPP-R #3
...
ZIPP-R #50

The current prototype firmware contains a simple device ID in the command packet.

Each satellite examines the logical device ID and responds only to commands intended for that device. A broadcast address may also be used for commands intended for all devices.

The initial prototype uses:

Device ID 1

for the first ZIPP-R1.

== Automatic Commissioning ==

A future objective is to eliminate the need to compile separate firmware for every ZIPP-R1.

All satellites should be capable of receiving identical firmware.

An unconfigured controller could announce itself to the master using its unique factory MAC address.

The master could then assign an available logical ZIPP-R number.

For example:

New ZIPP-R detected
Factory MAC: xx:xx:xx:xx:xx:xx
Assigned ID: ZIPP-R #17

The satellite would store its assigned logical ID in nonvolatile memory and use that address during future operation.

The MAC address would therefore be used internally during commissioning, but normal operation and configuration would use the simpler logical ZIPP-R number.

A newly assigned controller could also operate its relay or indicator in a recognizable pattern so that the installer can physically identify and label the controller.

'''Automatic commissioning has not yet been implemented.'''

== ESP32 ZIPP Master ==

The current development master uses an ESP32-C3.

The master is responsible for communicating with the remote ESP-01S ZIPP-R controllers.

The first bench-test firmware accepts simple commands through the USB serial interface and transmits the corresponding relay command using ESP-NOW.

Initial testing successfully demonstrated:

ESP32-C3
|
ESP-NOW
|
ESP-01S
|
GPIO0
|
Relay

The first working prototype successfully operated the relay remotely using ESP-NOW commands.

This established the basic communications and hardware architecture before DDP and other higher-level features were added.

== Initial Bench Testing ==

The first ZIPP-R1 ESP-NOW test used:

* ESP32-C3 master
* ESP-01S satellite
* Single-channel relay module
* ESP-NOW channel 1
* Logical Device ID 1
* Serial commands at the master for testing

Development commands included:

1 = Relay ON
0 = Relay OFF
t = Toggle relay
s = Display status

The ESP32-C3 transmitted the six-byte ZIPP-R packet using ESP-NOW.

The ESP-01S received the packet, verified the packet information and logical device address, and controlled GPIO0 accordingly.

Remote ON and OFF operation of the physical relay was successfully demonstrated.

'''This was the first successful end-to-end ZIPP-R1 communications test.'''

== DDP Integration ==

The eventual ZIPP-R master is intended to receive DDP data from a sequencing or show-player application.

Individual DDP channels can then be mapped to logical ZIPP-R outputs.

For example:

DDP Channel 1 -> ZIPP-R #1
DDP Channel 2 -> ZIPP-R #2
DDP Channel 3 -> ZIPP-R #3

The master converts the incoming channel state into the small ESP-NOW command required by the appropriate satellite.

This allows sequencing software to treat ZIPP-R outputs similarly to other show channels without requiring the software to understand ESP-NOW or the individual remote devices.

'''DDP-to-ZIPP-R operation has not yet been implemented or tested.'''

== Sequencing Software ==

Because the planned interface between the show computer and ZIPP master is DDP, ZIPP-R should not inherently depend on one particular sequencing application.

[[xLights]] is expected to be the primary software used during development.

Other sequencing or show-player applications capable of transmitting compatible DDP data should potentially be capable of controlling ZIPP-R through the master.

Software compatibility should be considered unverified until specifically tested.

== Heartbeat and Failsafe ==

A future ZIPP-R communications system is expected to include periodic heartbeat or state messages.

The master can periodically retransmit the desired state of each output even when no change has occurred.

This provides several advantages:

* Recovery from a missed command
* Confirmation that the master is still operating
* Detection of communication loss
* Automatic restoration of the correct relay state after temporary interference

A satellite that fails to hear the master for a defined period can enter a predetermined safe state.

For many ZIPP-R applications, the expected failsafe state will be:

Relay OFF

The exact heartbeat interval and failsafe behavior have not yet been finalized.

== Acknowledgements and Status ==

ESP-NOW provides information about successful radio transmission, but radio-level delivery does not necessarily prove that the physical relay changed state.

Future ZIPP-R development may therefore include application-level acknowledgement and status reporting from satellites to the master.

This could allow the master to distinguish between:

* Command transmitted
* Command received
* Command accepted
* Relay state changed
* Satellite communication lost

'''Application-level acknowledgement has not yet been implemented.'''

== Wireless Channel Selection and Roaming ==

Automatic 2.4 GHz channel selection and roaming are planned features of the ZIPP communications architecture.

The objective is to avoid permanently assigning every ZIPP-R controller to one manually selected RF channel.

A future ZIPP-R satellite may:

* Start on its last known working channel
* Listen for a recognizable ZIPP master beacon
* Remain on that channel when the master is found
* Detect loss of the master heartbeat
* Search permitted channels when communication is lost
* Rediscover the ZIPP master automatically
* Store the newly discovered channel for future startup

The master may eventually evaluate the local 2.4 GHz RF environment and select the most suitable usable channel.

A possible future channel-change procedure is:

Master determines that another channel is preferable
|
Master announces the new channel
|
Satellites acknowledge or prepare to move
|
Master and satellites change channels
|
Normal communications resume

A satellite that misses the channel-change announcement could eventually detect loss of the heartbeat, begin searching, and rediscover the master.

This makes ZIPP-R an attractive development platform for testing automatic channel selection because relay-control traffic requires very little bandwidth.

There is an important limitation when the ESP32 master is simultaneously associated with a conventional Wi-Fi access point. Wi-Fi and ESP-NOW share the ESP32's 2.4 GHz radio, so channel selection must account for the channel being used by the Wi-Fi network.

'''Automatic channel selection and roaming have not yet been implemented.'''

== Multiple ZIPP-R Controllers ==

The ZIPP-R architecture is intended to support many inexpensive remote controllers from one master.

Because relay commands are very small and relay states change relatively infrequently, communications requirements are much lower than those of pixel controllers.

The practical maximum number of satellites has not yet been established.

Future testing will determine:

* Maximum practical controller count
* Command latency
* Packet-loss behavior
* Startup and discovery time
* Recovery after interference
* Channel-roaming performance
* Master processing requirements

== Possible Future ZIPP-R Variants ==

ZIPP-R1 identifies the current single-relay controller.

The architecture does not require every future ZIPP-R controller to contain only one output.

Possible future variants could include:

ZIPP-R1 - One relay output
ZIPP-R4 - Four relay outputs
ZIPP-R8 - Eight relay outputs

These variants are conceptual unless separately documented as completed hardware.

For widely separated loads, multiple inexpensive ZIPP-R1 controllers may be preferable to a larger multi-output controller.

For several loads located together, a multi-relay ZIPP-R controller could reduce the total hardware required.

== Enclosure ==

The initial ZIPP-R1 prototype uses a custom 3D-printed enclosure.

The enclosure is intended to contain the ESP-01S relay module and associated wiring in a compact package suitable for distributed use.

Multiple enclosures can be printed inexpensively, making it practical to construct a relatively large number of identical remote controllers.

Enclosure files and construction details may be added after the design has been sufficiently tested and finalized.

== Firmware ==

Two firmware components are required by the current ZIPP-R architecture:

* '''ZIPP-R satellite firmware''' for the ESP-01S
* '''ZIPP Master firmware''' for the ESP32

The current firmware is development firmware and should not yet be considered a general release.

The first working satellite development firmware provides:

* ESP-NOW reception
* Logical device filtering
* Relay ON/OFF control
* Serial diagnostics
* Manual serial testing

The first working ESP32-C3 master development firmware provides:

* ESP-NOW transmission
* Logical device addressing
* Serial ON/OFF commands
* Toggle command
* Status diagnostics

Firmware downloads and programming instructions will be added when suitable versions are ready for general use.

== Safety ==

ZIPP-R may be used to control line-voltage electrical loads.

'''Line voltage can cause serious injury, fire, or death.'''

Appropriate electrical construction practices, insulation, strain relief, fusing, enclosure design, wire sizes, connectors, weather protection, and component ratings must be used.

Low-voltage ESP electronics and accessible programming connections must be appropriately isolated from line-voltage wiring.

Relay contact ratings must be suitable for the connected load.

Outdoor controllers must be protected against moisture and environmental exposure.

== Relationship to Other ZIPP Projects ==

ZIPP-R is part of the larger [[ZIPP]] project family.

Related projects include:

* [[ZIPP Pixel Controller|ZIPP]] - DDP pixel control
* [[ZIPP-I]] - Incandescent-light control and dimming
* [[ZIPP-M]] - Motion sensing and interactive control
* [[ZIPP-A]] - Experimental audio distribution

ZIPP-R also serves as a useful development platform for features that may eventually be shared with other low-bandwidth ZIPP devices, particularly logical addressing, automatic commissioning, heartbeat/failsafe operation, and wireless channel roaming.

== Future Development ==

Planned or proposed ZIPP-R development includes:

* Multiple logical satellite addresses
* Automatic device commissioning
* Persistent logical addresses
* DDP input at the ESP32 master
* Mapping DDP channels to ZIPP-R devices
* Periodic heartbeat/state messages
* Satellite failsafe behavior
* Application-level acknowledgements
* Automatic RF channel selection
* Automatic channel roaming
* Lost-device recovery
* Configuration interface
* Additional ZIPP-R hardware variants
* Large-controller-count testing
* Documentation of enclosure and construction details

== Project Author ==

ZIPP-R is a DIY Christmas member project developed by '''Ernest Horning''' as part of the [[ZIPP]] project family.

The project is being documented during development so that hardware information, firmware architecture, experiments, test results, and design decisions can be preserved for future reference.

== See Also ==

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

[[Category:Controllers]]

ZIPP-R - Revision history

ErnieHorning: Initial ZIPP-R documentation – ZIPP-R1 hardware, ESP-NOW architecture, addressing, master/satellite operation, testing, and planned development.