ARCHITECTURE.md - INVERTER-ESP System Architecture

Complete system design and data flow for INVERTER-ESP project.

🎯 System Overview

INVERTER-ESP is a dual-component solar inverter monitoring system:

Primary Mission: Read solar inverter data → POST to SolarLog API (Cloud)
Secondary Mission: Display current production on local E-Paper display

Architecture Type: API-First Design (not web server)

┌─────────────────────────────────────────────────────────────┐
│                    INVERTER-ESP System                      │
│                                                             │
│  Solar Inverter (LAN) ────┐                                │
│                            │                                │
│                            ▼                                │
│                  ┌─────────────────┐                        │
│                  │   ESP32-S3      │                        │
│                  │                 │                        │
│                  │  • WiFi Client  │                        │
│                  │  • LVGL UI      │                        │
│                  │  • NVS Storage  │                        │
│                  │  • Deep Sleep   │                        │
│                  └─────────────────┘                        │
│                   │             │                           │
│                   │             │                           │
│          E-Paper Display    SolarLog API                    │
│          (Local View)       (Cloud Storage)                 │
│          296×128 px         https://...karma.organic        │
└─────────────────────────────────────────────────────────────┘

📦 Component Architecture

Component Diagram

┌──────────────────────────────────────────────────────────────┐
│                         ESP32-S3                             │
│                                                              │
│  ┌───────────────┐  ┌───────────────┐  ┌──────────────┐    │
│  │   Network     │  │   Display     │  │   Storage    │    │
│  │   Layer       │  │   Layer       │  │   Layer      │    │
│  ├───────────────┤  ├───────────────┤  ├──────────────┤    │
│  │ • WiFi Mgr    │  │ • LVGL Core   │  │ • NVS Config │    │
│  │ • API Client  │  │ • E-Paper Drv │  │ • Data Cache │    │
│  │ • Inverter    │  │ • UI Screens  │  │ • Preferences│    │
│  │   Client      │  │ • Button Input│  │              │    │
│  └───────────────┘  └───────────────┘  └──────────────┘    │
│           │                  │                  │           │
│           └──────────────────┴──────────────────┘           │
│                              │                              │
│                    ┌─────────▼─────────┐                    │
│                    │   Main Control    │                    │
│                    │   Loop & Power    │                    │
│                    │   Management      │                    │
│                    └───────────────────┘                    │
└──────────────────────────────────────────────────────────────┘

Module Breakdown

1. Network Layer (`firmware/src/network/`)

Files: - wifi_manager.h/.cpp - WiFi connection & reconnection logic - solarlog_api.h/.cpp - SolarLog API HTTP client (HTTPS POST) - inverter_client.h/.cpp - Solar inverter data reader (protocol TBD)

Responsibilities: - Establish WiFi connection - Handle WiFi disconnections & auto-reconnect - POST data to SolarLog API (with retry logic) - Read power/energy data from solar inverter - Handle network errors (timeout, auth, server errors)

Key Functions:

bool wifi_connect(const char* ssid, const char* password);
bool wifi_is_connected();
void wifi_disconnect();

bool api_post_data(float power_w, float energy_kwh, const char* status);
bool api_post_with_retry(float power, float energy, int retries);

float inverter_get_power();      // Returns current power in watts
float inverter_get_energy();     // Returns today's energy in kWh
bool inverter_is_online();

2. Display Layer (`firmware/src/display/` & `firmware/src/ui/`)

Files: - epaper_driver.h/.cpp - E-Paper LVGL display driver - screen_dashboard.h/.cpp - Main dashboard UI - screen_history.h/.cpp - 7-day history chart - screen_sysinfo.h/.cpp - System info & diagnostics - screen_settings.h/.cpp - WiFi & API configuration - button_input.h/.cpp - Physical button handler

Responsibilities: - Initialize E-Paper display (296×128, monochrome) - Render LVGL UI on E-Paper - Handle button input (3 buttons: Next, Prev, Action) - Update display with latest data (every 30-60s) - Optimize E-Paper refresh (partial updates)

