The HomeGenie Smart Light is a firmware designed to drive advanced, highly responsive 1D/2D addressable LED systems. Supporting both linear strips and high-density matrices up to 64x64 (4096 pixels) in any physical configuration, it operates natively as a standalone ambient light, a music-reactive visualizer, or a programmable pixel-art display.

HomeGenie Smart Light firmware Demo

Open media

Product Features

• bolt High-Performance Rendering: Smooth fluid transitions and particle-physics effects calculated at up to 100 Hz.
• grid_on Advanced 1D/2D Matrix Support: Run classic linear strip patterns or fully procedural 2D matrix animations up to 4096 pixels.
• music_note Dynamic Music Sync: Integrates with the "Music-Sync" functionality. Color and speed are mapped to the master hue, saturation, and level in real-time, allowing the light to physically dance to the beats.
• code_blocks Embedded Scripting Engine: Compile and execute custom text-based animations on the fly. The non-blocking interpreter supports sub-millisecond execution, precise timing, and control-flow commands.
• cloud_off Autonomous & Cloud-Free: No account registration, internet connection, or external gateway required. It operates entirely locally.
• calendar_clock Automated Scheduling: A built-in scheduler runs JavaScript automation, enabling automatic Sunrise/Sunset scenes or automatic turn-off timers.
• api Convenient Control: Fully manageable via the free HomeGenie Panel app, physical buttons, or a rich HTTP API.

The Concept: Snap-Together Modules

The Smart Light Controller relies on compact, modular breakout boards. Each component handles a dedicated role and plugs directly into the custom PCB shield using standard pin headers with zero soldering required during final assembly:

1. Main Microcontroller Board (ESP32-C3 / S3 Zero)

The processing brain of the smart light. It runs the HomeGenie Mini firmware, manages high-speed 100Hz animation rendering, Wi-Fi connectivity, local automations, and scheduling. It plugs face-down into the controller shield, directing its onboard RGB indicator toward the base of the translucent enclosure.
Common models / Search keywords: Waveshare ESP32-C3-Zero / ESP32-S3-Zero (with pre-soldered pin headers)

2. WS2812B 1-Pixel RGB LED Module (Optional)

An optional auxiliary RGB indicator that plugs directly into the controller shield. It illuminates the 3D-printed enclosure from within, providing visual status feedback (such as Wi-Fi pairing and animation mirroring) or functioning as an independent, secondary ambient light source.
Common models / Search keywords: WS2812B 5050 RGB LED 1-Bit module breakout board, NeoPixel 1-LED PCB module

These components are standard, widely produced electronic modules that cost very little. They are readily available on major marketplaces (such as AliExpress, Amazon, or eBay) and can be snapped together in less than 5 minutes, making it an accessible, rewarding DIY build for anyone.

Assembling The Controller

The HomeGenie Smart Light controller board features dedicated sockets to plug in the ESP32 module and the optional RGB LED module, along with a 10 cm cable with a JST connector for connecting an LED strip or matrix.

Assembly is quick and simple: just plug in the two modules and place the board into its translucent 3D-printed enclosure, which uses a completely screwless snap-fit design for easy assembly.

Smart Light Controller

Open media

Kit assembly instructions

Open media

Install the ESP32-C3 (or S3)

Open media

Install the RGB LED pixel (WS2812B)

Open media

Insert the buttons into the enclosure top

Open media

Place the assembled board into the enclosure top

Open media

Snap the bottom cover into place

Open media

Bottom assembly complete

Open media

Device fully assembled

Open media

16x16 LED matrix enclosure

This project also includes a custom 3D-printed enclosure for a 16x16 LED matrix. It is specifically designed to maximize light output while minimizing dark lines between individual pixels.

The internal grid is an independent element positioned a few millimeters behind the front face, creating a subtle, natural diffusion that softens pixel boundaries and eliminates harsh grid shadows.

The enclosure consists of three parts:

