NightDriverStrip for ESP32 LED Strips and Matrices

What NightDriverStrip Controls on an ESP32

NightDriverStrip addresses a specific embedded lighting problem: putting animated color and pattern software directly onto an ESP32 connected to addressable LEDs. It is aimed at makers, kit builders, and developers who want a reusable LED controller rather than a one-off sketch that only runs locally. The firmware can drive up to eight channels of WS2812B-style LEDs connected to ESP32 pins, and it also supports HUB75-style matrices.

The project is broader than a fixed animation library. Its built-in effects can be configured for different displays, and modules equipped with a microphone can use audio and beat-reactive effects. WiFi provides a route for remote configuration and data reception. The ESP32 also synchronizes its clock through NTP, which is relevant when several devices need to run time-based effects in coordination.

The repository contains firmware, board definitions, configuration, examples, and supporting utilities under `include/`, `src/`, `boards/`, `config/`, `data/`, `lib/`, `samples/`, and `tools/`. Although the repository metadata identifies G-code as its primary language, the documented package is primarily an ESP32 C++ firmware project. This layout gives developers distinct places to inspect hardware definitions, application code, effects, and build configuration.

The repository is not archived. Its last push was on 2026-08-14, which is a recent recorded change, but repository activity alone does not establish how quickly issues are handled or how broadly supported devices are validated.

Firmware Paths for Animation and Network Data

The README describes two important operating paths. The ESP32 can run effects configured in the firmware or changed through its device web interface. It can also optionally receive LED color data over a TCP/IP socket. That socket opens on port 49152 by default, and the README says the color data may be LZ-compressed or uncompressed.

This arrangement separates local animation control from external data production. A device can therefore run its own effects while still serving as a network-controlled endpoint. However, the README does not document the packet structure, message boundaries, compression negotiation, authentication, or stream recovery. Those protocol details need to be checked before an external service is written against port 49152.

The device also exposes a web server and a telnet debug console. The web interface is the documented configuration surface, while telnet and serial provide debugging access. `REST_API.md` and `UISpec.md` exist at the repository root and are the logical places to look for endpoint and interface details. The README excerpt does not specify their authentication rules, endpoint names, or response formats, so this review does not assume any of them.

Optional hardware support extends beyond the basic WS2812B use case. The README lists audio analysis plus OLED, TFT, and LCD display support. It also lists Over-The-Air updates. These capabilities are build-dependent. The web installer identifies enabled features in each project label, which matters because owning hardware capable of a feature does not establish that the selected firmware includes it.

Browser Installation for Supported ESP32 Devices

The web installer is the documented first-use path for most supported NightDriver projects. It is intended for a new user with a compatible ESP32, a USB cable, and a browser that supports Web Serial. The README identifies recent versions of Chrome, Edge, and Opera as browsers with that capability. It therefore does not promise support for every browser.

Connect the device to the computer with USB and open the installer at:

https://plummerssoftwarellc.github.io/NightDriverStrip

The page should display the installer start screen. Select a device from the first drop-down, such as `M5StickC Plus`, and then select a supported project from the second drop-down. The README states that each project label indicates the key features enabled in that build.

Choose `CONNECT`. In the browser dialog, select the device serial port and click Connect. If several ports are listed, the README identifies `USB Serial Port (COMn)` as the likely choice. After the connection dialog opens, choose `INSTALL <project> FOR <device>`.

The installer asks whether to erase the device. Select the erase option for a first flash or a clean installation. The README warns that WiFi configuration is cleared whether or not the device is erased. Confirm the flash when prompted. The documented sequence ends at that confirmation step, so it does not identify a completion message or a specific indicator that the device is ready for configuration. Users should follow the browser prompts and confirm that their particular board appears in the device list before flashing.

Source Configuration and Effect Customization

The source-code route is the alternative to the browser installer. Instead of selecting a prepared firmware image, a developer can work with the repository's C++ code, board definitions, configuration files, libraries, and samples. The root includes `platformio.ini`, while the README has dedicated sections covering feature defines, adding new effects, WiFi setup, build tools, build commands, file system, and tools.

The excerpt does not include the actual build commands or feature-define syntax, so no unverified compilation command is presented here. Source users need to follow the repository's own build documentation rather than assuming flags or configuration keys. The relevant places to inspect are `platformio.ini`, the selected board definition under `boards/`, and the source and library directories used by that firmware target.

WiFi setup and feature defines are separate concerns. WiFi configuration is required for the network-facing functions, while feature defines determine which capabilities are compiled into a build. A developer adding an effect must also account for the selected LED type and any microphone, display, or storage assumptions associated with the target.

