Backup-Mirrors/esp32-energy-meter
1
0
Fork 0
mirror of https://github.com/Legolas-2025/esp32-energy-meter.git synced 2026-08-17 12:35:01 +02:00
Code Issues Packages Projects Releases Wiki Activity
Files
1e649fd4995d299b943d745abbe3a60e2f09209c
esp32-energy-meter/docs/configuration-guide.md
T
Amir d9c971ea61 Add files via upload
2025-12-19 22:59:04 +01:00

10 KiB
Raw Blame History

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
  2. Configure Secrets
  3. Upload Configuration
  4. Integrate with Home Assistant

🔧 Installing ESPHome

Method 1: pip (Recommended)

pip install esphome

Method 2: Docker

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:

# 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

esphome:
  name: esp32-energy-meter
  friendly_name: ESP32 Energy Meter

esp32:
  board: esp32dev
  framework:
    type: esp-idf

2. Network Configuration

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

api:
  encryption:
    key: !secret api_key

ota:
  - platform: esphome
    password: !secret ota_password

📡 Hardware Configuration

Modbus RTU Setup

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

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

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

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

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

# Connect ESP32 via USB and upload
esphome run esp32-energy-meter.yaml

Subsequent Updates

# Compile and upload (no USB connection required)
esphome run esp32-energy-meter.yaml --upload-port 192.168.1.100

Advanced Options

# 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

modbus_controller:
  - id: jsymk
    address: 0x1
    modbus_id: modbus1
    update_interval: 2s       # Faster updates
    command_throttle: 25ms    # Reduced throttle

Display Customization

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

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

esp32:
  board: esp32dev
  framework:
    type: esp-idf
  psram:
    mode: octal              # Enable PSRAM if available

WiFi Optimization

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password
  fast_connect: true         # Skip scanning
  output_power: 10.5         # Adjust power level

Update Optimization

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

# 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

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

# 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 - If not already completed
  2. Home Assistant Integration
  3. Advanced Features
  4. Troubleshooting

For specific hardware issues, refer to the Hardware Setup Guide.

Reference in New Issue View Git Blame Copy Permalink