diff --git a/docs/configuration-guide.md b/docs/configuration-guide.md
new file mode 100644
index 0000000..f291ad8
--- /dev/null
+++ b/docs/configuration-guide.md
@@ -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).
\ No newline at end of file
diff --git a/docs/hardware-setup.md b/docs/hardware-setup.md
new file mode 100644
index 0000000..d447ad9
--- /dev/null
+++ b/docs/hardware-setup.md
@@ -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.
\ No newline at end of file
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..3d0bd08
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -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.
\ No newline at end of file