Difference between revisions of "Chapter 8 - Configuration"

From diychristmas.org wiki
Jump to navigation Jump to search
(Created page with "'''Chapter 8 – Configuration''' '''Version:''' 0.5 (Draft) '''Written for:''' ESPPixelStick Version 4.x '''Last Updated:''' July 2026 '''Author:''' Ernest Horning '''Re...")
 
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
'''Chapter 8 – Configuration'''
 
'''Chapter 8 – Configuration'''
  
−
'''Version:''' 0.5 (Draft)
+
'''Version:''' 0.1 (Draft)
  
−
'''Written for:''' ESPPixelStick Version 4.x
+
'''Written for:''' ESPixelStick Version 4.x
  
 
'''Last Updated:''' July 2026
 
'''Last Updated:''' July 2026
Line 15: Line 15:
 
'''Purpose'''
 
'''Purpose'''
  
−
This chapter explains how to configure ESPPixelStick after firmware installation. It introduces the web-based configuration interface, network settings, pixel outputs, protocols, system settings, and methods for saving and verifying configuration changes.
+
This chapter explains how to configure ESPixelStick after firmware installation. It introduces the web-based configuration interface, network settings, pixel outputs, protocols, system settings, and methods for saving and verifying configuration changes.
  
 
Although individual menu layouts may change between firmware releases, the underlying concepts remain the same.
 
Although individual menu layouts may change between firmware releases, the underlying concepts remain the same.
Line 46: Line 46:
 
* System information
 
* System information
  
−
[[File:vertopal_7840a49f0d5c4f6a9c9462e0ebe297f5/media/image1.png|624x349px]]'''Figure 8-1-1 – Configuration Workflow'''
+
[[File:Figure_08-01-01_Configuration_Workflow.png|thumb|none|600px|'''Figure 8-1-1 – Configuration Workflow''']]
  
 
'''Why This Matters'''
 
'''Why This Matters'''
Line 59: Line 59:
 
# Open a web browser.
 
# Open a web browser.
 
# Enter the controller's IP address.
 
# Enter the controller's IP address.
−
# The ESPPixelStick configuration page should appear.
+
# The ESPixelStick configuration page should appear.
  
−
[[File:vertopal_7840a49f0d5c4f6a9c9462e0ebe297f5/media/image3.png|624x349px]]'''Figure 8-2-1 – Accessing the Configuration Interface'''
+
[[File:Figure_08-02-01_Accessing_Web_Interface.png|thumb|none|600px|'''Figure 8-2-1 – Accessing the Configuration Interface''']]
  
 
'''Engineering Note'''
 
'''Engineering Note'''
Line 84: Line 84:
 
'''8.3 Configuration Pages'''
 
'''8.3 Configuration Pages'''
  
−
The ESPPixelStick web interface is organized into logical sections.
+
The ESPixelStick web interface is organized into logical sections.
  
 
Typical configuration areas include:
 
Typical configuration areas include:
Line 92: Line 92:
 
* Outputs
 
* Outputs
 
* Effects
 
* Effects
−
* Input
+
* Inputs
 
* System
 
* System
 
* Diagnostics
 
* Diagnostics
 +
* File Management
  
−
[[File:vertopal_7840a49f0d5c4f6a9c9462e0ebe297f5/media/image5.png|624x349px]]'''Figure 8-3-1 – Typical Configuration Layout'''
+
[[File:Figure_08-03-01_Configuration_Overview.png|thumb|none|600px|'''Figure 8-3-1 – Typical Configuration Layout''']]
  
 
'''Research Note'''
 
'''Research Note'''
Line 113: Line 114:
 
* IP addressing
 
* IP addressing
 
* Ethernet (where applicable)
 
* Ethernet (where applicable)
 +
* Access Point Settings
  
 
Changes generally require the controller to reconnect to the network.
 
Changes generally require the controller to reconnect to the network.
Line 132: Line 134:
 
* Brightness
 
* Brightness
 
* Grouping
 
* Grouping
−
* Reversing
+
* ZigZag
−
* Start channel
+
* Start / End NUL pixel count
 +
* Gamma settings
 +
* Minimum Interframe gap
  
−
[[File:vertopal_7840a49f0d5c4f6a9c9462e0ebe297f5/media/image7.png|624x349px]]'''Figure 8-5-1 – Pixel Output Configuration'''
+
[[File:Figure_08-05-01_Output_Configuration.png|thumb|none|600px|'''Figure 8-5-1 – Pixel Output Configuration''']]
  
 
'''Engineering Note'''
 
