The HomeGenie Smart Light is a fully autonomous 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.

The two videos below showcase the firmware running on a standard 16x16 LED matrix (256 pixels). The first video is a quick teaser showing the procedural Black Hole effect, while the second is a comprehensive showcase of several mathematical patterns synchronized in real-time to music.

HomeGenie Smart Light Teaser (1/2)

Open media

HomeGenie Smart Light Showcase (2/2)

Open media

Product Features

• money High-Performance Rendering: Smooth fluid transitions and particle-physics effects calculated at a solid 100Hz refresh rate.
• 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 auto-off timers.
• api Convenient Control: Fully manageable via the free, HomeGenie Panel app, physical buttons, or a rich HTTP API.

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.

LED Controller Kit Functionality

To make building your own device as simple as possible, this page introduces the LED Controller Kit: a quick-start DIY hardware project using readily available components you can find in any electronics store.

The video below demonstrates the HomeGenie DIY LED controller, providing a quick overview of its physical button controls.

Open media

DIY: Build Your Own Smart Light

You can easily build your own DIY smart light using the HomeGenie Mini color-light firmware, combined with the custom-designed LED Controller Kit v1.5 and addressable RGB LEDs.

The project consists of three main components:

• LED Controller Kit: A custom PCB shield paired with a compact, 3D-printed translucent enclosure.
• LED Strip or Matrix: A 5V addressable RGB LED strip (supporting up to 4096 pixels) or a serpentine matrix panel.
• Light Enclosure (Optional): A 3D-printed casing designed to house and diffuse the LED strip or matrix in the shape or form of your choice.

WS2812B LEDs: Selection & Sourcing

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). A higher density (such as 60 or 144 LEDs/m) provides smoother light diffusion inside 3D-printed enclosures.
• 16x16 or 8x32 Serpentine Matrix Panel (5V): A flexible grid ideal for displaying animations, icons, or text.

WS2812B LED Matrix Types

Open media

WS2812B LED Strip Types

Open media

Where to Buy

WS2812B strips and matrices are easy to find online and at electronics hobbyist stores:

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

3D-Printed Enclosures & Lamps

The final step in building your smart light is housing it in a 3D-printed enclosure or lamp body. A proper casing protects the electronics and diffuses the sharp light of individual LEDs into a soft, appealing glow.

Where to Find Ready-to-Print Models

You do not need to design a lamp from scratch. There are thousands of free, creative designs specifically made for WS2812B strips and 16x16 matrices.

• Popular Platforms: Search platforms like Printables, Thingiverse, or MakerWorld using keywords such as:
  • "WS2812B lamp"
  • "LED matrix frame"
  • "Serpentine 16x16"
  • "Diffused LED lamp"
• Custom Projects: If you prefer to design your own lamp, you can use CAD software like Tinkercad, Fusion 360, or Shapr3D to model a shape tailored to your space.

Printing Tips for Best Results

• The Diffuser: The part of the print that covers the LEDs must scatter the light. Use a translucent or white filament (such as White PLA or Natural/Translucent PETG). Printing this section with thin walls (1 to 2 perimeters) and 100% infill helps prevent internal infill patterns from casting shadows.
• The Body: Use opaque PLA or PETG in any dark or solid color for the rest of the lamp structure to block light leakage and direct all illumination through the diffuser.

Get your ESP32-S3 Zero Development Board

LED Controller Kit v1.5

The LED controller kit consists of a custom PCB shield designed for the ESP32-C3/S3 Zero development board and a compact 3D-printed enclosure. The device can safely drive addressable WS2812x LEDs for a maximum power of 10-15W.

The translucent enclosure lets the onboard RGB status LED remain visible, creating a nice color/status feedback even before an external LED strip is plugged in.

Open media

Open media

PCB Shield & Components

On the upper side of the PCB there are two buttons, while on the lower side there are the two 9-pin header connectors on which the ESP32 board is connected, and the JST connector cable to which the LED strip is connected.

Components listing:

• 2 momentary tactile push button switches (6x6x5mm THT)
• 2 single row female headers 9 pin (pitch 2.54mm, head 8.50mm)
• 1 JST SM 3-pin male connector cable for WS281x LED strips

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 v1.5 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 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%

Plastic Enclosure Assembly

The enclosure can be printed in translucent PETG. It takes about 45 minutes on any standard 3D printer (e.g., Bambu Lab A1-mini) using a 0.4mm nozzle and a 0.16mm layer height.

LED controller kit

Open media

STEP 1

Push the button caps in place.

Open media

STEP 2

Insert the PCB and the ESP32 board.

Open media

STEP 3

Add the bottom lid.

Open media

Open media

Open media

Archie 🌀 Mood Lamp

Archie is a custom 3D-printed casing for 1-meter LED strips, designed in the shape of an Archimedean spiral. The spiral is an ancient, cross-cultural symbol representing growth, natural cycles, and transformation.

Combined with the slow, non-blocking visual effects of the color-light firmware, Archie is perfect as a relaxing meditation lamp. It is also an excellent device to test in "Party Mode" using the HomeGenie Panel app while listening to your favorite ambient music.

Archie 3D model

Open media

Ready to assemble Archie

Open media

Archie + 1mt LED strip with 60 pixels

Open media

Archie + 1mt LED strip with 144 pixels

Open media

Archie Mood Lamp is an original concept and design by G-Labs licensed under CC BY-NC 4.0

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 level event occurs:

$$.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

Project Files Download

LED Controller Kit

PCB Gerber download REV. 19

Enclosure 3MF download REV. 2

Archie 🌀 Mood Lamp

Download LED strip casing 3MF REV. 16

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

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.

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 LED 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>,<b>,<transition_ms> (Sets the master color. Hue and Saturation are values from 0.0 to 1.0, and b is scaled by the master dimmer).

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>,<b>,<transition_ms>

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 currently running script and turns off any active script animations.