zonebridge/PROJECT_SETUP.md

ZoneBridge - ESP32-S3 Touch LCD Project Setup

Project Overview

This is a C++ ESP-IDF project for the Waveshare ESP32-S3-Touch-LCD 4.3" display with the following features:

• C++ Framework with proper C++ exception handling
• FreeRTOS for task management
• LVGL for UI/graphics on the 800x480 touch display
• WiFi connectivity
• HTTP Web Server for remote control/monitoring
• Touch Input support for the capacitive touch panel

Project Structure

main/
├── main.cpp                 # Entry point (C++)
├── app_config.hpp/cpp       # Application initialization and configuration
├── display_manager.hpp/cpp  # LVGL display handling and UI management
├── wifi_manager.hpp/cpp     # WiFi connectivity management
├── web_server.hpp/cpp       # HTTP web server implementation
├── lv_conf.h               # LVGL configuration
└── idf_component.yml       # Component dependencies

Configuration

WiFi Credentials

Edit these constants in app_config.hpp:

#define DEFAULT_SSID "YOUR_SSID"
#define DEFAULT_PASSWORD "YOUR_PASSWORD"

Display Configuration

The display parameters are configured in app_config.hpp:

• Resolution: 800x480
• Color Depth: 16-bit RGB565
• Display Driver: LVGL (software stack)

Web Server

• Default Port: 80
• Endpoints:
  • GET / - HTML dashboard
  • GET /api/status - JSON status endpoint

Building the Project

Method 1: VS Code Tasks (Recommended)

1. Open Command Palette: Cmd+Shift+P
2. Run "Tasks: Run Task"
3. Select "ESP-IDF: Build"

Method 2: Terminal

cd /Users/brent/zonebridge/zonebridge
source ./setup_esp_env.sh
idf.py build

Common Commands

# Build the project
idf.py build

# Clean build artifacts
idf.py clean

# Configure via menuconfig
idf.py menuconfig

# Flash to device and monitor
idf.py flash monitor

# Monitor serial output
idf.py monitor

# Analyze binary size
idf.py size

Hardware Notes

Waveshare ESP32-S3-Touch-LCD 4.3"

• Display: 4.3" 800x480 RGB LCD
• Touch Input: Capacitive touchscreen
• Connectivity: Built-in WiFi and Bluetooth
• Ports: USB-C for programming and power

Display Connection

The display is typically connected via:

• 16-bit parallel RGB interface (via LCDC peripheral)
• SPI interface (alternative, if RGB not used)
• I2C for touch controller (CST816)

Touch Controller

• Model: CST816S (capacitive touchpad controller)
• Interface: I2C (typically pins 19/20 on ESP32-S3)
• Interrupt: GPIO pin for touch interrupt

Implementation Tasks

Phase 1: ✓ Project Structure

• C++ conversion
• FreeRTOS integration
• Component hierarchy
• Basic LVGL setup

Phase 2: Display Driver

• RGB LCD driver initialization
• Touch input driver (CST816 I2C)
• Frame buffer management
• Display refresh loop

Phase 3: UI Development

• Main dashboard UI
• Status displays
• Control buttons
• Menu system

Phase 4: WiFi & Web

• WiFi connection handling
• Web dashboard enhancement
• REST API endpoints
• WebSocket support (optional)

Next Steps

1. Configure WiFi: Update WiFi credentials in app_config.hpp
2. Build & Test: Run build task to verify compilation
3. Flash Device: Use idf.py flash monitor to program device
4. Display Driver: Implement actual display hardware interface
5. Touch Input: Add touch controller driver

Troubleshooting

Build Errors Related to Components

# Rebuild component cache
rm -rf build
idf.py fullclean
idf.py build

LVGL Compilation Issues

• Ensure LVGL component is installed: idf.py component-manager create-manifest
• Check lv_conf.h matches your requirements

WiFi Connection Issues

• Verify SSID/password in app_config.hpp
• Check WiFi event handling in wifi_manager.cpp
• Monitor UART output: idf.py monitor

Resources

• ESP-IDF Documentation
• LVGL Documentation
• Waveshare Product Page
• ESP32-S3 Datasheet