'''Engineering Note'''
Line 145: Line 149:
 
'''8.6 Protocol Configuration'''
 
'''8.6 Protocol Configuration'''
  
−
ESPPixelStick supports multiple input protocols depending on platform and firmware version.
+
ESPixelStick supports multiple input protocols.
  
 
Examples include:
 
Examples include:
Line 152: Line 156:
 
* E1.31 (sACN)
 
* E1.31 (sACN)
 
* Art-Net
 
* Art-Net
−
* DMX
+
* FPP Remote Sync
−
* Renard
+
* Amazon Alexa
 +
* MQTT Client
 +
* Built in effects engine
 +
* User managed Playlist
  
−
[[File:vertopal_7840a49f0d5c4f6a9c9462e0ebe297f5/media/image9.png|624x349px]]'''Figure 8-6-1 – Protocol Selection'''
+
[[File:Figure_08-06-01_Protocol_Selection.png|thumb|none|600px|'''Figure 8-6-1 – Protocol Selection''']]
  
 
'''Research Note'''
 
'''Research Note'''
Line 193: Line 200:
 
Verify Operation
 
Verify Operation
  
−
[[File:vertopal_7840a49f0d5c4f6a9c9462e0ebe297f5/media/image11.png|624x349px]]'''Figure 8-8-1 – Saving Configuration'''
+
[[File:Figure_08-08-01_Save_Configuration.png|thumb|none|600px|'''Figure 8-8-1 – Saving Configuration''']]
  
 
'''Engineering Note'''
 
'''Engineering Note'''
Line 234: Line 241:
 
* Controller reboot
 
* Controller reboot
  
−
[[File:vertopal_7840a49f0d5c4f6a9c9462e0ebe297f5/media/image13.png|624x349px]]'''Figure 8-10-1 – Configuration Troubleshooting'''
+
[[File:Figure_08-10-01_Configuration_Troubleshooting.png|thumb|none|600px|'''Figure 8-10-1 – Configuration Troubleshooting''']]
  
 
'''8.11 Engineering Recommendations'''
 
'''8.11 Engineering Recommendations'''
Line 274: Line 281:
 
This chapter is based upon:
 
This chapter is based upon:
  
−
* ESPPixelStick project documentation
+
* ESPixelStick project documentation
−
* ESPPixelStick firmware interface
+
* ESPixelStick firmware interface
 
* Espressif networking documentation
 
* Espressif networking documentation
 
* Community experience documented on DoItYourselfChristmas.com
 
* Community experience documented on DoItYourselfChristmas.com
Line 290: Line 297:
 
| Initial draft
 
| Initial draft
 
|-
 
|-
−
| 0.5
 
−
| July 2026
 
−
| Standardized chapter format with Engineering Notes, Why This Matters, Community Experience, Research Notes, Open Research Items, and SVG figure references.
 
 
|}
 
|}

Latest revision as of 21:04, 25 July 2026

Chapter 8 – Configuration

Version: 0.1 (Draft)

Written for: ESPixelStick Version 4.x

Last Updated: July 2026

Author: Ernest Horning

Research & Technical Editing: ChatGPT

Chapter Summary

Purpose

This chapter explains how to configure ESPixelStick after firmware installation. It introduces the web-based configuration interface, network settings, pixel outputs, protocols, system settings, and methods for saving and verifying configuration changes.

Although individual menu layouts may change between firmware releases, the underlying concepts remain the same.

Prerequisites

  • Chapter 2 – Hardware Overview
  • Chapter 3 – ESP8266 Hardware Guide
  • Chapter 4 – ESP32 Hardware Guide
  • Chapter 5 – Firmware Installation

Related Chapters

  • Chapter 9 – Pixel Outputs and Wiring
  • Appendix A – GPIO Reference Tables

8.1 Introduction

Once firmware has been installed and the controller has joined the local network, nearly all controller operation is managed through the built-in web configuration interface.

The configuration pages allow the user to customize controller behavior without modifying firmware.

Typical configuration tasks include:

  • Network settings
  • Pixel outputs
  • Protocol selection
  • GPIO assignments
  • Brightness
  • System information
Figure 8-1-1 – Configuration Workflow

Why This Matters

Understanding the configuration interface allows one controller design to be reused for many different projects.

