ESP32-S3 Smart Home Control Panel

A feature-rich, touch-screen Smart Home Control Panel built for the Waveshare ESP32-S3-Touch-LCD-4B. This project integrates WiFi, MQTT (Home Assistant), Weather tracking, and Power Management into a sleek UI designed with SquareLine Studio and powered by LVGL.

Please note: some are work in progress (WIP)

📚 Documentation

Additional documentation is available in the docs/ directory.

• Settings guide: Settings.md
• HomeScreen guide: HomeScreen.md
• Home Assistant configuration guide: HomeAssistant.md

🌟 Features

🏠 Smart Home Control (MQTT)

• Grid Control: 9 dedicated switch buttons for common switches (Light, Fan, AC, Plug, TV, Bed, Lock, Heater, All).
• Bi-Directional Sync: Updates UI state based on incoming MQTT messages and publishes commands immediately on touch.
• Customizable Topics: MQTT Host, Port, Credentials, and Notification topics are fully configurable via the on-device Settings menu.

🌤️ Weather & Location

The system uses a smart Hybrid Location Strategy to ensure weather and time data are always accurate, even after a reboot.

• Dual-Mode Location:
  • Auto (IP-Based): Automatically detects your city and coordinates using your WiFi's public IP via ip-api.com.
  • Manual Override: Search for any city globally using the built-in keyboard. The system uses the open-meteo Geocoding API to find the exact latitude/longitude.
• Persistent Settings: Your chosen location (whether Auto or Manual) is saved to the ESP32's non-volatile memory (NVS). The device wakes up knowing exactly where it is, without needing to re-fetch data immediately.
• Live Weather: Fetches real-time weather conditions from open-meteo.com (No API Key required).
• Dynamic UI: The home screen adapts to your environment:
  • Conditions: Visuals change for Clear, Rain, Snow, Clouds, Thunderstorms, and Fog.
  • Day/Night Cycle: Backgrounds automatically switch between Day and Night themes based on your location's local sunset/sunrise times.

🔔 Notification System

• MQTT Alerts: Receive text notifications directly from Home Assistant (via ha/panel/notify).
• History Center: Stores up to 15 recent notifications in a scrollable list.
• Popup Actions: Read details or delete individual alerts; "Clear All" functionality included.
• Visual Indicators: Home screen badge count for unread alerts.

💡 Display & Power Settings

The device now includes a dedicated settings screen to customize the display behavior and power consumption. All settings are saved to flash memory.

• Brightness Control:

  • A drag-slider allows real-time adjustment of the backlight intensity (0% to 100%).
  • 0% is calibrated to the lowest visible dim level (PWM 120).
  • 100% is maximum brightness (PWM 0).

• Configurable Timeouts:

  • Screensaver: Select how long the device waits before dimming the screen (15s, 30s, 1m... up to 10m or Never).
  • Deep Sleep: Select how long the device waits in Screensaver mode before turning the backlight completely OFF (1m... up to 10m or Never).
  • Smart Logic: The system automatically ensures Deep Sleep time is always greater than Screensaver time to prevent configuration conflicts.

• Wake-Up Behavior:

  • Touch: Touching the screen while it is in Deep Sleep (Off) will wake it to the Screensaver (Dimmed) state first. A second touch wakes it to the Home Screen.
  • Motion: Moving the device (via the QMI8658 IMU) triggers the wake-up sequence.

⚙️ System & Connectivity

• WiFi Manager: On-screen WiFi scanning, password entry, and "Saved Networks" management (stores up to 5 networks).
• Timekeeping: Automatic NTP synchronization or Manual RTC (PCF85063) setting via keypad.
• Persistence: All settings (WiFi, MQTT, Device Name) are saved to Non-Volatile Storage (Preferences).

🔋 Power Management

• Hardware Integration: Full support for AXP2101 PMU to monitor battery percentage, voltage, and charging status.
• Screensaver & Sleep:
• 30 Seconds: Dim screen/Show Screensaver (Clock & Weather).
• 60 Seconds: Turn off backlight to save battery.
• Wake: Tap screen or shake device (IMU-based wake using QMI8658).

🎨 UI & UX Improvements

• Auto-Closing Popups: Alerts and confirmation dialogs now automatically close after 10 seconds to prevent the UI from getting stuck if you walk away.
• Input Blocking: During WiFi connections or API calls, a global loader appears to prevent accidental clicks, ensuring connection stability.

🛠️ Hardware Specifications

• Development Board: Waveshare ESP32-S3-Touch-LCD-4B
• Display: 4.0-inch IPS, 480x480 Resolution (RGB Interface)
• Touch Controller: GT911 (Capacitive)
• Processor: ESP32-S3-WROOM-1-N16R8 (Xtensa® 32-bit LX7)
• Power Management: AXP2101
• IMU (Accelerometer/Gyro): QMI8658C
• RTC: PCF85063
• IO Expander: XCA9554

---

🚀 Setup Guide

