HomeGenie
MINI 1.2 — Documentation

Firefly Smart Gateway

Smart IR / RF / X10 Gateway

Firefly is an open-source smart home hub that integrates traditional devices, including air conditioners, TVs, motorized gates, and remote-controlled sockets—into your connected home via Wi-Fi. The hub unifies standard IR remotes, 433/315 MHz radio frequency remotes, and classic X10 devices into a single app.

What you can do with Firefly :

Firefly Smart Sub-GHz and Infrared Gateway

by G-Labs


Open media

Even though it is a DIY project, building it is surprisingly simple. There is no messy wiring and zero soldering needed: standard, ready-made electronic modules plug directly into the Firefly board like Lego bricks, fitting neatly inside a 3D-printed translucent case that doubles as a decorative soft light.

The Concept: Snap-together modules

Instead of a single, complex circuit board, Firefly relies on four separate, interchangeable modules. Each component handles a dedicated task and connects directly to the main board via standard pin headers:

1. Microcontroller Core ESP32-S3

ESP32-S3-Zero / ESP32-C3-Zero mini development board
The processing brain of the gateway. It runs the HomeGenie Mini firmware, manages Wi-Fi connectivity, local automations, and scheduling. It plugs face-down into the Firefly board, directing its integrated RGB LED toward the base to serve as an illuminated status light.
Common models / Search keywords: Waveshare ESP32-S3-Zero

2. Sub-GHz Transceiver (TI CC1101)

TI CC1101 433MHz / 315MHz 8-pin SPI RF transceiver module with antenna
A software-configurable SPI radio transceiver equipped with an external antenna. It handles bidirectional 433.92 MHz and 315 MHz communication for standard RF remote controls, wireless wall switches, security sensors, and X10 home automation devices.
Common models / Search keywords: CC1101 433MHz 8-pin SPI Wireless Module with SMA antenna

3. High-Power IR Transmitter (38 kHz, 5V)

5V 38kHz infrared transmitter emission module
Emits 38 kHz infrared signals to control devices such as air conditioners, TVs, and audio systems. Powered directly from the 5V USB bus, it provides maximum optical output power and long-distance coverage (8–10+ meters).
Common models / Search keywords: 5V High-Power Infrared Transmitter 3-pin

4. IR Receiver Module (38 kHz)

38kHz infrared receiver sensor module with VS1838B
Captures and demodulates 38 kHz infrared signals emitted by physical remote controls in real-time, allowing Firefly to learn new commands instantly without manual code entry.
Common models / Search keywords: KY-022 IR Receiver Module

All four 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 build for anyone.

Semi-Transparent Case Shows Internal Components


Open media

In short, to build your own Firefly gateway, simply get these four modules and plug them into the Firefly board. You can get this board (PCB) and its 3D-printed case by ordering them from online fabrication services like JLCPCB or PCBWay using the open-source Gerber and 3D print files provided below.

Get your ESP32-S3-Zero Board

Practical Guide

Capturing and Replaying Commands

With the Firefly gateway and the HomeGenie Panel app, you can easily capture commands sent by your existing remote controls and wireless sensors. Once recorded, these sequences can be replayed on demand or scheduled automatically using the built-in Scheduler, without writing a single line of code.

  1. fiber_manual_record Start Recording: Open the HomeGenie Panel app and tap the Record Script icon in the upper-right corner. A status bar will appear at the bottom with a blinking timer showing 00:00.000, which stays on hold until the first signal is received, so you can take your time without rushing.

Start Recording


  1. tv_remote Press Remote Buttons: Aim your IR or RF remote at Firefly and press the buttons you want to record. You can combine commands from multiple remotes into the same sequence, and the system will faithfully preserve the exact pauses and timing intervals between button presses for authentic replay.

Press Remote Buttons


  1. stop Save the Script: Tap the Stop button on the bottom bar, enter a descriptive name for your new routine (e.g., "Fan ON" or "Movie Time"), and confirm with Save.

