HomeDash

HomeDash is an ESP32-S3 based smart home control panel project using LVGL for the UI. It integrates voice, music, radio and sensors through MQTT and provides a touchscreen interface.

Current status (short):

• Build: succeeded locally (PlatformIO, environment esp32_4848s040).
• GUI: Active redesign to an Echo Show-inspired look. Shared LVGL styles and helper functions were added and applied to the Home, Voice, Music, Radio and Sensors screens (src/gui_screens.cpp).
• Hardware: Display and GT911 touch drivers are functional. Some earlier display test-pattern and LVGL perf overlay remain visible on the device and will be removed in a follow-up change.

Next steps:

• Tweak layout padding and alignment (user-reported widget placement issues).
• Remove display test pattern & disable LVGL perf monitor overlay.
• Final device testing (touch calibration, responsiveness) and OTA/upload.

See lvgl_gui_status.md and project_status.md for more details.

HomeDash - ESP32-S3 Smart Home Control Panel

A professional-grade smart home control panel built on the ESP32-4848S040 board featuring a 480x480 IPS display. Controls multiple Raspberry Pi applications via MQTT including Home Assistant Voice Satellite (Wyoming Protocol), music/radio players, and environmental sensors.

🎯 Features

• 480x480 IPS Touchscreen Display - Capacitive touch with LVGL GUI
• MQTT Communication - TLS/SSL support, auto-reconnection
• WiFi Management - Auto-connect, AP fallback mode, credential storage
• Voice Satellite Control - Wyoming protocol integration
• Music & Radio Player - Full playback control
• Sensor Monitoring - Temperature, humidity, air quality
• Home Assistant Integration - Direct service calls and state management
• OTA Updates - Over-the-air firmware updates
• Configuration Management - NVS-based persistent storage
• Modular Architecture - Clean, maintainable codebase

📋 Hardware Requirements

ESP32-4848S040 Board Specifications

• MCU: ESP32-S3 Dual-core Xtensa @ 240MHz
• RAM: 512KB SRAM + 8MB PSRAM (Octal SPI)
• Flash: 16MB (Quad SPI)
• Display: 4.0" IPS LCD 480x480 (ST7701 driver)
• Touch: Capacitive touch panel (GT911/FT6336)
• Connectivity: WiFi 802.11 b/g/n, Bluetooth 5.0 (BLE)
• USB: USB-C for programming and power

Additional Requirements

• Raspberry Pi (for running controlled applications)
• MQTT Broker (Mosquitto recommended)
• Power supply: 5V/2A via USB-C

🚀 Getting Started

Prerequisites

1. PlatformIO IDE (VSCode extension recommended)

   # Install PlatformIO CLI
   pip install platformio

2. ESP-IDF v5.1+ (handled by PlatformIO)

3. MQTT Broker running on your network

Installation

1. Clone the repository

   git clone <repository-url>
   cd HomeDash

2. Configure WiFi and MQTT

   Edit src/main.cpp or use the web interface after first boot:

   // Default configuration in config_manager.cpp
   strcpy(config->wifi_ssid, "YourWiFiSSID");
   strcpy(config->wifi_password, "YourPassword");
   strcpy(config->mqtt_broker, "mqtt://192.168.1.100");
   config->mqtt_port = 1883;

3. Build and Upload

   # Build the project
   pio run -e esp32_4848s040
   
   # Upload to board
   pio run -e esp32_4848s040 --target upload
   
   # Monitor serial output
   pio device monitor

📡 MQTT Topics

Device Status

homedash/status                 # Device online/offline status

Voice Satellite (Wyoming Protocol)

homedash/voice/state            # Current state (subscribe)
homedash/voice/listen           # Start/stop listening (publish)
homedash/voice/volume           # Set volume (publish)
homedash/voice/mute             # Mute/unmute (publish)
homedash/voice/wakeword         # Enable/disable wake word (publish)

Music Player

homedash/music/state            # Current state (subscribe)
homedash/music/control          # play/pause/stop/next/prev (publish)
homedash/music/volume           # Set volume (publish)
homedash/music/shuffle          # Enable/disable shuffle (publish)
homedash/music/repeat           # Enable/disable repeat (publish)
homedash/music/seek             # Seek to position (publish)

Radio Player

homedash/radio/state            # Current state (subscribe)
homedash/radio/control          # play/stop (publish)
homedash/radio/station          # Change station (publish)
homedash/radio/volume           # Set volume (publish)

Sensors

homedash/sensors/data           # Sensor readings (subscribe)
homedash/sensors/request        # Request update (publish)

Home Assistant

homedash/ha/service             # Call HA service (publish)
homedash/ha/set_state           # Set entity state (publish)
homedash/ha/get_state           # Get entity state (publish)

📄 Message Formats

Voice Satellite State

{
  "mute": false,
  "volume": 80,
  "listening": true,
  "wake_word": "hey_jarvis",
  "wake_word_enabled": true
}

Music Player State

