Backup-Mirrors/esp32-energy-meter
1
0
Fork 0
mirror of https://github.com/Legolas-2025/esp32-energy-meter.git synced 2026-08-18 12:44:58 +02:00
Code Issues Packages Projects Releases Wiki Activity

Add files via upload

Browse Source
This commit is contained in:
Amir
2025-12-19 22:59:04 +01:00
committed by GitHub
parent 0edf0f6f23
commit d9c971ea61
3 changed files with 1184 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/configuration-guide.md
+476
View File
@@ -0,0 +1,476 @@
# Configuration Guide
This guide walks you through configuring ESPHome for your ESP32 Energy Meter, from initial setup to advanced customization.
## 🚀 Quick Start
### Prerequisites
- ESP32 development board with energy meter hardware connected
- Computer with ESPHome installed
- WiFi network credentials
- Home Assistant instance (optional but recommended)
### Installation Steps
1. [Install ESPHome](#installing-esphome)
2. [Configure Secrets](#configuring-secrets)
3. [Upload Configuration](#uploading-configuration)
4. [Integrate with Home Assistant](#home-assistant-integration)
## 🔧 Installing ESPHome
### Method 1: pip (Recommended)
```bash
pip install esphome
```
### Method 2: Docker
```bash
docker run -it --rm \
-v "$PWD":/config \
esphome/esphome run esp32-energy-meter.yaml
```
### Method 3: Home Assistant Add-on
1. Open Home Assistant
2. Go to Supervisor → Add-ons
3. Search for "ESPHome"
4. Click "Install"
## 🔐 Configuring Secrets
Create a `secrets.yaml` file in your project directory:
```yaml
# WiFi Configuration
wifi_ssid: "YOUR_WIFI_NETWORK_NAME"
wifi_password: "YOUR_WIFI_PASSWORD"
# API Encryption Key (optional - will be auto-generated)
api_key: "GENERATED_API_KEY"
# OTA Password
ota_password: "YOUR_OTA_PASSWORD"
# MQTT Configuration (if using MQTT)
mqtt_broker_ip: "192.168.1.100"
mqtt_broker_port: 1883
mqtt_username: "your_mqtt_username"
mqtt_password: "your_mqtt_password"
```
### Security Best Practices
- Use strong passwords (at least 12 characters)
- Enable API encryption
- Use WPA2/WPA3 WiFi encryption
- Change default passwords immediately
## ⚙️ Basic Configuration
### File Structure
```
project/
├── esp32-energy-meter.yaml
├── secrets.yaml
└── .esphome/
```
### Core Configuration Sections
#### 1. Basic Device Settings
```yaml
esphome:
name: esp32-energy-meter
friendly_name: ESP32 Energy Meter
esp32:
board: esp32dev
framework:
type: esp-idf
```
#### 2. Network Configuration
```yaml
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
manual_ip:
static_ip: 192.168.1.100 # Choose available IP
gateway: 192.168.1.1 # Your router IP
subnet: 255.255.255.0
ap:
ssid: "ESP32-Energy-Meter Fallback Hotspot"
password: "CHANGE_THIS_PASSWORD"
```
#### 3. API and OTA
```yaml
api:
encryption:
key: !secret api_key
ota:
- platform: esphome
password: !secret ota_password
```
## 📡 Hardware Configuration
### Modbus RTU Setup
```yaml
uart:
id: mod_bus
tx_pin: 17
rx_pin: 16
baud_rate: 4800
stop_bits: 1
modbus:
id: modbus1
modbus_controller:
- id: jsymk
address: 0x1 # JSY meter address
modbus_id: modbus1
update_interval: 3s # Measurement update interval
command_throttle: 50ms # Min time between commands
```
### I2C Display Setup
```yaml
i2c:
sda: 21
scl: 22
font:
- file:
type: gfonts
family: Baloo+Bhaijaan+2
weight: 500
id: baloo_18_500
size: 18
```
## 📱 Display Configuration
### OLED Display Lambda
```yaml
display:
- platform: ssd1306_i2c
model: "SSD1306 128x64"
address: 0x3C
id: oled
rotation: 180°
update_interval: 3s
lambda: !lambda |-
// Burn-in protection
time_t now = id(homeassistant_time).now().timestamp;
if (now % 1800 == 0) {
it.clear();
return;
}
// Clear and draw content
it.clear();
it.print(-1, -4, id(baloo_18_500), "Energy Meter");
// WiFi status
if(id(connection_status).state == 1) {
it.print(it.get_width(), 0, id(icons_18), TextAlign::TOP_RIGHT, "\ue63e");
} else {
it.print(it.get_width(), 0, id(icons_18), TextAlign::TOP_RIGHT, "\ue648");
}
// Power display
it.printf(it.get_width()/2, 38, id(baloo_32_700), TextAlign::CENTER, "%.1f W", id(power2).state);
it.printf(0, it.get_height() + 12, id(baloo_18_700), TextAlign::BOTTOM_LEFT, "%.1f V", id(voltage2).state);
it.printf(it.get_width(), it.get_height() + 12, id(baloo_18_700), TextAlign::BOTTOM_RIGHT, "%.1f A", id(current2).state);
```
## 📊 Sensor Configuration
### WiFi Signal Strength Monitoring
```yaml
binary_sensor:
- platform: template
name: "WiFi Connection Status"
id: connection_status
lambda: !lambda
return id(wifi_signal_strength).state > -70;
sensor:
- platform: wifi_signal
name: "WiFi Signal Strength"
id: wifi_signal_strength
update_interval: 10s
unit_of_measurement: "dBm"
```
### Energy Meter Sensors
```yaml
sensor:
# Power measurement (Channel 2 - primary)
- platform: modbus_controller
modbus_controller_id: jsymk
id: power2
name: "Power 2"
icon: mdi:lightning-bolt
device_class: energy
address: 0x0052
unit_of_measurement: "W"
register_type: holding
value_type: U_DWORD
accuracy_decimals: 1
filters:
- multiply: 0.0001
register_count: 1
response_size: 4
# Voltage measurement
- platform: modbus_controller
modbus_controller_id: jsymk
id: voltage2
name: "Voltage 2"
icon: mdi:alpha-v-box
device_class: energy
address: 0x0050
unit_of_measurement: "V"
register_type: holding
value_type: U_DWORD
accuracy_decimals: 1
filters:
- multiply: 0.0001
register_count: 1
response_size: 4
# Current measurement
- platform: modbus_controller
modbus_controller_id: jsymk
id: current2
name: "Current 2"
icon: mdi:current-ac
device_class: energy
address: 0x0051
unit_of_measurement: "A"
register_type: holding
value_type: U_DWORD
accuracy_decimals: 4 # Increased for low current readings
filters:
- multiply: 0.0001
register_count: 1
response_size: 4
```
## 🚀 Uploading Configuration
### First Upload
```bash
# Connect ESP32 via USB and upload
esphome run esp32-energy-meter.yaml
```
### Subsequent Updates
```bash
# Compile and upload (no USB connection required)
esphome run esp32-energy-meter.yaml --upload-port 192.168.1.100
```
### Advanced Options
```bash
# Enable verbose logging
esphome run esp32-energy-meter.yaml --log-level=debug
# Clean build
esphome run esp32-energy-meter.yaml --clean
# Upload via OTA (if IP is known)
esphome run esp32-energy-meter.yaml --upload-port 192.168.1.100
```
## 🏠 Home Assistant Integration
### Auto-Discovery
Once uploaded, the ESP32 will automatically appear in Home Assistant under "Devices & Services".
### Manual Integration
1. Go to Configuration → Devices & Services
2. Click "Add Integration"
3. Search for "ESPHome"
4. Enter the IP address: `192.168.1.100`
5. Enter API key when prompted
### Entity Naming
ESPHome will create entities like:
- `sensor.esp32_energy_meter_power_2`
- `sensor.esp32_energy_meter_voltage_2`
- `sensor.esp32_energy_meter_current_2`
- `binary_sensor.esp32_energy_meter_wifi_connection_status`
## 🔧 Advanced Configuration
### Custom Update Intervals
```yaml
modbus_controller:
- id: jsymk
address: 0x1
modbus_id: modbus1
update_interval: 2s # Faster updates
command_throttle: 25ms # Reduced throttle
```
### Display Customization
```yaml
display:
- platform: ssd1306_i2c
model: "SSD1306 128x64"
address: 0x3C
id: oled
rotation: 0° # Normal orientation
update_interval: 1s # Faster display updates
lambda: !lambda |-
// Custom display logic here
it.clear();
it.printf(0, 0, id(baloo_18_500), "Custom Label");
```
### Sensor Filtering
```yaml
sensor:
- platform: modbus_controller
# ... other config ...
filters:
- multiply: 0.0001 # Scale factor
- offset: -5.0 # Calibration offset
- exponential_moving_average:
alpha: 0.2 # Smooth readings
- heartbeat: 10s # Periodic updates
```
## 📊 Performance Optimization
### Memory Management
```yaml
esp32:
board: esp32dev
framework:
type: esp-idf
psram:
mode: octal # Enable PSRAM if available
```
### WiFi Optimization
```yaml
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
fast_connect: true # Skip scanning
output_power: 10.5 # Adjust power level
```
### Update Optimization
```yaml
modbus_controller:
- id: jsymk
address: 0x1
modbus_id: modbus1
update_interval: 5s # Balance responsiveness vs. stability
command_throttle: 100ms # Prevent bus overload
```
## 🐛 Troubleshooting
### Common Issues
#### Compilation Errors
- **Check YAML syntax**: Use online YAML validators
- **Verify sensor IDs**: Ensure all referenced IDs exist
- **Update ESPHome**: `pip install --upgrade esphome`
#### Connection Issues
- **Check IP conflicts**: Use static IP to avoid DHCP issues
- **Verify WiFi credentials**: Ensure correct SSID and password
- **Check firewall**: Ensure device can connect to local network
#### Sensor Reading Issues
- **Check Modbus address**: Default is usually 0x1
- **Verify wiring**: Check RS485 A+ and B- connections
- **Check update intervals**: Don't set too aggressive
### Debug Commands
```bash
# Check device status
esphome config esp32-energy-meter.yaml
# Test connection
esphome logs esp32-energy-meter.yaml --device 192.168.1.100
# Check logs
esphome logs esp32-energy-meter.yaml --serial /dev/ttyUSB0
```
## 📝 Configuration Templates
### Minimal Configuration
```yaml
esphome:
name: minimal-energy-meter
friendly_name: Minimal Energy Meter
esp32:
board: esp32dev
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
api:
encryption:
key: !secret api_key
ota:
- platform: esphome
password: !secret ota_password
uart:
id: mod_bus
tx_pin: 17
rx_pin: 16
baud_rate: 4800
modbus:
id: modbus1
modbus_controller:
- id: jsymk
address: 0x1
modbus_id: modbus1
sensor:
- platform: modbus_controller
modbus_controller_id: jsymk
id: power
name: "Power"
address: 0x0052
unit_of_measurement: "W"
register_type: holding
value_type: U_DWORD
filters:
- multiply: 0.0001
```
### Production Configuration
```yaml
# Full featured configuration with all sensors, display, and monitoring
# (see esp32-energy-meter.yaml for complete example)
```
## 🔗 Next Steps
After basic configuration:
1. [Hardware Setup](hardware-setup.md) - If not already completed
2. [Home Assistant Integration](wiki/Home-Assistant-Integration.md)
3. [Advanced Features](wiki/Advanced-Features.md)
4. [Troubleshooting](troubleshooting.md)
For specific hardware issues, refer to the [Hardware Setup Guide](hardware-setup.md).
docs/hardware-setup.md
+220
View File
@@ -0,0 +1,220 @@
# Hardware Setup Guide
## ⚠️ Safety Warning
⚠️ **HIGH VOLTAGE**: This project involves working with mains electricity. Always disconnect power before making connections and use appropriate safety measures. The authors are not responsible for any damage or injury resulting from the use of this project.
## 📋 Required Components
### Core Hardware
| Component | Specification | Quantity | Notes |
|-----------|---------------|----------|-------|
| ESP32 Board | Any ESP32 variant | 1 | DevKit, WROOM, etc. |
| Energy Meter | JSY with Modbus RTU | 1 | Main measurement device |
| OLED Display | SSD1306 128x64 I2C | 1 | For local display |
| RS485 Module | TTL to RS485 converter | 1 | For Modbus communication |
| Power Supply | 3.3V/5V | 1 | USB power recommended |
### Optional Components
| Component | Purpose | Notes |
|-----------|---------|-------|
| 3D Printed Enclosure | Protection | Recommended for permanent installation |
| Current Clamps | Non-invasive measurement | For measuring current without direct connection |
| Voltage Transformers | Voltage isolation | If voltage measurement is required |
## 🔌 Pin Connections
### ESP32 Pinout
```
ESP32 DevKit V1 Pin Layout:
┌─────────┐
3V3 │1 38│ GND
EN │2 37│ GPIO0
SENSOR │3 36│ GPIO2
VP/GPIO36 │4 35│ GPIO4
VN/GPIO39 │5 34│ GPIO16 ← RX for Modbus
GPIO34 │6 33│ GPIO17 ← TX for Modbus
GPIO35 │7 32│ GPIO5
GPIO32 │8 31│ GPIO18 ← I2C SCL
GPIO33 │9 30│ GPIO19 ← I2C SDA
5V │10 29│ GPIO21
GND │11 28│ GND
GND │12 27│ GPIO3 (RX0)
GPIO25│13 26│ GPIO1 (TX0)
GPIO26│14 25│ GPIO22 ← SCL (Alt)
GPIO27│15 24│ GPIO23 ← SDA (Alt)
└─────────┘
```
### Connection Table
| Component | ESP32 Pin | Signal | Notes |
|-----------|-----------|--------|-------|
| **Modbus RTU** | | | |
| RS485 Module | GPIO17 | TX | UART TX |
| RS485 Module | GPIO16 | RX | UART RX |
| RS485 Module | 3.3V | VCC | Power |
| RS485 Module | GND | GND | Ground |
| **I2C OLED Display** | | | |
| OLED SDA | GPIO21 | SDA | I2C Data |
| OLED SCL | GPIO22 | SCL | I2C Clock |
| OLED VCC | 3.3V | VCC | Power |
| OLED GND | GND | GND | Ground |
## 🔌 Detailed Wiring Guide
### Step 1: RS485 Modbus Setup
#### RS485 Module Connections
```
RS485 Module Pinout:
┌─────────┐
│ VCC │ ← 3.3V (ESP32)
│ GND │ ← GND (ESP32)
│ RE/DE │ ← Not connected (automatic)
│ RE │ ← Not connected
│ DE │ ← Not connected
│ DI │ ← GPIO17 (ESP32 TX)
│ RO/RX │ ← GPIO16 (ESP32 RX)
└─────────┘
│ A+ │ ← JSY Meter A+ (or Data+)
│ B- │ ← JSY Meter B- (or Data-)
│ GND │ ← Optional: Earth ground
└─────────┘
```
#### JSY Energy Meter Connections
```
JSY Energy Meter:
┌─────────┐
│ Power │ ← AC Power (L/N)
│ Current │ ← CT Clamp connections
│ A+ │ ← RS485 Data+
│ B- │ ← RS485 Data-
│ GND │ ← Optional ground
└─────────┘
```
### Step 2: I2C OLED Display Setup
#### OLED Display Connections
```
SSD1306 128x64 OLED:
┌─────────┐
│ VCC │ ← 3.3V (ESP32)
│ GND │ ← GND (ESP32)
│ SDA │ ← GPIO21 (ESP32 SDA)
│ SCL │ ← GPIO22 (ESP32 SCL)
└─────────┘
```
#### I2C Address Configuration
The default I2C address for SSD1306 is `0x3C`. If you have multiple I2C devices, you may need to use `0x3D` by connecting the address pin to VCC.
## 🔧 Hardware Assembly Steps
### Step 1: Prepare the ESP32
1. **Verify ESP32**: Check that your ESP32 board is working properly
2. **Install Headers**: Solder pin headers if not pre-installed
3. **Test Power**: Connect to USB and verify power-on LED
### Step 2: Install RS485 Module
1. **Position Module**: Place RS485 module on breadboard or PCB
2. **Connect Power**: Wire 3.3V and GND to ESP32
3. **Connect UART**: Wire TX/RX pins as shown in table above
4. **Connect to Meter**: Wire A+ and B- to JSY energy meter
### Step 3: Install OLED Display
1. **Position Display**: Mount OLED in visible location
2. **Wire I2C**: Connect SDA, SCL, VCC, and GND
3. **Test Communication**: Verify I2C detection (see troubleshooting)
### Step 4: Connect Energy Meter
1. **Power Off**: Ensure all power is disconnected
2. **Wire Modbus**: Connect A+ and B- wires to RS485 module
3. **Wire Power**: Connect AC power wires to meter (if required)
4. **Wire Current**: Connect current transformers (if used)
## 🏗️ Enclosure Recommendations
### 3D Printed Enclosure
- **Material**: ABS or PLA
- **Dimensions**: Minimum 100mm x 60mm x 30mm
- **Features Needed**:
- Ventilation holes for heat dissipation
- Cutouts for OLED display
- Access holes for wiring
- Mounting holes for PCB
### Commercial Enclosure
- **Type**: IP65 rated plastic or metal enclosure
- **Size**: DIN rail mount or wall mount
- **Features**:
- Clear window for OLED display
- Cable entry glands
- Grounding lug
## 📏 Calibration and Testing
### Initial Power-On
1. **Connect Power**: Apply power to ESP32 via USB
2. **Check Serial**: Monitor serial output for boot messages
3. **Verify WiFi**: Check WiFi connection status
4. **Test Display**: Verify OLED shows "Energy Meter" title
### Modbus Communication Test
1. **Check Logs**: Look for "JSY energy meter protocol" messages
2. **Verify Address**: Ensure meter address is 0x1 (default)
3. **Monitor Communication**: Watch for read errors or timeouts
### Sensor Validation
1. **Check Values**: Verify all sensors show reasonable readings
2. **Verify Display**: Confirm power, voltage, current display correctly
3. **Test WiFi Icon**: Verify WiFi status indicator functionality
## 🔍 Troubleshooting Hardware Issues
### Common Problems
#### No Power to ESP32
- **Check USB cable**: Ensure data cable (not charge-only)
- **Check voltage**: Verify 3.3V and 5V rails
- **Check connections**: Verify all power connections
#### OLED Not Displaying
- **Check I2C address**: Default should be 0x3C
- **Check wiring**: Verify SDA/SCL connections
- **Check library**: Ensure SSD1306 library is loaded
#### Modbus Communication Failure
- **Check RS485 wiring**: Verify A+ and B- connections
- **Check address**: Ensure meter address matches configuration
- **Check termination**: Add 120Ω termination if long cables
- **Check power**: Verify meter is powered
#### Intermittent Readings
- **Check power supply**: Ensure stable power to all components
- **Check connections**: Verify all wire connections are secure
- **Check EMI**: Move away from high-voltage areas
- **Add filtering**: Use ferrite beads on power lines
### Diagnostic Tools
- **Serial Monitor**: Monitor ESP32 serial output
- **I2C Scanner**: Use I2C scan to find devices
- **Oscilloscope**: Check RS485 signal quality
- **Multimeter**: Verify voltage levels and continuity
## 📋 Final Checklist
Before proceeding to software configuration:
- [ ] ESP32 powers on and boots successfully
- [ ] OLED display shows "Energy Meter" title
- [ ] WiFi connection established
- [ ] Modbus communication working
- [ ] Energy meter readings are stable
- [ ] All connections are secure
- [ ] Enclosure (if used) is properly assembled
- [ ] Safety measures are in place
Once hardware is verified, proceed to the [Configuration Guide](configuration-guide.md) for ESPHome setup.
docs/troubleshooting.md
+488
View File
@@ -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.