Key Functions:

void epaper_init();
void epaper_refresh_full();      // Full screen refresh (2-15s)
void epaper_refresh_partial();   // Partial update (<1s)

void screen_dashboard_create();
void screen_dashboard_update(float power, float energy);

void button_init();
button_event_t button_read();    // Returns BUTTON_NEXT, BUTTON_PREV, BUTTON_ACTION

3. Storage Layer (`firmware/src/storage/`)

Files: - nvs_config.h/.cpp - NVS (Non-Volatile Storage) wrapper - data_cache.h/.cpp - Cache failed API uploads

Responsibilities: - Store WiFi credentials - Store API key - Store configuration (update interval, display settings) - Cache data points when API upload fails - Provide config getter/setter functions

Key Functions:

bool config_load();
bool config_save();

String config_get_wifi_ssid();
void config_set_wifi_ssid(const char* ssid);

String config_get_api_key();
void config_set_api_key(const char* key);

void cache_add_data_point(float power, float energy);
int cache_get_count();
void cache_flush_all();  // Upload cached data when online

4. Main Control (`firmware/src/main.cpp`)

Responsibilities: - Initialize all subsystems - Run main update loop - Handle deep sleep power management - Coordinate data flow

Pseudocode:

href="#__codelineno-5-1">void setup() { Serial.begin(115200); // 1. Initialize subsystems lv_init(); epaper_init(); button_init(); config_load(); // 2. Connect WiFi String ssid = config_get_wifi_ssid(); String pass = config_get_wifi_password(); wifi_connect(ssid.c_str(), pass.c_str()); // 3. Create UI screen_dashboard_create(); // 4. Sync NTP time configTime(0, 0, "pool.ntp.org"); } >void loop() { // LVGL task handler lv_timer_handler(); // Check if update needed (every 5 min) static unsigned long last_update = 0; if (millis() - last_update > UPDATE_INTERVAL) { update_data_and_display(); last_update = millis(); } // Handle button input button_event_t event = button_read(); if (event == BUTTON_NEXT) { screen_next(); } delay(10); } >void update_data_and_display() { // 1. Read inverter data float power = inverter_get_power(); float energy = inverter_get_energy(); // 2. POST to API if (api_post_with_retry(power, energy, 3)) { Serial.println("✅ Data uploaded"); cache_flush_all(); // Upload cached data } else { Serial.println("❌ Upload failed, caching"); cache_add_data_point(power, energy); } // 3. Update display screen_dashboard_update(power, energy); epaper_refresh_partial(); // Fast update }

🔄 Data Flow

Primary Data Flow (API Upload)

┌─────────────────────────────────────────────────────────┐
│  1. Solar Inverter                                      │
│     (HTTP/Modbus/MQTT)                                  │
│     • Current Power: 3500W                              │
│     • Today's Energy: 12.5kWh                           │
│     • Status: Online                                    │
└──────────────┬──────────────────────────────────────────┘
               │
               │ READ (inverter_client.cpp)
               ▼
┌─────────────────────────────────────────────────────────┐
│  2. ESP32-S3 Processing                                 │
│     • Parse inverter response                           │
│     • Add timestamp (NTP)                               │
│     • Format JSON payload                               │
└──────────────┬──────────────────────────────────────────┘
               │
               │ HTTPS POST (solarlog_api.cpp)
               ▼
┌─────────────────────────────────────────────────────────┐
│  3. SolarLog API                                        │
│     https://solarlog-api.karma.organic/api/v1/...       │
│     • Receive JSON payload                              │
│     • Store in database                                 │
│     • Return 200 OK                                     │
└─────────────────────────────────────────────────────────┘
               │
               │ (Optional) GET /history for display
               ▼
┌─────────────────────────────────────────────────────────┐
│  4. Data Storage & Processing                           │
│     • Historical graphs                                 │
│     • Analytics dashboard                               │
│     • Alerts & notifications                            │
└─────────────────────────────────────────────────────────┘

Secondary Data Flow (Local Display)

┌─────────────────────────────────────────────────────────┐
│  1. ESP32-S3 (Cached Data)                              │
│     • power_w = 3500                                    │
│     • energy_kwh = 12.5                                 │
│     • wifi_status = Connected                           │
└──────────────┬──────────────────────────────────────────┘
               │
               │ RENDER (screen_dashboard.cpp)
               ▼
┌─────────────────────────────────────────────────────────┐
│  2. LVGL Rendering Engine                               │
│     • Create labels: "3.5 kW", "12.5 kWh"               │
│     • Draw icons: WiFi, Cloud, Battery                  │
│     • Render to framebuffer (296×128×1bit)              │
└──────────────┬──────────────────────────────────────────┘
               │
               │ FLUSH (epaper_driver.cpp)
               ▼
┌─────────────────────────────────────────────────────────┐
│  3. E-Paper Display Driver                              │
│     • Send framebuffer via SPI                          │
│     • Trigger partial/full refresh                      │
│     • Wait for BUSY pin LOW                             │
└──────────────┬──────────────────────────────────────────┘
               │
               │ DISPLAY (E-Paper Hardware)
               ▼
┌─────────────────────────────────────────────────────────┐
│  4. E-Paper Display (296×128)                           │
│     ┌─────────────────────────────────┐                │
│     │ SOLAR PRODUCTION                │                │
│     │                                 │                │
│     │     3.5 kW                      │                │
│     │                                 │                │
│     │ Today: 12.5 kWh                 │                │
│     │ Status: ●●● WiFi OK             │                │
│     └─────────────────────────────────┘                │
└─────────────────────────────────────────────────────────┘

🔘 UI State Machine

┌──────────────┐     Button 1      ┌──────────────┐
│  Dashboard   ├──────(Next)───────▶│   History    │
│  Screen 1    │◀─────(Prev)────────┤  Screen 2    │
└──────┬───────┘     Button 2       └──────┬───────┘
       │                                    │
Button 1 │                              Button 1 │
(Next)  │                              (Next)  │
       ▼                                    ▼
┌──────────────┐                    ┌──────────────┐
│  Settings    │◀────(Next)─────────│  SysInfo     │
│  Screen 4    ├─────(Prev)────────▶│  Screen 3    │
└──────────────┘                    └──────────────┘
       │
Button 3 │
(Action)│
       ▼
┌──────────────┐
│  WiFi Setup  │
│  (Subscreen) │
└──────────────┘

Button Event Handling

typedef enum {
    BUTTON_NONE,
    BUTTON_NEXT,     // GPIO 0
    BUTTON_PREV,     // GPIO 14
    BUTTON_ACTION    // GPIO 21
} button_event_t;

void handle_button_event(button_event_t event) {
    static uint8_t current_screen = 0;

    switch (event) {
        case BUTTON_NEXT:
            current_screen = (current_screen + 1) % 4;
            screen_switch(current_screen);
            break;

        case BUTTON_PREV:
            current_screen = (current_screen + 3) % 4;  // +3 = -1 mod 4
            screen_switch(current_screen);
            break;

        case BUTTON_ACTION:
            screen_action(current_screen);  // Screen-specific action
            break;

        case BUTTON_NONE:
        default:
            break;
    }
}

⚡ Power Management

Deep Sleep Strategy

┌─────────────────────────────────────────────────────────┐
│  Power State Timeline (5-minute update interval)        │
└─────────────────────────────────────────────────────────┘

 0s                 30s                           300s
 ├───────────────────┼──────────────────────────────┤
 │  ACTIVE           │  DEEP SLEEP                  │
 │  ~150mA           │  ~10µA                       │
 │                   │                              │
 │  • WiFi Connect   │  • CPU off                   │
 │  • Read Inverter  │  • WiFi off                  │
 │  • POST API       │  • Display retains image     │
 │  • Update Display │  • RTC alarm timer active    │
 └───────────────────┴──────────────────────────────┘
                      ▲
                      │
                 Wakeup after 270s

Implementation

#define UPDATE_INTERVAL_S (5 * 60)  // 5 minutes
#define ACTIVE_TIME_S 30             // 30 seconds active

void enter_deep_sleep() {
    Serial.printf("💤 Entering deep sleep for %d seconds...\n", UPDATE_INTERVAL_S - ACTIVE_TIME_S);

    // Configure wake timer
    esp_sleep_enable_timer_wakeup((UPDATE_INTERVAL_S - ACTIVE_TIME_S) * 1000000ULL);

    // Power down peripherals
    WiFi.disconnect(true);
    WiFi.mode(WIFI_OFF);

    // Enter deep sleep
    esp_deep_sleep_start();

    // Execution resumes in setup() after wake
}

void loop() {
    static unsigned long loop_start = millis();

    // Update data & display
    if (!data_updated) {
        update_data_and_display();
        data_updated = true;
    }

    // LVGL task handler
    lv_timer_handler();

    // After 30 seconds, enter deep sleep
    if (millis() - loop_start > ACTIVE_TIME_S * 1000) {
        enter_deep_sleep();
    }

    delay(10);
}

🧪 Testing Strategy

Unit Tests (`tests/`)

// test_wifi_manager.cpp
TEST_CASE("WiFi connects successfully") {
    REQUIRE(wifi_connect("TestSSID", "TestPass") == true);
    REQUIRE(wifi_is_connected() == true);
}

// test_api_client.cpp
TEST_CASE("API POST returns success") {
    bool result = api_post_data(3500, 12.5, "online");
    REQUIRE(result == true);
}

// test_inverter_client.cpp
TEST_CASE("Inverter data parsing") {
    float power = inverter_get_power();
    REQUIRE(power > 0);
    REQUIRE(power < 10000);  // Sanity check
}

Integration Tests

// Test full data flow
void test_full_data_flow() {
    // 1. Read inverter
    float power = inverter_get_power();
    float energy = inverter_get_energy();

    // 2. POST to API
    bool api_ok = api_post_data(power, energy, "online");
    assert(api_ok);

    // 3. Update display
    screen_dashboard_update(power, energy);
    epaper_refresh_full();

    Serial.println("✅ Full data flow test PASSED");
}

📊 Performance Requirements

Metric	Target	Notes
WiFi Connect Time	< 5s	First boot, WPA2
API Upload Time	< 3s	HTTPS POST with retry
E-Paper Refresh	2-15s	Full refresh (hardware limit)
Partial Refresh	< 1s	Value updates only
Deep Sleep Current	< 20µA	With RTC timer enabled
Active Current	< 200mA	WiFi TX peak
Memory Usage (RAM)	< 100KB	LVGL + network buffers
Flash Usage	< 1.5MB	With OTA partition

🔒 Security Considerations

HTTPS Only: All API communication via TLS 1.2+
API Key Storage: Store in NVS (encrypted)
WiFi Credentials: Store in NVS (encrypted)
OTA Updates: Signed firmware only (future)
No Hardcoded Secrets: All credentials via config

Last Updated: 2025-10-23
Version: 0.1.0-alpha
Status: 📐 Design Phase

ARCHITECTURE.md - INVERTER-ESP System Architecture

🎯 System Overview

📦 Component Architecture

Component Diagram

Module Breakdown

1. Network Layer (firmware/src/network/)

2. Display Layer (firmware/src/display/ & firmware/src/ui/)

3. Storage Layer (firmware/src/storage/)

4. Main Control (firmware/src/main.cpp)

🔄 Data Flow

Primary Data Flow (API Upload)

Secondary Data Flow (Local Display)

🔘 UI State Machine

Screen Navigation

Button Event Handling

⚡ Power Management

Deep Sleep Strategy

Implementation

🧪 Testing Strategy

Unit Tests (tests/)

Integration Tests

📊 Performance Requirements

🔒 Security Considerations

1. Network Layer (`firmware/src/network/`)

2. Display Layer (`firmware/src/display/` & `firmware/src/ui/`)

3. Storage Layer (`firmware/src/storage/`)

4. Main Control (`firmware/src/main.cpp`)

Unit Tests (`tests/`)