{
  "playing": true,
  "volume": 75,
  "track": "Song Title",
  "artist": "Artist Name",
  "duration": 240000,
  "position": 45000,
  "shuffle": false,
  "repeat": false
}

Sensor Data

{
  "temperature": 22.5,
  "humidity": 45.2,
  "pressure": 1013.25,
  "co2": 450,
  "voc": 120
}

Command Examples

// Play music
{"action": "play"}

// Set volume
{"volume": 50}

// Call HA service
{
  "domain": "light",
  "service": "turn_on",
  "entity_id": "light.living_room"
}

🏗️ Architecture

HomeDash/
├── include/
│   ├── main.h                  # Main application header
│   ├── config_manager.h        # Configuration management
│   ├── wifi_manager.h          # WiFi connection handling
│   ├── mqtt_client.h           # MQTT client wrapper
│   ├── app_controller.h        # Application control logic
│   ├── display_driver.h        # Display driver interface
│   ├── touch_driver.h          # Touch driver interface
│   ├── gui_manager.h           # LVGL GUI management
│   └── lv_conf.h              # LVGL configuration
├── src/
│   ├── main.cpp               # Main application
│   ├── config_manager.cpp     # Config implementation
│   ├── wifi_manager.cpp       # WiFi implementation
│   ├── mqtt_client.cpp        # MQTT implementation
│   └── app_controller.cpp     # App control implementation
├── platformio.ini             # PlatformIO configuration
├── partitions.csv             # Flash partition table
└── sdkconfig.defaults         # ESP-IDF defaults

Modular Design

Configuration Layer

• NVS-based persistent storage
• JSON configuration support
• Factory reset capability

Communication Layer

• WiFi with auto-reconnect
• MQTT with TLS/SSL support
• QoS levels for reliability

Application Layer

• Modular app controllers
• Event-driven architecture
• Callback-based updates

UI Layer (To be implemented)

• LVGL 8.3 graphics
• Multi-screen navigation
• Touch input handling

🔧 Configuration

First Boot

On first boot, the device will:

1. Create an Access Point: HomeDash-Setup
2. Password: homedash123
3. Connect to configure WiFi and MQTT settings
4. Reboot and connect to configured network

NVS Storage

Configuration is stored in NVS (Non-Volatile Storage):

• WiFi credentials
• MQTT broker settings
• Display preferences
• Home Assistant URL and token

Factory Reset

To reset to factory defaults:

config_manager_reset();

🛠️ Development

Adding New Features

1. Create header file in include/
2. Implement in source file in src/
3. Register callbacks in main application
4. Update MQTT topics as needed

Code Style

• Use descriptive variable names
• Document all public APIs
• Follow ESP-IDF coding standards
• Use ESP_LOG macros for logging

Testing

# Run unit tests
pio test

# Monitor with filters
pio device monitor --filter esp32_exception_decoder

🐛 Troubleshooting

WiFi Connection Issues

• Check SSID and password in configuration
• Verify 2.4GHz network (ESP32 doesn't support 5GHz)
• Check router firewall settings

MQTT Connection Issues

• Verify broker IP address and port
• Check broker is running: mosquitto -v
• Test with mosquitto_sub: mosquitto_sub -h <broker> -t "#" -v

Display Issues

• Verify pin connections match display_driver.h
• Check backlight PWM configuration
• Adjust brightness settings

Build Errors

# Clean build
pio run --target clean

# Update dependencies
pio pkg update

# Full rebuild
pio run --target fullclean
pio run

📚 API Reference

WiFi Manager

esp_err_t wifi_manager_init(void);
esp_err_t wifi_manager_connect(const wifi_config_t *config);
bool wifi_manager_is_connected(void);
int8_t wifi_manager_get_rssi(void);

MQTT Client

esp_err_t mqtt_client_init(const mqtt_config_t *config);
int mqtt_client_publish(const char *topic, const char *payload, size_t len, int qos, bool retain);
int mqtt_client_subscribe(const char *topic, int qos);
bool mqtt_client_is_connected(void);

App Controller

esp_err_t app_music_play(void);
esp_err_t app_music_set_volume(uint8_t volume);
esp_err_t app_voice_start_listening(void);
esp_err_t app_sensors_request_update(void);

🔮 Future Enhancements

• Complete LVGL GUI implementation
• Touch calibration utility
• Web-based configuration portal
• Weather widget integration
• Calendar and reminders
• Voice feedback via speaker
• Multiple theme support
• Screen saver with photo slideshow
• Energy monitoring dashboard

📖 Raspberry Pi Integration

See RASPBERRY_PI_INTEGRATION.md for:

• Setting up MQTT bridge on Raspberry Pi
• Wyoming voice satellite configuration
• Music player integration
• Sensor daemon examples

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

🙏 Acknowledgments

• ESP-IDF framework by Espressif
• LVGL graphics library
• PlatformIO build system
• Home Assistant community
• Wyoming Protocol developers

📧 Support

For issues and questions:

• GitHub Issues: [Create an issue]
• Documentation: [Wiki]
• Community: [Discord/Forum]

---

Built with ❤️ for the Smart Home community