8.2 Accessing the Configuration Interface

After connecting the controller to the local network:

  1. Determine the controller's IP address.
  2. Open a web browser.
  3. Enter the controller's IP address.
  4. The ESPixelStick configuration page should appear.
Figure 8-2-1 – Accessing the Configuration Interface

Engineering Note

Assigning a DHCP reservation in the router keeps the controller at the same IP address.

This makes future maintenance much easier.

Community Experience

Many users assign meaningful host names based on the prop being controlled.

Examples:

  • GarageMatrix
  • RoofPixels
  • MegaTree
  • CandyCane01

Source: DoItYourselfChristmas.com community discussions

8.3 Configuration Pages

The ESPixelStick web interface is organized into logical sections.

Typical configuration areas include:

  • Home
  • Network
  • Outputs
  • Effects
  • Inputs
  • System
  • Diagnostics
  • File Management
Figure 8-3-1 – Typical Configuration Layout

Research Note

Individual menu names and layouts may change between firmware releases.

This chapter focuses on concepts rather than specific screen layouts.

8.4 Network Configuration

Network configuration includes:

  • Wi-Fi SSID
  • Password
  • Host name
  • IP addressing
  • Ethernet (where applicable)
  • Access Point Settings

Changes generally require the controller to reconnect to the network.

Why This Matters

Incorrect network settings are among the most common causes of "missing" controllers.

8.5 Pixel Output Configuration

Each output may be configured independently.

Typical settings include:

  • GPIO assignment
  • Pixel type
  • Pixel count
  • Color order
  • Brightness
  • Grouping
  • ZigZag
  • Start / End NUL pixel count
  • Gamma settings
  • Minimum Interframe gap
Figure 8-5-1 – Pixel Output Configuration

Engineering Note

Configure and verify one output before configuring additional outputs.

This simplifies troubleshooting.

8.6 Protocol Configuration

ESPixelStick supports multiple input protocols.

Examples include:

  • DDP
  • E1.31 (sACN)
  • Art-Net
  • FPP Remote Sync
  • Amazon Alexa
  • MQTT Client
  • Built in effects engine
  • User managed Playlist
Figure 8-6-1 – Protocol Selection

Research Note

Protocol availability varies by firmware build and hardware platform.

8.7 GPIO Configuration

Advanced Mode allows supported GPIO pins to be assigned to controller functions.

Configuration should only use GPIO known to be compatible with the selected hardware.

Refer to Appendix A for verified GPIO assignments.

Why This Matters

Improper GPIO selection may prevent the controller from starting correctly.

8.8 Saving Configuration

Configuration changes remain temporary until saved.

Typical workflow:

Modify Settings

↓

Save Configuration

↓

Controller Reboots

↓

Verify Operation

Figure 8-8-1 – Saving Configuration

Engineering Note

Avoid changing several unrelated settings simultaneously.

Making one change at a time greatly simplifies troubleshooting.

8.9 Backup and Restore

Before making major changes:

✔ Save the current configuration.

✔ Record firmware version.

✔ Record controller IP address.

✔ Label the controller if multiple units are in use.

Community Experience

Keeping a spreadsheet of controller names, IP addresses, firmware versions, and prop assignments makes large displays much easier to maintain.

Contributor: Ernest Horning

Source: Practical engineering practice

8.10 Diagnostics

If the controller does not operate as expected:

Verify:

  • Firmware version
  • Network connection
  • Protocol selection
  • GPIO assignment
  • Pixel count
  • Controller reboot
Figure 8-10-1 – Configuration Troubleshooting

8.11 Engineering Recommendations

✔ Configure one controller completely before cloning additional controllers.

✔ Label controllers.

✔ Document IP addresses.

✔ Keep firmware versions consistent across the display.

✔ Test outputs immediately after configuration.

8.12 Open Research Items

Status Item
🟨 Current menu layout
🟨 Advanced Mode options
🟨 Configuration export/import
🟨 User account features (if added in future releases)
🟨 Platform-specific configuration differences

References

This chapter is based upon:

  • ESPixelStick project documentation
  • ESPixelStick firmware interface
  • Espressif networking documentation
  • Community experience documented on DoItYourselfChristmas.com

Revision History

Version Date Description
0.1 July 2026 Initial draft
Retrieved from "https://www.diychristmas.org/wiki/index.php?title=Chapter_8_-_Configuration&oldid=3738"