Save the Script


  1. play_arrow Replay Anytime: Tap the Play button at the bottom of the screen to open the saved programs list, then tap the play icon next to your routine (e.g., "Fan ON") to have Firefly instantly transmit the command to your appliance.

Replay Anywhere and Anytime


You can use this exact same workflow to automate and control virtually any IR or RF device in your home:

HomeGenie Panel lets you connect multiple Firefly gateways. Since you can also choose to enable remote access over the Internet, you can effortlessly control multiple devices across different rooms and locations using a single app!

Smart Schedules for Climate and Seasons

The Firefly gateway comes with a powerful built-in scheduler that lets you automate devices completely locally, without relying on third-party cloud subscriptions or internet connectivity:

  1. calendar_add_on Open Module Schedule: Tap the options menu (⋯) on the IR or RF widget, select Schedule, and tap the Add (+) button to create a new automated rule.
Navigating to module schedule and creating a new rule

  1. date_range Set Name, Target Module, and Time Window: Enter a name for the schedule (e.g., "Summer AC Cooling"), uncheck "Triggers following a module event" to use calendar-based scheduling, and configure the following parameters:
    • Bound Modules: Ensure the correct transceiver module (IR or RF) is selected under Bound modules. The Firefly device needs to know which hardware module will dispatch the commands.
    • Date Range: Select the seasonal date range (e.g., July 15 — September 15).
    • Time Slot: Set the daily time window (e.g., 12:00 PM → 6:00 PM).
    • Repeat: Choose the recurring days (e.g., Every day or Weekdays only).

Adding a Schedule


  1. settings_remote Configure Start & End Actions: Define the commands executed at the beginning and end of each time slot:
    • At start of a time slot: Check the box, select Remote control commands, and provide the target command string for turning on the AC at the desired temperature and mode (e.g., 26C Cool). The easiest way to do this is to tap the remote-control icon to capture the command live directly from the original remote control of your device.
    • At end of a time slot: Check the box and follow the same steps to assign the AC OFF command.
    • Multi-Command Sequences & Syntax: You can enter multiple commands (one per line). Each line supports an optional repeat and delay syntax using the format:
      <hex_code>/<repeat_count>/<repeat_delay_ms>
      Example: 00260009A5A3.../3/100 sends the code 3 times with a 100 ms interval between signals (defaults are 1 repeat and 1 ms delay if omitted).

Scheduling Remote Control Commands


  1. check_circle Save and Activate: Tap OK to save. The Firefly gateway will now run the routine autonomously on the device, ensuring your home stays comfortable while saving energy.

Event-Driven Automations

Besides time-based events, the built-in Firefly Scheduler can also trigger actions based on incoming IR and RF signals, such as toggling lights, relays, or scenes whenever a specific wireless button is pressed.

  1. sensors Capture the Signal: Press the physical remote-control button or wireless switch. Firefly intercepts the transmission and logs the unique packet under the "Receiver.RawData" property (e.g., C117D3E8).

  2. alt_route Create Event Trigger & Link Devices: Access the menu of the widget (⋯) to open the schedule manager and tap the Add (+) button to create a new rule:

Navigating to module schedule and creating a new rule

Scheduling Remote Control Commands


  1. toggle_on Assign Action on Occurrence: In the Action to perform section, check On every occurrence and select the command to execute:
    • Choose Toggle to alternate between ON and OFF on each incoming signal (or select Turn on, Turn off, Set color, Call HTTP URL, etc.).

  1. check_circle Save and Verify: Tap OK to save the rule. Whenever Firefly detects that specific signal, it will immediately execute the assigned action on all linked modules locally.

Control Multiple Devices

Integration with HomeGenie Server

Integrating Firefly with HomeGenie Server is seamless and straightforward. Like all devices running the HomeGenie Mini firmware, once connected to Wi-Fi, Firefly is automatically discovered by HomeGenie Server and appears among the UPnP modules.

Firefly UPnP Widget

Click the Connect button on the Firefly widget to link HomeGenie Server to Firefly over a persistent MQTT channel. Once connected, the IR and RF modules—along with any other hardware modules implemented on the Firefly device—will immediately become available in HomeGenie.

