Zum Inhalt

DEPLOYMENT.md - ESP32 Flash & Deployment Guide

Complete guide for flashing and deploying INVERTER-ESP firmware.

πŸ› οΈ Prerequisites

Hardware

  • βœ… CrowPanel ESP32 E-paper 2.9" HMI Display
  • βœ… USB-C cable (data-capable, not charge-only)
  • βœ… Computer with USB port (macOS, Linux, Windows)

Software

  • βœ… PlatformIO Core (CLI) or PlatformIO IDE (VS Code extension)
  • βœ… USB-to-UART drivers (CH340 or CP2102, usually auto-installed)
  • βœ… Python 3.7+ (for esptool)

πŸ“¦ Installation

Option 1: PlatformIO Core (CLI)

# Install PlatformIO Core
pip install platformio

# Verify installation
pio --version

Option 2: PlatformIO IDE (VS Code)

  1. Install Visual Studio Code: https://code.visualstudio.com/
  2. Open VS Code β†’ Extensions β†’ Search "PlatformIO IDE"
  3. Install PlatformIO IDE extension
  4. Restart VS Code

πŸš€ Build & Flash Firmware

Step 1: Clone/Navigate to Project

cd /path/to/ESP32_GUI_PROJECT/INVERTER-ESP/firmware

Step 2: Check platformio.ini

Verify platformio.ini configuration:

[env:crowpanel-esp32]
platform = espressif32
board = esp32-s3-devkitc-1
framework = arduino

monitor_speed = 115200
upload_speed = 921600

lib_deps = 
    lvgl/lvgl@^9.0.0
    zinggjm/GxEPD2@^1.5.0
    bblanchon/ArduinoJson@^6.21.0

build_flags = 
    -D LV_CONF_INCLUDE_SIMPLE
    -D BOARD_HAS_PSRAM
    -D ARDUINO_USB_CDC_ON_BOOT=1

Step 3: Connect Hardware

  1. Connect ESP32 to computer via USB-C
  2. ESP32 should appear as serial device:
  3. macOS: /dev/cu.usbserial-* or /dev/cu.SLAB_USBtoUART
  4. Linux: /dev/ttyUSB0 or /dev/ttyACM0
  5. Windows: COM3, COM4, etc.

Step 4: Build Firmware

# Build only (no upload)
pio run

# Or use PlatformIO IDE: Click "Build" button (checkmark icon)

Expected Output: 

Processing crowpanel-esp32 (platform: espressif32; board: esp32-s3-devkitc-1; framework: arduino)
...
RAM:   [==        ]  18.2% (used 59532 bytes from 327680 bytes)
Flash: [====      ]  42.3% (used 1109269 bytes from 2621440 bytes)
βœ… Building .pio/build/crowpanel-esp32/firmware.bin
========================= [SUCCESS] Took 45.67 seconds =========================

Step 5: Flash to ESP32

# Upload firmware to ESP32
pio run --target upload

# Or use PlatformIO IDE: Click "Upload" button (arrow icon)

Expected Output: 

Configuring upload protocol...
AVAILABLE: cmsis-dap, esp-bridge, esp-builtin, esp-prog, espota, esptool, iot-bus-jtag, jlink, minimodule, olimex-arm-usb-ocd, olimex-arm-usb-ocd-h, olimex-arm-usb-tiny-h, olimex-jtag-tiny, tumpa
CURRENT: upload_protocol = esptool
Looking for upload port...
Auto-detected: /dev/cu.usbserial-0001
Uploading .pio/build/crowpanel-esp32/firmware.bin
esptool.py v4.5.1
...
Writing at 0x00010000... (100%)
Wrote 1109280 bytes (685432 compressed) at 0x00010000 in 12.3 seconds
Hash of data verified.

Leaving...
Hard resetting via RTS pin...
========================= [SUCCESS] Took 18.45 seconds =========================

Step 6: Monitor Serial Output

# Open serial monitor
pio device monitor

# Or use PlatformIO IDE: Click "Serial Monitor" button (plug icon)

Expected Output: 

ESP-ROM:esp32s3-20210327
Build:Mar 27 2021
...
πŸ“‚ INVERTER-ESP Starting...
πŸ“‘ WiFi: Connecting to HomeNetwork...
βœ… WiFi: Connected! IP: 192.168.1.100
πŸ“Š Display: E-Paper initialized (296x128)
πŸ”˜ Buttons: Initialized (3 buttons)
πŸ“€ API: Testing connection...
βœ… API: Connected to SolarLog API
πŸ”„ Starting main loop...

πŸ”§ First-Time Configuration

WiFi Provisioning

Option 1: Hard-coded (Development)

Edit firmware/src/config.h:

#define WIFI_SSID "YourNetworkName"
#define WIFI_PASSWORD "YourPassword"

Option 2: SmartConfig (Production)

  1. ESP32 starts in AP mode if no WiFi config
  2. Connect phone to ESP32 AP: INVERTER-ESP-SETUP
  3. Open browser β†’ http://192.168.4.1
  4. Enter WiFi SSID & password
  5. ESP32 saves to NVS and reboots

Option 3: Serial Configuration

# Send commands via serial monitor
wifi:set:ssid:YourNetwork
wifi:set:pass:YourPassword
wifi:save
wifi:connect

API Key Configuration

Edit firmware/src/config.h:

#define SOLARLOG_API_KEY "your-api-key-here"

Or use serial commands:

api:set:key:your-api-key-here
api:save

πŸ§ͺ Testing & Verification

1. Display Test

