HomeGenie Mini is an open source library for building custom firmware for smart devices based on ESP32 or ESP8266 SoC. It allows you to create fully independent smart devices with local logic, cloud-free operation, and built-in JavaScript automation.
- Easy web-based installation directly from your browser (via Web Serial API)
- Easy device configuration using Wi-Fi protected setup button (WPS) or Bluetooth
- Does not require an Internet connection to be configured or to work properly
- Time synchronization using internal RTC (ESP32), mobile app time or NTP
- Integrated actions scheduler supporting extended Cron expressions and JavaScript
- Device discovery via SSDP/UPnP with customizable device name
- Multichannel I/O: HTTP, WebSocket, SSE, MQTT, Serial
- Built-in status LED logic and GPIO control API
- Multi-threading support, event router, extensible API
- Direct connection to HomeGenie Panel (Wi-Fi AP, hotspot or local network)
- Seamless integration with HomeGenie Server and other services via MQTT
Depending on your preference, you can flash the firmware either directly from your browser or compile it manually using the CLI.
If you prefer a quick, visual setup without installing coding tools, you can upload pre-compiled firmwares directly from the browser:
- Connect your ESP device to your computer via USB.
- Open the HomeGenie Mini Getting Started Page.
- Use the Firmware Upload form at the bottom of the page: select your SoC model, enter your Wi-Fi credentials (optional), and click Create device.
To customize and compile the firmware from source code, install Platform.IO core and download the HomeGenie Mini source code.
Open a terminal in the project directory and run the following commands to install the required dependencies:
pio pkg update
pio pkg installTo build and upload the default firmware to your connected ESP device, run:
pio run -e default -t uploadThe -e default option builds the base firmware for a generic ESP32 board.
To list all available configurations (including specific profiles for target devices), run:
pio project configYou can customize environments or define your own pin mappings and features by editing the platformio.ini file.
HomeGenie Mini provides several specialized configurations and ready-to-use firmware templates. You can find detailed guides, 3D printing files, and schematics on the official website:
- 📺 Smart Display & Control: Transforms an ESP32 with a TFT touch display into a local smart dashboard using LVGL or LovyanGFX.
- 🤖 Smart Car & Robotic Arm: Configures multi-servo motor control (
smart-motorfirmware) for DIY robotics and Mecanum wheels. - 📷 Smart Camera + A.I.: Implements video streaming and object tracking logic using ESP32-CAM models.
- 💡 Smart Light / Mood Lamp: Controls WS281x RGB LED strips with automated transitions, schedules, and custom animations.
- 🌡️ Smart Sensor: Gathers data from DHT22, LDR, and motion sensors with low overhead.
- 📟 Remote Control & Gateway: A transceiver gateway to capture and replay IR/RF commands.
Once the firmware is installed, the status LED will blink continuously, indicating the device is not yet connected to a network. You can connect it using one of these methods:
If you flashed your device using the browser-based Web Installer, you can pre-configure the Wi-Fi credentials. If you need to update them later, enter the new credentials, check "Initialize only" on the upload form, and click Create device to write only the configuration parameters without re-flashing the firmware.
- Enable WPS on your router.
- Press and hold the WPS button on your ESP device (often labeled as
BOOTorB) for at least 5 seconds. - The LED will turn solid while pairing, blink quickly for 5 seconds when connected, and then switch to a slow, steady pulse.
- Turn on Bluetooth on your smartphone and open the HomeGenie Panel app.
- Go to the connection discovery page. The app will detect the new device over Bluetooth and open a setup wizard to configure the device name and Wi-Fi credentials.
Once connected, your device will appear in the HomeGenie Panel dashboard.
HomeGenie Mini devices can communicate with HomeGenie Server and other brokers by configuring the MQTT client as shown below:
To monitor logs and interact with the device via the serial interface, connect your device to your USB port and run:
pio device monitor -b 115200You can configure the device or query its status directly from the serial terminal. Enter system commands prefixed by # or use /api/ prefix for API commands.
#CONFIG:device-name <name>#CONFIG:wifi-ssid <ssid>#CONFIG:wifi-password <passwd>#VERSION/#RESET/#UPTIME/#WPS
#GET:<parameter_key>#SET:<parameter_key> <value>
| Key | Description | Default |
|---|---|---|
sys-rb-n |
Factory reset button GPIO# | -1 (disabled) |
sys-sl-n |
System status LED GPIO# | -1 (disabled) |
io-typ01 |
I/O Ch.1 type ('Switch', 'Light', 'Dimmer') | |
io-pin01 |
I/O Ch.1 GPIO# | -1 (disabled) |
Example setting status LED and reset button:
#SET:sys-sl-n=10
#SET:sys-rb-n=0
#RESET
THIS PROJECT IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS PROJECT, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.