mirror of
https://github.com/Legolas-2025/esp32-energy-meter.git
synced 2026-08-17 12:35:01 +02:00
11 KiB
11 KiB
ESP32 Energy Meter Project - GitHub Repository Summary
🎯 Project Overview
This GitHub repository contains a complete, production-ready implementation of a smart energy monitoring system based on ESP32 and ESPHome firmware. The project enhances the original work by Giovanni Aggiustatutto with several advanced features and optimizations.
📊 Original vs Enhanced Features
Original Project (Giovanni Aggiustatutto)
- Basic Energy Monitoring: Power, voltage, current measurement
- Home Assistant Integration: Basic API connectivity
- Simple Display: Power readings on OLED
- Standard Modbus: Basic JSY energy meter communication
Enhanced Features Added
- ✅ Enhanced WiFi Monitoring: Signal strength-based connection status
- ✅ OLED Burn-in Protection: Automatic screen clearing every 30 minutes
- ✅ Professional Display: Google Fonts integration with proper typography
- ✅ Optimized Performance: Configurable update intervals and command throttling
- ✅ Advanced Sensor Filtering: Noise reduction and calibration capabilities
- ✅ System Health Monitoring: Memory, uptime, and connectivity tracking
- ✅ Professional Documentation: Complete guides and troubleshooting
- ✅ Home Assistant Optimization: Proper state classes and device classes
🏗️ Repository Structure
esp32-energy-meter/
├── 📄 esp32-energy-meter.yaml # Main ESPHome configuration (anonymized)
├── 📄 README.md # Project overview and quick start
├── 📄 LICENSE # Creative Commons BY-NC-SA 4.0 license
├── 📄 PROJECT_SUMMARY.md # This file - project overview
├── 📄 CHANGELOG.md # Original v.1.0.0 project vs. v2.0.0 updates listed
├── 📁 docs/ # Technical documentation
│ ├── 📄 hardware-setup.md # Complete hardware assembly guide
│ ├── 📄 configuration-guide.md # ESPHome configuration tutorial
│ ├── 📄 troubleshooting.md # Comprehensive troubleshooting guide
│ └── 📄 api-reference.md # Complete API and entity reference
└── 📁 wiki/ # Wiki pages for advanced topics
├── 📄 Home-Assistant-Integration.md # HA setup and usage guide
└── 📄 Advanced-Features.md # Customization and advanced features
🔧 Technical Specifications
Hardware Requirements
- ESP32 Development Board (any variant)
- JSY Energy Meter with Modbus RTU over RS485
- SSD1306 128x64 OLED Display (I2C, address 0x3C)
- RS485 to TTL Converter for Modbus communication
Pin Configuration
UART (Modbus):
- TX: GPIO17
- RX: GPIO16
I2C (OLED):
- SDA: GPIO21
- SCL: GPIO22
Power:
- 3.3V: OLED, RS485 module
- 5V: ESP32 via USB
Communication Protocols
- Modbus RTU: 4800 baud, 8N1 (8 data bits, No parity, 1 stop bit)
- I2C: Standard 400kHz for OLED communication
- WiFi: 2.4GHz, WPA2/WPA3 security
- Home Assistant API: Encrypted communication
📊 Monitored Parameters
Primary Measurements
| Parameter | Channel | Unit | Accuracy | Update Interval |
|---|---|---|---|---|
| Power | 1&2 | W | 0.1W | 3s |
| Voltage | 1&2 | V | 0.1V | 3s |
| Current | 1 | A | 0.1A | 3s |
| Current | 2 | A | 0.0001A | 3s |
| Energy | 1&2 | kWh | 0.1kWh | 3s |
| Frequency | Single | Hz | 0.1Hz | 3s |
System Monitoring
| Parameter | Unit | Update Interval | Purpose |
|---|---|---|---|
| WiFi Signal | dBm | 10s | Connection quality |
| WiFi Status | Boolean | 10s | Connectivity indicator |
| System Uptime | seconds | 30s | Reliability tracking |
| Free Memory | bytes | 60s | Performance monitoring |
🎨 Display Features
Current Implementation
- Title: "Energy Meter" (Google Fonts Baloo Bhaijaan 2, 18px)
- WiFi Status: Material Icons WiFi/WiFi-off indicators
- Power Display: Large centered power reading (32px font)
- Voltage/Current: Bottom corner display (18px font)
- Rotation: 180° for optimal viewing angle
OLED Burn-in Protection
- Automatic Clearing: Every 30 minutes (1800 seconds)
- Implementation: Time-based clearing using Home Assistant time sync
- Display Preservation: Prevents permanent screen damage from static content
Enhanced Typography
font:
- Baloo Bhaijaan 2 (500): Body text and titles
- Baloo Bhaijaan 2 (700): Power display and emphasis
- Material Symbols Outlined: WiFi status icons
🔧 WiFi Connectivity Enhancement
Problem Solved
Original Issue: WiFi icon showed "disconnected" despite successful data transmission due to generic platform: status checking multiple connectivity types (WiFi, API, DNS, MQTT).
Solution Implemented
# Enhanced WiFi monitoring
binary_sensor:
- platform: template
name: "WiFi Connection Status"
id: connection_status
lambda: !lambda
return id(wifi_signal_strength).state > -70; // Signal-based check
sensor:
- platform: wifi_signal
name: "WiFi Signal Strength"
id: wifi_signal_strength
update_interval: 10s
Benefits
- Accurate Status: Only shows disconnected when WiFi signal is actually weak
- No False Positives: Eliminates spurious disconnection alerts
- Signal Monitoring: Provides actual signal strength data for analysis
- Configurable Threshold: -70 dBm threshold can be adjusted as needed
🏠 Home Assistant Integration
Auto-Discovery Features
- Device Discovery: Automatic appearance in Home Assistant
- Entity Creation: All sensors automatically recognized
- Energy Dashboard: Ready for energy monitoring configuration
Entity Categories
- Primary Power Sensors: Used for display and primary monitoring
- System Health: WiFi, uptime, memory monitoring
- Energy Analytics: Cumulative energy, power factors
- Historical Data: Peak power, frequency tracking
Energy Dashboard Ready
# Recommended configuration
consumption:
- sensor.esp32_energy_meter_energy_2 # Primary circuit
- sensor.esp32_energy_meter_energy_1 # Secondary circuit
# Proper state classes
state_class: total # For cumulative measurements
device_class: energy # For energy entities
🔒 Security and Privacy
Anonymization Applied
- API Keys: Placeholder values (CHANGE_THIS_TO_YOUR_API_KEY)
- WiFi Credentials: Uses secrets.yaml system (!secret wifi_ssid)
- OTA Password: Placeholder value (CHANGE_THIS_OTA_PASSWORD)
- IP Addresses: Generic placeholder (192.168.1.XXX)
Security Best Practices
- API Encryption: Mandatory for Home Assistant communication
- WiFi Security: Requires WPA2/WPA3 encryption
- OTA Protection: Password-protected firmware updates
- Secret Management: External secrets.yaml file for credentials
📚 Documentation Quality
Comprehensive Guides
- Hardware Setup: Complete assembly instructions with safety warnings
- Configuration Guide: Step-by-step ESPHome setup tutorial
- Home Assistant Integration: Detailed HA setup and usage guide
- Troubleshooting: 400+ lines of common issues and solutions
- API Reference: Complete entity and service documentation
- Advanced Features: Customization and optimization guide
Professional Standards
- Safety Warnings: Prominent high-voltage warnings throughout
- Code Examples: Practical, tested configuration snippets
- Troubleshooting: Systematic diagnostic procedures
- Community Support: Clear paths for getting help
⚡ Performance Optimizations
Communication Efficiency
# Optimized Modbus settings
modbus_controller:
- id: jsymk
update_interval: 3s # Balanced responsiveness
command_throttle: 50ms # Prevents bus overload
# Display optimization
display:
update_interval: 3s # Matches sensor updates
rotation: 180° # Optimal viewing
Memory Management
- Font Loading: Efficient Google Fonts integration
- Sensor Filtering: Built-in noise reduction
- Update Intervals: Configurable for performance balance
🌟 Key Achievements
Technical Excellence
- Enhanced Reliability: Solved WiFi false positive issues
- Professional Display: Clean, readable interface with burn-in protection
- Comprehensive Monitoring: Full system health tracking
- Home Assistant Optimization: Proper entity configuration for energy dashboards
Documentation Excellence
- Complete Hardware Guide: From components to final assembly
- Professional Configuration: Step-by-step tutorials
- Extensive Troubleshooting: Common issues and solutions
- API Documentation: Complete reference for all entities
Community Value
- Fork-Ready: Anonymized configuration ready for immediate use
- Educational: Comprehensive guides for learning ESPHome
- Scalable: Configurable for different energy monitoring needs
- Safe: Proper safety warnings and best practices
🎯 Target Audience
Primary Users
- DIY Enthusiasts: Building energy monitoring systems
- Home Automation Users: Integrating with Home Assistant
- Energy Conscious: Monitoring household electricity usage
- Technical Learners: Understanding ESPHome and Modbus
Skill Levels
- Beginner: Complete guides with step-by-step instructions
- Intermediate: Configuration customization and optimization
- Advanced: Custom sensors, filters, and automation
🔄 Future Enhancement Opportunities
Potential Additions
- MQTT Integration: Alternative to Home Assistant API
- Cloud Connectivity: Remote monitoring capabilities
- Mobile App: Native mobile application
- Machine Learning: Predictive energy analytics
- Solar Integration: Solar panel monitoring support
Hardware Expansions
- Multiple Energy Meters: Support for additional circuits
- Environmental Sensors: Temperature, humidity monitoring
- Relay Control: Automatic load switching
- Data Logging: Local storage for historical analysis
🏆 Project Impact
This enhanced ESP32 Energy Meter project represents a significant improvement over the original implementation, providing:
- Enhanced User Experience: Reliable WiFi monitoring and professional display
- Production Readiness: Comprehensive testing and documentation
- Community Contribution: Open-source sharing under Creative Commons license
- Educational Value: Complete learning resource for ESPHome and energy monitoring
The project successfully transforms a basic energy monitoring concept into a professional-grade, well-documented, and community-ready solution that maintains the spirit and license of the original work while adding substantial value through technical enhancements and comprehensive documentation.
License: Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International
Original Attribution: Based on work by Giovanni Aggiustatutto
Enhanced By: MiniMax Agent
Repository Purpose: Community sharing and educational resource