Add files via upload

2026-08-18 12:44:58 +02:00 · 2025-12-19 22:59:04 +01:00
parent 0edf0f6f23
commit d9c971ea61
3 changed files with 1184 additions and 0 deletions
@@ -0,0 +1,488 @@
+# Troubleshooting Guide
+
+This comprehensive guide helps you diagnose and resolve common issues with the ESP32 Energy Meter project.
+
+## 🔍 Quick Diagnosis
+
+### System Health Check
+Before diving into specific issues, verify these basics:
+
+- [ ] ESP32 powers on and boots successfully
+- [ ] WiFi connection is established  
+- [ ] OLED display shows "Energy Meter" title
+- [ ] Home Assistant integration is working
+- [ ] Energy meter readings are stable
+
+### First Steps for Any Issue
+1. **Check Serial Logs**: Monitor ESP32 output for error messages
+2. **Verify Connections**: Ensure all hardware connections are secure
+3. **Test Individual Components**: Test ESP32, OLED, and energy meter separately
+4. **Check Power Supply**: Verify stable power to all components
+
+## ⚡ Power and Boot Issues
+
+### ESP32 Not Powering On
+**Symptoms**: No LED indicators, no serial output
+
+**Diagnosis**:
+```bash
+# Check USB cable
+esphome logs esp32-energy-meter.yaml --serial /dev/ttyUSB0
+```
+
+**Solutions**:
+- **USB Cable**: Use data cable (not charge-only cable)
+- **Power Supply**: Ensure 5V power supply provides adequate current (≥1A)
+- **Reset Button**: Press reset button on ESP32
+- **Power Connections**: Verify 3.3V and GND connections
+
+### Boot Loop or Continuous Restart
+**Symptoms**: ESP32 restarts repeatedly, no stable operation
+
+**Diagnosis**:
+```bash
+# Monitor boot sequence
+esphome logs esp32-energy-meter.yaml --serial /dev/ttyUSB0
+```
+
+**Common Causes & Solutions**:
+- **Insufficient Power**: Upgrade to higher current power supply
+- **Loose Connections**: Secure all wire connections
+- **Memory Issues**: Reduce font loading or increase stack size
+- **Watchdog Reset**: Check for infinite loops in code
+
+```yaml
+# Fix memory issues
+esp32:
+  board: esp32dev
+  framework:
+    type: esp-idf
+  psram:
+    mode: octal
+```
+
+## 📶 WiFi Connection Issues
+
+### Cannot Connect to WiFi
+**Symptoms**: No WiFi icon, "Fallback Hotspot" appears
+
+**Diagnosis**:
+```yaml
+# Check WiFi configuration
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  fast_connect: true  # Skip scanning
+```
+
+**Solutions**:
+- **Credentials**: Verify SSID and password in secrets.yaml
+- **Network Issues**: Check router status and other device connectivity
+- **Signal Strength**: Move ESP32 closer to WiFi access point
+- **Security**: Ensure WPA2/WPA3 security (avoid WEP)
+
+### Intermittent WiFi Connection
+**Symptoms**: WiFi drops frequently, connectivity problems
+
+**Diagnosis**:
+```yaml
+# Monitor signal strength
+sensor:
+  - platform: wifi_signal
+    name: "WiFi Signal Strength"
+    update_interval: 10s
+```
+
+**Solutions**:
+- **Signal Strength**: Improve WiFi coverage or move closer to router
+- **Power Management**: Disable WiFi power saving
+- **Channel Interference**: Change WiFi channel on router
+- **Hardware Issues**: Check ESP32 WiFi antenna
+
+```yaml
+# Optimize WiFi settings
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  fast_connect: true
+  output_power: 12.0
+  power_save_mode: NONE
+```
+
+### WiFi Status Shows "Disconnected" Despite Connection
+**Symptoms**: Data flowing to Home Assistant but WiFi icon shows disconnected
+
+**Diagnosis**: This is caused by the generic `platform: status` check
+
+**Solution**: Use enhanced WiFi signal strength monitoring (already implemented):
+```yaml
+binary_sensor:
+  - platform: template
+    name: "WiFi Connection Status"
+    id: connection_status
+    lambda: !lambda
+      return id(wifi_signal_strength).state > -70;
+```
+
+## 📱 OLED Display Issues
+
+### Display Shows Nothing
+**Symptoms**: Blank screen, no text or graphics
+
+**Diagnosis**:
+```yaml
+# Check I2C configuration
+i2c:
+  sda: 21
+  scl: 22
+
+display:
+  - platform: ssd1306_i2c
+    model: "SSD1306 128x64"
+    address: 0x3C
+```
+
+**Solutions**:
+- **I2C Address**: Default is 0x3C, try 0x3D if multiple I2C devices
+- **Wiring**: Verify SDA (GPIO21) and SCL (GPIO22) connections
+- **Power**: Ensure 3.3V and GND connections to OLED
+- **Library**: Update ESPHome to latest version
+
+```bash
+# Test I2C device detection
+esphome logs esp32-energy-meter.yaml --serial /dev/ttyUSB0
+```
+
+### Display Shows Garbled Text or Wrong Characters
+**Symptoms**: Corrupted text, strange symbols
+
+**Diagnosis**: Font loading or encoding issues
+
+**Solutions**:
+- **Font Loading**: Verify Google Fonts connectivity
+- **Character Encoding**: Check font glyphs configuration
+- **Memory Issues**: Reduce font sizes or count
+
+```yaml
+# Simplify font loading
+font:
+  - file:
+      type: gfonts
+      family: Arial
+    id: arial_16
+    size: 16
+```
+
+### Display Refreshes Too Slowly
+**Symptoms**: Laggy display updates, delayed readings
+
+**Solutions**:
+- **Update Interval**: Reduce display update interval
+- **Display Logic**: Optimize lambda function efficiency
+
+```yaml
+display:
+  update_interval: 1s  # Faster updates
+```
+
+### OLED Burn-in Protection Not Working
+**Symptoms**: Static text causing screen damage over time
+
+**Diagnosis**: Time synchronization issues
+
+**Solutions**:
+```yaml
+# Ensure time platform is configured
+time:
+  - platform: homeassistant
+    id: homeassistant_time
+    
+# Verify burn-in protection logic
+lambda: !lambda |-
+  time_t now = id(homeassistant_time).now().timestamp;
+  if (now % 1800 == 0) {  // Every 30 minutes
+    it.clear();
+    return;
+  }
+```
+
+## 📊 Energy Meter Communication Issues
+
+### No Modbus Communication
+**Symptoms**: All sensors show 0, no data from energy meter
+
+**Diagnosis**:
+```yaml
+# Check Modbus configuration
+uart:
+  id: mod_bus
+  tx_pin: 17
+  rx_pin: 16
+  baud_rate: 4800
+  stop_bits: 1
+
+modbus_controller:
+  - id: jsymk
+    address: 0x1  # Default JSY address
+```
+
+**Solutions**:
+- **Wiring**: Verify RS485 A+ and B- connections
+- **Address**: Check energy meter address (usually 0x1)
+- **Termination**: Add 120Ω termination resistor for long cables
+- **Power**: Ensure energy meter is powered on
+
+```bash
+# Monitor Modbus communication
+esphome logs esp32-energy-meter.yaml --serial /dev/ttyUSB0
+```
+
+### Intermittent Sensor Readings
+**Symptoms**: Readings appear and disappear randomly
+
+**Diagnosis**: Communication errors or timing issues
+
+**Solutions**:
+```yaml
+# Optimize communication settings
+modbus_controller:
+  - id: jsymk
+    address: 0x1
+    modbus_id: modbus1
+    update_interval: 5s        # Slower, more reliable
+    command_throttle: 100ms    # More time between commands
+```
+
+### Incorrect Sensor Values
+**Symptoms**: Readings are wrong but consistent
+
+**Diagnosis**: Calibration or scaling issues
+
+**Solutions**:
+```yaml
+# Apply calibration corrections
+sensor:
+  - platform: modbus_controller
+    # ... other config ...
+    filters:
+      - multiply: 0.0001       # Correct scaling
+      - offset: -5.0           # Apply offset
+      - calibrate_linear:
+          - 0.0 -> 0.0
+          - 240.0 -> 242.1     # Correct for systematic error
+```
+
+## 🏠 Home Assistant Integration Issues
+
+### Device Not Auto-Discovered
+**Symptoms**: ESP32 not appearing in Home Assistant
+
+**Solutions**:
+- **Network**: Ensure ESP32 and HA are on same network
+- **API**: Verify API encryption key is correct
+- **Firewall**: Check if network firewall blocks mDNS
+
+### Entities Missing or Not Updating
+**Symptoms**: Some sensors don't appear or show "unknown"
+
+**Diagnosis**:
+```bash
+# Check ESP32 logs for API connection issues
+esphome logs esp32-energy-meter.yaml --device 192.168.1.100
+```
+
+**Solutions**:
+- **API Key**: Ensure correct API key in HA
+- **Update Interval**: Check sensor update intervals
+- **State Class**: Ensure energy sensors have proper state class
+
+```yaml
+# Proper state classes for energy
+sensor:
+  - platform: modbus_controller
+    # ... other config ...
+    state_class: total          # For cumulative energy
+    device_class: energy        # For energy measurements
+```
+
+### Energy Dashboard Not Working
+**Symptoms**: Energy sources not recognized
+
+**Solutions**:
+- **State Classes**: Ensure sensors have `state_class: total`
+- **Device Classes**: Use `device_class: energy`
+- **Statistics**: Enable statistics for energy calculations
+
+## 🔧 Configuration Issues
+
+### Compilation Errors
+**Symptoms**: ESPHome compilation fails
+
+**Common Issues**:
+- **YAML Syntax**: Validate YAML file
+- **Sensor IDs**: Ensure all referenced IDs exist
+- **Dependencies**: Update ESPHome to latest version
+
+```bash
+# Validate configuration
+esphome config esp32-energy-meter.yaml
+
+# Clean build
+esphome run esp32-energy-meter.yaml --clean
+```
+
+### OTA Update Fails
+**Symptoms**: Cannot update firmware over WiFi
+
+**Solutions**:
+- **Network**: Ensure stable WiFi connection
+- **OTA Password**: Verify correct OTA password
+- **IP Address**: Use correct ESP32 IP address
+
+```bash
+# Force OTA update
+esphome run esp32-energy-meter.yaml --upload-port 192.168.1.100
+```
+
+### Memory Issues
+**Symptoms**: ESP32 restarts, unstable operation
+
+**Diagnosis**:
+```yaml
+# Monitor memory usage
+sensor:
+  - platform: template
+    name: "Free Heap"
+    lambda: !lambda
+      return ESP.getFreeHeap();
+```
+
+**Solutions**:
+- **Reduce Fonts**: Limit font loading
+- **Enable PSRAM**: Use external RAM if available
+- **Optimize Code**: Simplify lambda functions
+
+## 📋 Hardware-Specific Issues
+
+### JSY Energy Meter Problems
+**Symptoms**: No communication with JSY meter
+
+**Solutions**:
+- **Address**: Default address is usually 0x1
+- **Wiring**: Check RS485 A+ (Data+) and B- (Data-)
+- **Termination**: Add termination resistor for long cables
+- **Power**: Ensure meter is properly powered
+
+### RS485 Module Issues
+**Symptoms**: No or corrupted Modbus communication
+
+**Solutions**:
+- **Direction Control**: Some modules need RE/DE pin control
+- **Power**: Ensure proper 3.3V power supply
+- **Isolation**: Consider optoisolated RS485 modules
+
+### ESP32 Board Variations
+**Symptoms**: Different behavior on different ESP32 boards
+
+**Solutions**:
+- **Pin Assignment**: Verify pin numbers for your specific board
+- **Flash Mode**: Check if different flash mode needed
+
+## 🔍 Advanced Diagnostics
+
+### Serial Debug Commands
+```bash
+# Monitor all ESP32 output
+esphome logs esp32-energy-meter.yaml --serial /dev/ttyUSB0
+
+# Monitor specific component
+esphome logs esp32-energy-meter.yaml --log-level=DEBUG
+
+# Check configuration without building
+esphome config esp32-energy-meter.yaml
+```
+
+### Network Diagnostics
+```bash
+# Ping ESP32
+ping 192.168.1.100
+
+# Check network connectivity
+nmap -p 8266 192.168.1.100  # ESP32 API port
+```
+
+### Hardware Testing
+```bash
+# I2C scanner (add to configuration temporarily)
+i2c:
+  - id: i2c_component
+    sda: 21
+    scl: 22
+    scan: True  # Scan for I2C devices
+
+# UART testing
+uart:
+  - id: uart_test
+    tx_pin: 17
+    rx_pin: 16
+    baud_rate: 115200  # Higher baud for testing
+```
+
+## 📞 Getting Help
+
+### Before Asking for Help
+1. **Check this guide** for common solutions
+2. **Review serial logs** for error messages
+3. **Test individual components** separately
+4. **Document the issue** with steps to reproduce
+
+### Information to Include
+- **ESP32 board type** and specifications
+- **Energy meter model** and version
+- **ESPHome version** (`esphome version`)
+- **Home Assistant version**
+- **Relevant log excerpts**
+- **Configuration file** (with secrets removed)
+
+### Community Resources
+- [ESPHome Discord](https://discord.gg/esphome)
+- [Home Assistant Community Forum](https://community.home-assistant.io/)
+- [GitHub Issues](https://github.com/esphome/esphome/issues)
+
+### Useful Tools
+- **ESP32 Serial WiFi Terminal** - For wireless serial monitoring
+- **Network Analyzer** - For WiFi diagnostics
+- **Modbus Poll** - For Modbus testing
+- **I2C Scanner** - For I2C device detection
+
+## 🔄 Prevention and Maintenance
+
+### Regular Maintenance
+- **Monitor logs** weekly for warning signs
+- **Check connections** quarterly for corrosion
+- **Update firmware** monthly for security patches
+- **Backup configurations** after major changes
+
+### System Monitoring
+```yaml
+# Add system health monitoring
+sensor:
+  - platform: uptime
+    name: "Uptime"
+    
+  - platform: wifi_signal
+    name: "WiFi Signal"
+    update_interval: 60s
+    
+  - platform: template
+    name: "Free Memory"
+    lambda: !lambda
+      return ESP.getFreeHeap();
+```
+
+### Performance Optimization
+- **Update intervals**: Balance responsiveness vs. stability
+- **Memory usage**: Monitor heap usage regularly
+- **Connection quality**: Keep WiFi signal above -70 dBm
+
+This troubleshooting guide should help you resolve most issues with the ESP32 Energy Meter project. For persistent problems, consider creating a GitHub issue with detailed information about your setup and the specific problem you're experiencing.