The repository includes samples under `samples/`, including `audioserver/`, `check.sh`, `flash.sh`, and `videoserver/`. Their names indicate examples and utilities, but the README excerpt does not identify a canonical first-use example. The browser installer is therefore the more direct route when a suitable board and prepared project are listed. Source development is the appropriate route when a standard build does not match the required LED type, effect, display, or network behavior.

Web UI, API, Persistence, and Debugging Boundaries

NightDriverStrip treats the ESP32 as a network-controlled device rather than only as an LED driver. The README identifies a web interface, a web server, an API, telnet debugging, and serial debugging. It also has a section on JSON persistence, indicating that some settings or state use a JSON representation. The README does not specify the complete schema, write frequency, storage capacity, or failure behavior, so those details require inspection of the relevant source and the repository's persistence documentation.

The README includes a separate procedure for resetting the effect list, but the documented excerpt does not reproduce its commands or interface steps. This omission matters because a clean firmware flash, an effect-list reset, and restoration of saved settings are different operations. The installer's erase option resets settings to their defaults, while the README separately warns that WiFi configuration is cleared during flashing.

NTP synchronization gives time-based effects a shared clock reference across devices. That can help when several ESP32 units form one installation. The README does not state how retry timing works after an NTP failure, whether all effects stop when time synchronization is unavailable, or whether the device falls back to stored time. Those are separate operational questions from merely enabling NTP.

The telnet console is explicitly a debug facility. The README does not document its authentication model or whether its availability changes between builds. OTA is also listed, but the README excerpt does not describe the update trigger, signing behavior, rollback process, or recovery procedure after an interrupted update. A production deployment should not assume recovery behavior that the README leaves unspecified.

Install Limits and the Source-Based Alternative

The clearest installation limitation is that the web installer covers only the devices and projects exposed by its selection lists. A board that is electrically similar to a supported ESP32 is not made compatible merely because the source can be modified. Browser installation also depends on Web Serial support, making the documented browser set relevant rather than decorative.

The README lists WS2812B strips, HUB75 matrices, audio-reactive effects, displays, networking, NTP, and OTA. It does not publish maximum physical strip lengths, power limits, refresh-rate guarantees, color-order settings for every board, or a support matrix for every peripheral. Software compatibility cannot answer the electrical question of whether a power supply can supply the intended LED load.

The real alternative to the browser workflow is the source-and-build workflow, not another LED project with an unknown relationship. The web installer selects a prepared image and transfers it through the browser's serial connection. A source-based workflow lets a developer change board definitions, feature defines, effects, and application code, using `platformio.ini` and the repository's directories as the configuration surface.

The trade-off is concrete. The installer reduces initial setup decisions but limits the first-use target to what it supports. Source development offers finer control but adds build, board, and integration work. A developer who needs a custom matrix arrangement, a specialized effect, or hardware not represented by a prepared project should expect to enter that second path.

Releases, License, and Upgrade Work

The repository records `v1.3.0` dated 2026-01-10, followed by `v2.0.0` and `v2.0.1` on 2026-06-14. The last push was on 2026-08-14. These dates show recent development activity, but they do not establish issue response times or the validation status of every supported device and feature combination.

The project uses `GPL-3.0`. The README directs readers to `COPYING.txt` for detailed technical and licensing information. Organizations planning to modify, distribute, or redistribute the firmware should read the actual license text and assess its obligations themselves. No legal conclusion can be drawn from the license identifier alone.

Upgrade work extends beyond transferring a new image. A version change can alter the board and project choices presented by the web installer, the feature letters in a build label, and the behavior exposed through the web UI, API, persistence layer, or debug console. The README includes a section about build times, but the excerpt does not provide current commands or timing values.

Configuration also needs attention during upgrades. The installer warns that WiFi configuration is cleared when a device is flashed. Users who depend on a saved network configuration, effect list, or local UI setup should determine how those settings are preserved before replacing a working installation. The README documents a reset procedure for the effect list but does not include enough of that procedure here to recommend a specific command.

Editorial conclusion

NightDriverStrip suits makers who want an ESP32 to run configurable LED effects with browser configuration, remote control, or synchronized network input. It is a poor fit for devices outside the supported installer list or for users who need a fully documented production deployment and rollback procedure. Verify the supported board and project build first, then confirm the LED wiring, power requirements, WiFi setup, and whether the planned effect needs a microphone or display before flashing.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. PlummersSoftwareLLC/NightDriverStrip on GitHub
3. Project website
4. README
5. Releases