• Front Cover: Serves as the smooth light diffuser.
• Light Grid: Isolates individual LEDs to prevent light bleed.
• Back Plate: Designed for modularity, allowing multiple panels to be securely joined together using 3 brackets and 6 screws.

Print Settings

Printing all three components takes approximately 4 hours on a Bambu Lab A1 mini using standard settings and white PLA+ filament. To achieve the exact diffusion effect shown in the videos, we recommend using the same filament brand (eSun White PLA+), as translucency can vary significantly between manufacturers.

Smart Light with 16x16 LED Matrix Panel

Open media

Place the light grid into the front cover

Open media

Place the LED matrix over the grid

Open media

Gently flex the LED matrix to slide it under the side tabs

Open media

Route the cables through the slots and place the back plate

Open media

Secure the back plate with the 6 screws

Open media

Back assembly complete

Open media

Connect the LED matrix panel to the controller

Open media

Panel Assembly

Assembling the 16x16 LED matrix enclosure is quick, clean, and requires no glue. First, place the light grid inside the front diffuser cover. Next, gently flex the LED matrix so its side edges slide under the retaining tabs, resting flat against the grid while keeping any spare power wires tucked safely inside. Finally, place the back plate on top—making sure the input (DIN) and output (DOUT) cables exit through the dedicated side slots—and secure it firmly with six M2×6 screws.

Once assembled, you have a solid, lightweight display unit ready to connect directly to the Smart Light controller, or to be joined with additional panels for a wider display.

Joining Multiple Panels

To join two panels side-by-side, place the three 3D-printed brackets across the side holes and secure each bracket with two M2×8 screws (6 screws total). These are 2 mm longer than the standard screws to account for the bracket thickness.

Join two panels with the 3 brackets and 6 M2×8 screws

Open media

Smart Light with 32x16 LED Matrix Panel (Wave effect)

Open media

Power Supply & Max Power Setting

To protect your USB power supply and the controller itself, the firmware includes a configurable Max Power % limiter.

The DIY LED controller kit is physically rated for a maximum current of 3A (3 Amps). When driving a high number of pixels (up to 4096), you must reduce the "Max Power %" setting to ensure the total current draw never exceeds this 3A threshold. To utilize more power (e.g., running massive matrix panels at full white brightness), different hardware capable of handling more than 3A is required.

The 16x16 LED matrix (256 pixels) used in the demonstration examples fits perfectly within these safety limits using standard USB power supplies.

Max LED power % formula:

<power_supply_ampere> / (<number_of_pixels> * <ampere_per_pixel>) * 100 = <max_ampere_perc>

Example: With a 2A power supply and a LED strip of 144 pixels (0.04A each), the limit should be set to 35%:

2 / (144 * 0.04) * 100 = 34.7%

Interactive LED Matrix Emulator

You can explore the system's real-time rendering capabilities and custom scripting engine directly in your browser. Use the interactive LED Matrix Emulator below to preview procedural patterns, browse pre-built pixel art, and upload animations directly to your physical HomeGenie device.

Emulator Quick Guide

• mic_off Music Sync: Click to toggle real-time audio reactivity. The matrix colors and brightness will pulse dynamically to your microphone input.
• palette Master Color: Set the global color and brightness. Script intensities automatically normalize (VCA scale) against this value.
• arrow_back arrow_forward Navigation: Cycle through procedural effects and custom scripts using the arrows or the dropdown list.
• send Send to Device: Open the panel to set your device IP, copy the generated commands (CURL or Wget), or upload directly. This button is available only when a Custom Script is selected.

DIY: Beyond the Default Enclosures

The 3D-printed controller housing and the 16x16 LED matrix frame shown above are ready-to-print, standalone designs—in fact, the controller itself already functions as a compact ambient light.

However, the real strength of HomeGenie lies in its versatility. Because it uses standard addressable LEDs, you are not limited to these default shapes: you can use the exact same controller to bring virtually any custom lamp, lit lithophane, neon-style sign, or decorative fixture to life.

WS2812B LEDs: Selection & Sourcing