Firefly Connected Widget

Clicking the Modules button on the Firefly widget opens a dialog displaying the widgets for all modules available on Firefly (IR, RF), allowing you to add them directly to any dashboard group.

Firefly Modules Dialog

Once integrated with HomeGenie Server, all Firefly transceiver modules become native building blocks within the automation engine. You can create automation scripts that react in real time to incoming IR, RF, and X10 signals—such as triggering complex scenes whenever a wireless button or security sensor is activated. Centralized schedules can also broadcast IR and RF commands to automate traditional devices.

Visual block programming in HomeGenie Server triggering smart lights when an RF code is received


Open media

This brings different technologies together: a simple 433 MHz wall switch or an ordinary IR remote button can directly toggle modern ZigBee or Z-Wave lights throughout your home. It provides the ideal balance between everyday convenience and security: fast, battery-friendly physical controls for daily lighting, while keeping sensitive operations (such as smart door locks) protected on encrypted protocols.

How to Build Firefly

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

PCB Gerber download REV. 4A (v1.2+)

3D-Printed Case (3MF) download REV. 3A (v1.2+)

3D Printing Tips

The 3D case archive includes two versions of the 3MF project to ensure broad slicer compatibility. For the best light diffusion from the onboard status LED, printing in natural/translucent PETG or PLA is recommended. Select the appropriate file based on your slicing software:

Bill of Materials (BOM)

Modules you will need to source in order to complete the gateway:

It is recommended to power the device from a 5V USB power supply of at least 1A (2A preferred).

Get your ESP32-S3-Zero Board

Flash & Configure in 10 Seconds 🪄

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

1. Select device type

2. Select firmware flavor

VERSION  

3. Let the magic happen!

Installing firmware directly from this page works only in browsers with Web Serial API enabled.

⚠️ Having trouble uploading the firmware?

First, ensure that you do not have multiple ESP devices connected to your USB ports. Please connect only one device at a time.

If only one device is connected and the firmware uploader still fails to connect (or gets stuck at "Connecting..."), your device might need to be put into Boot Mode manually. (This is often required with development boards such as the classic ESP32-CAM).

START THIS PROCEDURE AFTER THE PORT SELECTION WINDOW APPEARS.
  1. Unplug the device from the USB port.
  2. Press and hold the RST and IO0 buttons.
  3. Plug the device back into the USB port (while still pressing the buttons).
  4. Release the buttons, then select the serial port from the list and confirm the upload.
Get your ESP32-S3-Zero Board

Developer Resources & Web API

Firefly exposes a clean REST API for seamless integration with third-party applications and custom scripts:

HTTP Examples:

# Send an IR signal (e.g. TV Power)
curl "http://<device_ip>/api/HomeAutomation.RemoteControl/IR/Control.SendRaw/0000006D.../1/100"

# Send a raw 433.92 MHz RF packet
curl "http://<device_ip>/api/HomeAutomation.RemoteControl/RF/Control.SendRaw/C133E068/10/100"

# Turn ON X10 module A1
curl "http://<device_ip>/api/HomeAutomation.X10/A1/Control.On"

# Set Dimmer A2 to 50%
curl "http://<device_ip>/api/HomeAutomation.X10/A2/Control.Level/50"

Source Code:

Pre-compiled binaries and source code are open-source on GitHub:

Modules and API

In addition to the common Device API, this device implements the following modules and API.

IR module

IR module is associated to IR transceiver hardware.

Domain / Address

HomeAutomation.RemoteControl/IR

Properties

Commands

RF module

RF module is associated to RF transceiver hardware.

Domain / Address

HomeAutomation.RemoteControl/RF

Properties

Commands

X10 module

RF module is associated to RF transceiver hardware.

Domain / Address

HomeAutomation.X10/RF

Properties

Commands

More topics

Setup

Create!

Programming

📖

🕵🏻 Explore Mini DeepWiki

Technical Docs & Interactive Wiki

Ask the AI 🧠
menu_open Browse Content