INVERTER-ESP Quick Start Guide

Get started with INVERTER-ESP in 5 minutes.

🎯 What is INVERTER-ESP?

Solar inverter monitoring system with: - ESP32-S3 microcontroller - E-Paper 2.9" display (296×128 pixels) - WiFi connectivity for cloud data upload - SolarLog API integration for data storage - 3 physical buttons for navigation

📋 Before You Start

⚠️ CRITICAL: Research Required

You MUST complete these research tasks before coding:

SolarLog API: Visit https://solarlog-api.karma.organic/docs
Get API key
Document authentication method
Test with curl
Solar Inverter: Identify your inverter model
Brand/Model: ____
Protocol: HTTP / Modbus / MQTT / Other?
How to connect: IP address / Serial / Cloud?
Hardware Verification: Check Elecrow wiki
Verify E-Paper SPI pins
Verify button GPIO pins
Test with example sketch

See AGENT_HANDOVER.md for detailed research tasks.

🚀 Option 1: Simulator (Desktop Development)

Best for UI development without hardware.

Prerequisites

# macOS
brew install swift sdl2

# Linux
sudo apt install swift libsdl2-dev

Steps

# 1. Navigate to project
cd /path/to/INVERTER-ESP

# 2. Copy LVGL infrastructure from DeINER
cp -r ../SwiftLVGL-Platform/Sources/CLVGL simulator/Sources/
cp -r ../SwiftLVGL-Platform/Sources/SwiftLVGL simulator/Sources/

# 3. Create Package.swift (adapt from DeINER)
# See AGENT_HANDOVER.md for details

# 4. Build
cd simulator
swift build

# 5. Run
swift run INVERTER-Simulator

Expected: SDL2 window opens showing 296×128 E-Paper simulation.

🔧 Option 2: ESP32 Firmware (Hardware)

Best for final deployment and testing.

Prerequisites

# Install PlatformIO
pip install platformio

# Or use VS Code extension: PlatformIO IDE

Steps

# 1. Navigate to firmware
cd /path/to/INVERTER-ESP/firmware

# 2. Edit config (WiFi, API key)
nano src/config.h

# 3. Connect ESP32 via USB-C

# 4. Build
pio run

# 5. Flash
pio run --target upload

# 6. Monitor
pio device monitor

Expected: Serial output shows WiFi connected, API upload success, display updated.

📚 Documentation

File	Purpose
README.md	Project overview
HARDWARE.md	Hardware specs & pinout
API_INTEGRATION.md	SolarLog API documentation
DEPLOYMENT.md	ESP32 flash & deployment guide
ARCHITECTURE.md	System design & data flow
AGENT_HANDOVER.md	Current status & next steps
TODO.md	Complete task checklist

🐛 Common Issues

Simulator won't build

✅ Install SDL2: brew install sdl2
✅ Copy CLVGL and SwiftLVGL from DeINER
✅ Check Package.swift configuration

ESP32 won't flash

✅ Check USB cable (data-capable, not charge-only)
✅ Install USB-UART drivers (CH340 or CP2102)
✅ Hold Boot button (GPIO0) while connecting

Display not working

✅ Verify E-Paper SPI pins (see HARDWARE.md)
✅ Test with Elecrow example sketch
✅ Check BUSY pin (GPIO7) is not stuck HIGH

WiFi won't connect

✅ Verify SSID/password in config.h
✅ Check router supports 2.4GHz (no 5GHz on ESP32)
✅ Move ESP32 closer to router

API upload fails (401)

✅ Verify API key is correct
✅ Check API endpoint URL
✅ Test with curl first

📞 Need Help?

Read Documentation: Check AGENT_HANDOVER.md for detailed info
Check TODO: See TODO.md for task breakdown
Hardware Issues: Check HARDWARE.md
API Issues: Check API_INTEGRATION.md
CrowPanel Wiki: https://www.elecrow.com/wiki/CrowPanel_ESP32_E-paper_2.9-inch_HMI_Display.html

🎯 Next Steps

Choose your path:

Path A: Start with Simulator (Recommended)

Read AGENT_HANDOVER.md
Complete Research Phase (API, Inverter, Hardware)
Copy CLVGL/SwiftLVGL from DeINER
Create Package.swift
Implement Dashboard screen
Test in SDL2 window

Path B: Start with ESP32 Firmware

Read DEPLOYMENT.md
Create platformio.ini
Create config.h (WiFi, API key)
Port UI screens from simulator
Test on hardware

Estimated Timeline: - Research Phase: 1-2 days ⚠️ CRITICAL - Simulator Development: 7-10 days - ESP32 Firmware: 10-14 days - Testing & Deployment: 5-7 days - Total: 3-4 weeks

Last Updated: 2025-10-23
Status: 🚧 Ready to Start
First Task: Research Phase (see TODO.md)