To build custom fixtures or expand your setup, the HomeGenie controller is officially tested and optimized for WS2812B (5V) addressable LEDs. These are the most common, cost-effective, and widely supported digital RGB LEDs on the market.

Recommended Form Factors

• WS2812B LED Strip (5V): Available in various densities (typically 30, 60, or 144 LEDs per meter). Higher densities (such as 60 or 144 LEDs/m) provide smoother light diffusion inside custom lamp shapes and channels.
• 16x16 or 8x32 Serpentine LED Matrix Panel (5V): Flexible LED grids ideal for displaying fluid 2D animations, retro pixel art, and digital clocks.

WS2812B LED Matrix Types

Open media

WS2812B LED Strip Types

Open media

Where to Buy

WS2812B strips and matrices are readily available online and at electronics hobbyist retailers:

• Global Marketplaces: AliExpress, Amazon, and eBay offer a wide range of options in different lengths, densities, and waterproof ratings (IP30, IP65, or IP67).
• Specialized Maker Retailers: Stores like Adafruit (often sold under the brand name NeoPixels), SparkFun, and local electronics hobby shops.

Custom 3D-Printed Lamps & Community Models

In addition to the official 3D-printable files included with this project, you can easily adapt thousands of creative community designs to work with the HomeGenie controller. A well-designed lamp body protects the electronics and diffuses the harsh, pinpoint light of individual LEDs into a soft, uniform glow.

Where to Find Ready-to-Print Models

You do not need to design every lamp from scratch. Popular 3D-printing repositories host thousands of free models designed specifically for WS2812B strips and 16x16 matrices.

• Popular Platforms: Search sites like MakerWorld, Printables, or Thingiverse using keywords such as:
  • "WS2812B lamp"
  • "LED matrix frame"
  • "Pixel art display"
  • "Diffused ambient light"
  • "Lithophane light box"
• Designing Your Own: If you want a tailored shape for your desk or room, beginner-friendly CAD tools like Tinkercad, Fusion 360, or Onshape make it easy to model custom light channels and diffusers.

Printing Tips for Best Results

• The Diffuser: The surface covering the LEDs must scatter the light evenly. Use a white or natural translucent filament (such as White PLA or Translucent PETG). Print this section with thin walls (1 to 2 perimeters) and 100% solid infill (concentric or rectilinear) so internal infill patterns do not cast visible shadows.
• The Lamp Body: Use opaque, dark, or solid-colored PLA/PETG for the outer structure to block light leakage and ensure all illumination is focused through the diffuser.

Get your ESP32-S3-Zero Board

How to build HomeGenie Smart Light

Use these files to order the PCB and 3D-printed case from manufacturing services such as JLCPCB or PCBWay.

LED Controller Kit V2

PCB Gerber download REVISION 1

Controller Case 3MF download REVISION 1

Matrix Mood Lamp

16x16 LED matrix casing 3MF REVISION 1

Smart Light project files by G-Labs licensed under CC BY-NC 4.0

Firmware Configuration Parameters

Before uploading the firmware, set the configuration fields to match your hardware:

1. LED Strip or Matrix

• Linear LED Strip: Set Rows to 1, then enter your total number of LEDs.
• 16x16 Matrix (256 LEDs): Set Total LEDs to 256 and Rows to 16. Then select the following layout options:
  • Vertical wiring: Yes
  • Serpentine wiring: Yes
  • Starts at bottom: Yes
  • Starts at right: No
• Chained Matrices (e.g., 32x16): For two 16x16 panels side-by-side, keep the same layout options with Rows at 16 and set Total LEDs to 512.

2. Auxiliary LED (Optional)

If you installed the optional RGB module onto the controller shield:

• Auxiliary Data Pin:
  • For ESP32-C3: Pin 8
  • For ESP32-S3: Pin 9
  • If not installed: -1
• Color Order & Speed: Keep the defaults (GRB, 800 kHz).
• Operating Mode: Choose status (mirrors light effects and Wi-Fi) or independent (controlled separately in HomeGenie Panel).

Create this device now! 🪄

You can flash the pre-compiled firmware directly to your connected ESP board using the tool below. Select the appropriate target model (e.g., ESP32-C3 or ESP32-S3) and click Create device.

Connect your ESP32/ESP8266 microcontroller to your computer via USB, select your firmware version, and click "Create device" to upload the HomeGenie Mini firmware.

Automation Examples

Every HomeGenie Mini device includes a built-in Scheduler capable of executing lightweight JavaScript code for customized automation.

Linked Lights (Zero-Code and Scripted)

You can link multiple devices to control them as a group. For example, adjusting the brightness of a "Main Light" can automatically synchronize the brightness of a "Floor Lamp" and a "Ceiling Light".

In the video below, we demonstrate a simple, zero-code group linking using two preset scheduler tasks.

Open media

Alternatively, you can implement a highly optimized, single-task solution using a custom JavaScript action. The script triggers whenever the master light's brightness changes:

$$.boundModules.level = event.value

The bound devices (boundModules) will automatically copy the master's active level (event.value) in real-time.

Linked Lights schedule

Module event trigger and action to perform

Open media

Source Code

The complete source code and individual effect headers are available on GitHub:

folder_open color-light

Modules and API

In addition to the common Device API, the following modules and API endpoints are implemented by the color-light firmware.

C1 Module (Master Controller)

This is the master module that controls all primary LED strip or matrix pixels simultaneously.

Domain / Address

HomeAutomation.HomeGenie/C1

Properties

• Status.Level (Current master brightness level, 0.0 to 1.0. For matrix styles, this dynamically scales the maximum height of the equalizers/waves).
• Status.ColorHsb (Current master color in HSV format. In music modes, H maps to high frequencies/notes, S maps to mid-frequencies, and V maps to bass/volume).

Commands

• Control.On (Turns all LEDs on to the previous state)
• Control.Off (Turns all LEDs off)
• Control.Toggle (Toggles the power state of the LEDs)
• Control.Level/<level>/<transition_ms> (Sets the master brightness level 0-100)
• Control.ColorHsb/<h>,<s>,<v>,<transition_seconds> (Sets the master color. Hue, saturation, and brightness are normalized values from 0.0 to 1.0; the optional transition parameter is in seconds).

C2 Module (Auxiliary Controller LED)

Controls the optional secondary RGB indicator on the controller board.

Domain / Address

HomeAutomation.HomeGenie/C2

Commands

• Control.On
• Control.Off
• Control.Toggle
• Control.Level/<level>/<transition_ms>
• Control.ColorHsb/<h>,<s>,<v>,<transition_seconds>

Properties & Parameters

Behavioral note: In status mode, the auxiliary LED mirrors primary animations and network status without triggering continuous module events. In independent mode, the C2 module accepts distinct color and level controls independently of the main LED strip.

L1 ... L<num> Modules (Individual Pixels)

These modules control a single, specific LED corresponding to the index number <num>.

Domain / Address

HomeAutomation.HomeGenie/L<num>

Properties

• Status.Level (Current individual LED brightness level, 0.0 to 1.0)
• Status.ColorHsb (Current individual LED HSV color)

Commands

• Control.On
• Control.Off
• Control.Toggle
• Control.Level/<level>/<transition_ms>
• Control.ColorHsb/<h>,<s>,<v>,<transition_seconds>

Automation Module (Compiled Script Engine)

This module manages the non-blocking execution of the compiled binary bytecode scripting engine.

Domain / Address

HomeAutomation.HomeGenie/Automation

Commands

• Script.Run/<script_text>
  Compiles and executes a custom light animation script on the fly. The script supports standard or abbreviated timestamps, pixel ranges, 2D coordinates (row:col), region offsets (+length, +width:height rectangles), LEVEL scaling, HSB transitions, and control-flow instructions (#N, #REPEAT, #LOOP).
• Script.Clear
  Clears the active script from memory. If Script remains the selected mode, the built-in fallback animation will resume.