INVERTER-ESP - Solar Inverter Data Logger with E-Paper Display

ESP32-S3 based solar inverter monitoring system with E-Paper display and cloud API integration.

🎯 Project Overview

Hardware: CrowPanel ESP32 E-paper 2.9-inch HMI Display
Display: 296×128 pixel E-Paper (Monochrome)
MCU: ESP32-S3 (Dual-Core, 240MHz, 512KB RAM + 2MB PSRAM)
Connectivity: WiFi 802.11 b/g/n

Primary Functions

📊 Data Collection: Read solar inverter data from local network
☁️ Cloud Upload: POST data to SolarLog API (https://solarlog-api.karma.organic)
📱 Local Display: Show current production and status on E-Paper display
⚙️ System Info: Display network status and device info
🔘 Button Navigation: 3 physical buttons for screen switching

🏗️ Project Structure

INVERTER-ESP/
├── README.md                    ← You are here
├── HARDWARE.md                  Hardware specifications
├── API_INTEGRATION.md           SolarLog API documentation
├── DEPLOYMENT.md                ESP32 flash & deployment guide
├── AGENT_HANDOVER.md            Current status & handover notes
├── TODO.md                      Task list for next agent
│
├── firmware/                    ESP32 firmware (C/C++)
│   ├── platformio.ini           PlatformIO configuration
│   ├── src/
│   │   ├── main.cpp             Main entry point
│   │   ├── display/             E-Paper LVGL driver
│   │   ├── network/             WiFi & API clients
│   │   ├── ui/                  LVGL UI screens
│   │   └── storage/             NVS configuration
│   └── lib/                     Dependencies (LVGL, etc.)
│
├── simulator/                   Desktop simulator (Swift/SDL2)
│   ├── Package.swift            Swift Package Manager config
│   ├── Sources/                 Swift source code
│   └── Public/                  Web assets (if needed)
│
├── assets/                      Fonts & icons for E-Paper
├── docs/                        Additional documentation
└── tests/                       Unit tests

🚀 Quick Start

Prerequisites

Hardware: CrowPanel ESP32 E-paper 2.9" HMI Display
Software:
PlatformIO Core (for ESP32 firmware)
Swift 6.0 + SDL2 (for simulator)
SolarLog API credentials (API key)

1. Simulator (Desktop Development)

cd simulator
swift build
swift run INVERTER-Simulator

Opens SDL2 window with E-Paper simulation (296×128 pixels).

2. ESP32 Firmware (Hardware Deployment)

cd firmware
platformio run --target upload
platformio device monitor

See DEPLOYMENT.md for detailed instructions.

📋 Features

✅ Implemented

🚧 In Progress

UI screens (Dashboard, History, SysInfo, Settings)
Mock data generator for simulator
API authentication

📅 Planned

OTA firmware updates
Historical data caching (24h)
Battery monitoring
Error logging

🖥️ Display Screens

Navigation: 3 physical buttons for screen switching

Screen 1: Dashboard 📊

Current production (W)
Today's energy (kWh)
Status icons (WiFi, Cloud, Inverter)
Timestamp

Screen 2: History 📈

Last 7 days bar chart
Monthly total
Comparison to previous month

Screen 3: System Info ⚙️

WiFi SSID + signal strength
IP address
API sync status
Memory usage
Uptime

Screen 4: Settings 🔧

WiFi configuration
API key entry
Update interval
Display contrast

🔌 Hardware Connections

E-Paper Display (SPI)

MOSI: GPIO 11
MISO: GPIO 13
SCK: GPIO 12
CS: GPIO 10
DC: GPIO 9
RST: GPIO 8
BUSY: GPIO 7

Buttons

Button 1: GPIO 0 (Next Screen)
Button 2: GPIO 14 (Previous Screen)
Button 3: GPIO 21 (Action/Refresh)

Note: Verify pin mapping with HARDWARE.md

🌐 API Integration

SolarLog API: https://solarlog-api.karma.organic/docs

Endpoints (TBD - see API_INTEGRATION.md)

POST /api/v1/inverters/{id}/data
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "timestamp": "2025-10-23T09:30:00Z",
  "power_w": 3500,
  "energy_kwh": 12.5,
  "status": "online"
}

📡 Data Flow

Solar Inverter (LAN)
    ↓ HTTP/Modbus/MQTT
ESP32 (INVERTER-ESP)
    ├─→ E-Paper Display (local)
    └─→ WiFi → Internet
            ↓
        SolarLog API (Cloud)
            ↓
        Data Storage & Processing

Update Intervals: - API Upload: Every 5 minutes (configurable) - Display Refresh: Every 30-60 seconds (E-Paper limitation) - Deep Sleep: Between updates (power saving)

⚡ Power Management

Strategy: Deep Sleep between data uploads

// Wake up every 5 minutes
void loop() {
    // 1. Connect WiFi
    // 2. Read inverter data
    // 3. POST to API
    // 4. Update E-Paper display
    // 5. Deep Sleep for 5 minutes

    esp_deep_sleep(5 * 60 * 1000000ULL);
}

Estimated Battery Life (with 2000mAh battery): - Deep Sleep: ~10µA - WiFi Active: ~150mA for ~30s - E-Paper Refresh: ~50mA for ~3s - Average: ~1-2mAh → 30-60 days battery life

🛠️ Development Workflow

Phase 1: Simulator ✅

Design UI screens in simulator
Test navigation logic
Mock inverter data
Verify display rendering

Phase 2: ESP32 Firmware ⚠️

Setup PlatformIO project
Integrate E-Paper driver
Port UI from simulator
Implement network layer
Test with real hardware

Phase 3: Deployment 🚀

Flash ESP32
Configure WiFi & API
Field test (24h)
Monitor logs

📚 Documentation

HARDWARE.md: Complete hardware specifications
API_INTEGRATION.md: SolarLog API documentation
DEPLOYMENT.md: Flash & deployment guide
AGENT_HANDOVER.md: Current status for next developer
TODO.md: Task list and priorities

🐛 Troubleshooting

Display not updating

Check SPI pin connections
Verify E-Paper driver initialization
Increase log level: #define LV_LOG_LEVEL LV_LOG_LEVEL_TRACE

WiFi connection fails

Check credentials in config.h
Verify router supports 2.4GHz (ESP32 doesn't support 5GHz)
Check signal strength (RSSI)

API upload fails

Verify API key is correct
Check internet connectivity
Review API endpoint URL
Enable HTTP debug logs

📞 Support

For issues and questions: 1. Check docs/ folder 2. Review AGENT_HANDOVER.md 3. Check CrowPanel ESP32 Wiki: https://www.elecrow.com/wiki/CrowPanel_ESP32_E-paper_2.9-inch_HMI_Display.html

📄 License

Project-specific license TBD.

Last Updated: 2025-10-23
Version: 0.1.0-alpha
Status: 🚧 Initial Setup