1. Clone the Repository: Download the project files.
2. UI Files: Ensure the Screens folder (generated by SquareLine Studio) is in the same directory as your libraries folder.
3. Install Libraries: Use the Arduino Library Manager and Manual library configuration to install the dependencies listed below.
4. Install Boards: Use the Arduino Boards Manager to install the dependencies listed below.
5. Compile & Upload: Connect the board via USB-C and upload using the settings provided.
6. On-Device Setup:
   • Upon first boot, go to Settings > WiFi Setup.
   • Scan and Connect to your WiFi.
   • Go to Settings > Home Assistant.
   • Enter your MQTT Broker IP, Port (usually 1883), User, and Password.
   • Save Settings.

📦 Library Installation

This project requires specific driver libraries provided by Waveshare to function correctly with the display, touch, and power management chips.

Download Required Libraries: ESP32-S3-Touch-LCD-4B Demo (Zip)

Installation Steps:

1. Download the ZIP file linked above.

2. Unzip the file.

3. Locate the libraries folder inside the unzipped directory.

4. Copy the contents of that libraries folder into your Arduino libraries directory (Usually Documents/Arduino/libraries).

   • This installs: Arduino_GFX, XPowersLib, SensorLib (QMI8658/PCF85063), and lvgl configured for this board.

5. Replace the existing lv_conf.h file in your Arduino libraries directory with the one provided at libraries/lv_conf.h * IMPORTANT *

6. Additional Libraries: If not included in the ZIP, install the following via the Arduino Library Manager:

   • PubSubClient by Nick O'Leary (v2.8)
   • ArduinoJson by Benoit Blanchon (v7.4.2)

7. Boards: Install the following via the Arduino Boards Manager:

   • Arduino ESP32 Boards by Arduino (v2.0.18-arduino.5)
   • esp32 by Espressif Systems (v3.3.6)

Arduino IDE Board Settings

Setting	Value
Board	ESP32S3 Dev Module
Port	COMx / /dev/ttyUSBx
USB CDC On Boot	Enabled (Required for Serial)
CPU Frequency	240MHz (WiFi)
Core Debug Level	None / Info
Erase All Flash	Disabled
Events Run On	Core 1
Flash Mode	QIO 80MHz
Flash Size	16MB (128Mb)
JTAG Adapter	Disabled
Arduino Runs On	Core 1
Partition Scheme	Custom Defined by partitions.csv
PSRAM	OPI PSRAM (Crucial for 480x480 Display)
Upload Speed	921600

💾 Partitions Configuration

Due to the large size of the GUI assets, the default ESP32 partition scheme is insufficient. Created partitions file to allocate 10MB for the application, ensuring enough space for LVGL images.

# Name,   Type, SubType, Offset,  Size, Flags
nvs,      data, nvs,     0x9000,  0x5000,
otadata,  data, ota,     0xe000,  0x2000,
app0,     app,  ota_0,   0x10000, 0xA00000,
spiffs,   data, spiffs,  0xA10000,0x5F0000,

---

🔍 Troubleshooting

• Screen is black but code is running: Ensure PSRAM is set to OPI PSRAM. The 480x480 frame buffer requires OPI PSRAM to initialize the RGB interface.
• Compilation Error: 'class Arduino_RGB_Display' has no member named 'Display_Brightness'.
  • Fix: This project uses a custom driver implementation. Ensure you have copied the libraries folder from the Waveshare Demo zip specifically into your Arduino libraries folder.
• Backlight Control: The backlight is controlled via the AXP2101 PMU (DLDO1). Standard analogWrite on a GPIO will not work.

🎨 Assets & UI Resources

The project includes an assets folder containing the graphical elements used to design the interface in SquareLine Studio. These images are compiled directly into the source code (referenced in ui.h) during the export process.

Folder Structure

assets/
├── bg/  # Background PNGs used for the Homescreen
│   ├── bg3rc2.png
│   └── bg6rc2.png
└── ha-icons/  # PNG Icons used for HomeAssistant elements
    ├── ac.png
    ├── dryer.png
    ├── fan.png
    ├── lightbulb.png
    └── ... (Icons updated via json data of mqtt)
├── scenes/   # Background PNGs used for the Screensaver (Sleep Screen)
│   ├── clear_day.png
│   ├── clear_night.png
│   ├── rain_day.png
│   ├── snow_night.png
│   └── ... (Dynamic backgrounds based on weather conditions)
│
└── weather/  # PNG Icons representing specific weather statuses
    ├── weather_day.png
    ├── weather_cloudy.png
    ├── weather_rain.png
    ├── weather_storm.png
    └── ... (Icons updated via Open-Meteo API data)

Integration Note

In SquareLine Studio, these assets were imported to create the image widgets (ui_ImgBg and ui_IconWeather). The C array definitions for these images are automatically generated in the exported ui_img_...c files, allowing the ESP32 to render them without an external SD card.

Images used in screensaver backdrop are generaed using Google Gemini

---

Project Gallery

NoData Screen	Screen Saver	Settings Page	Housing
HA Screen	Notifications Screen	WiFi Settings	HA Settings
Date/Time Screen	Location Screen	System Status	About Page

---

📝 Credits & References

• Board Manufacturer: Waveshare
• UI Design: SquareLine Studio
• Graphics Library: LVGL
• Weather Data: Open-Meteo
• Location Data: IP-API