Press Button 3 (Action) to force E-Paper refresh.

Expected: Display shows dashboard with: - Current power (W) - Today's energy (kWh) - WiFi status icon - Timestamp

2. Network Test

Check serial monitor for:

βœ… WiFi: Connected! IP: 192.168.1.100
βœ… API: POST success (3500W, 12.5kWh)

3. Button Test

  • Button 1 (Next): Cycle to next screen
  • Button 2 (Previous): Cycle to previous screen
  • Button 3 (Action): Refresh current screen

4. Deep Sleep Test

Wait for next update cycle (5 min default).

Expected Serial Output: 

πŸ’€ Entering deep sleep for 300 seconds...
(ESP32 goes to sleep, current drops to ~10Β΅A)

--- 5 minutes later ---

ESP-ROM:esp32s3-20210327
πŸ“‚ INVERTER-ESP Waking from deep sleep...
πŸ“€ API: Sending cached data...
βœ… API: POST success
πŸ’€ Entering deep sleep for 300 seconds...

πŸ› Troubleshooting

Issue: Port not detected

Symptoms: 

Error: Please specify `upload_port` for environment or use global `--upload-port` option.

Solutions: 1. Check USB cable is data-capable (not charge-only) 2. Install USB-UART drivers: - macOS: brew install --cask silicon-labs-vcp-driver - Linux: Usually pre-installed (CH341 driver) - Windows: Download from Silicon Labs or WCH website 3. Check device manager / ls /dev/tty* 4. Try different USB port 5. Press Boot button (GPIO0) while connecting

Issue: Upload fails "Failed to connect"

Symptoms: 

A fatal error occurred: Failed to connect to ESP32-S3: No serial data received.

Solutions: 1. Enter bootloader mode manually: - Hold Boot button (GPIO0) - Press Reset button briefly - Release Boot button - Retry upload 2. Check USB cable connection 3. Reduce upload speed in platformio.ini: 

upload_speed = 460800  ; Slower speed

Issue: Display not updating

Symptoms: E-Paper shows blank screen or old content

Solutions: 1. Check SPI pin connections (see HARDWARE.md) 2. Enable debug logs: 

#define LV_LOG_LEVEL LV_LOG_LEVEL_TRACE
3. Test E-Paper driver: 
display.init();
display.fillScreen(GxEPD_BLACK);
display.display();
4. Verify E-Paper BUSY pin (GPIO7) is not stuck HIGH

Issue: WiFi connection fails

Symptoms: 

❌ WiFi: Connection timeout

Solutions: 1. Verify SSID & password are correct 2. Check router supports 2.4GHz (ESP32 doesn't support 5GHz) 3. Move ESP32 closer to router (check RSSI) 4. Disable WiFi power saving: 

WiFi.setSleep(false);
5. Increase connection timeout: 
WiFi.begin(ssid, password);
WiFi.setAutoReconnect(true);
WiFi.persistent(true);

Issue: API upload fails (401 Unauthorized)

Symptoms: 

❌ API POST failed: 401 - Unauthorized

Solutions: 1. Verify API key is correct 2. Check API endpoint URL 3. Test with curl: 

curl -X POST https://solarlog-api.karma.organic/api/v1/inverters/inv-001/data \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"power_w":3500}'

Issue: Deep sleep not working

Symptoms: ESP32 stays awake, battery drains fast

Solutions: 1. Verify deep sleep call: 

esp_deep_sleep_start();  // Not just esp_light_sleep_start()
2. Check USB connection (USB keeps ESP32 powered) 3. Check all peripherals are powered down before sleep 4. Verify wake stub is configured: 
esp_sleep_enable_timer_wakeup(5 * 60 * 1000000ULL);

πŸ”„ OTA Updates (Over-The-Air)

Enable OTA in platformio.ini

upload_protocol = espota
upload_port = 192.168.1.100  ; ESP32 IP address
upload_flags = --auth=admin

Flash via OTA

pio run --target upload

Advantages: - No physical access needed - Update devices in the field - Faster than serial upload

Requirements: - ESP32 connected to same WiFi network - OTA handler implemented in firmware

πŸ“Š Firmware Size Optimization

Current Build Stats

RAM:   [==        ]  18.2% (59KB / 320KB)
Flash: [====      ]  42.3% (1.1MB / 2.6MB)

Optimization Tips

  1. Disable unused LVGL widgets: 

    #define LV_USE_CHART 0
#define LV_USE_CALENDAR 0

  2. Use monochrome only (1-bit color): 

    #define LV_COLOR_DEPTH 1

  3. Reduce LVGL buffer size: 

    #define LV_MEM_SIZE (32U * 1024U)  ; 32KB

  4. Enable compiler optimizations: 

    build_flags = -Os  ; Optimize for size

πŸ“ Backup & Restore

Backup Current Firmware

# Read flash from ESP32
esptool.py --port /dev/cu.usbserial-0001 read_flash 0x0 0x400000 backup.bin

Restore Firmware

# Write flash to ESP32
esptool.py --port /dev/cu.usbserial-0001 write_flash 0x0 backup.bin

πŸ“ž Support

  • PlatformIO Docs: https://docs.platformio.org/
  • ESP32-S3 Docs: https://docs.espressif.com/projects/esp-idf/en/latest/esp32s3/
  • Elecrow Wiki: https://www.elecrow.com/wiki/CrowPanel_ESP32_E-paper_2.9-inch_HMI_Display.html

Last Updated: 2025-10-23
Firmware Version: 0.1.0-alpha
PlatformIO Version: 6.1+