# 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](app_config.hpp):
```cpp
#define DEFAULT_SSID "YOUR_SSID"
#define DEFAULT_PASSWORD "YOUR_PASSWORD"
```

### Display Configuration
The display parameters are configured in [app_config.hpp](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
```bash
cd /Users/brent/zonebridge/zonebridge
source ./setup_esp_env.sh
idf.py build
```

## Common Commands

```bash
# 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
- [x] C++ conversion
- [x] FreeRTOS integration
- [x] Component hierarchy
- [x] 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](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
```bash
# 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](https://docs.espressif.com/projects/esp-idf/en/latest/)
- [LVGL Documentation](https://docs.lvgl.io/)
- [Waveshare Product Page](https://www.waveshare.com/esp32-s3-touch-lcd-4.3.htm?sku=25948)
- [ESP32-S3 Datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf)