[Integration] EG4/Luxpower Web Monitor — Local Modbus, Cloud & Hybrid Monitoring + Control for EG4 Solar Systems
EG4 Web Monitor is a comprehensive Home Assistant custom integration for EG4 and Luxpower-compatible solar equipment — inverters, GridBOSS microgrid devices, and batteries. It has grown far beyond its cloud-monitoring roots: today it offers fully local Modbus polling (5-second updates, no internet required), cloud API access, or a hybrid of both, plus a deep control surface for automations.
The integration meets the Home Assistant Platinum quality tier (the highest level: fully async, strict typing, websession injection) and is translated into 12 languages.
- GitHub: GitHub - joyfulhouse/eg4_web_monitor: Local (RS485 Modbus) + Cloud hybrid integration for EG4 and Luxpower inverters — GridBOSS, FlexBOSS, 18kPV, 12kPV, XP, LXP-LB, and batteries · GitHub
- Discord: joyful.house
Connection Options
| Connection type | How | Update speed | Internet required |
|---|---|---|---|
| Cloud API | Your existing monitor.eg4electronics.com account | 30 s | Yes |
| Local Modbus TCP | RS485-to-Ethernet adapter (e.g. Waveshare) | 5 s | No |
| WiFi dongle | Direct connection to the inverter’s stock WiFi dongle | 5 s | No |
| Serial (USB/RS485) | USB-to-RS485 adapter on your HA host | 5 s | No |
| Hybrid | Local polling + cloud for cloud-only features and write fallback | 5 s | Cloud features only |
The mode is derived automatically from what you configure — cloud credentials only → Cloud, local devices only → Local, both → Hybrid. Hybrid gives you the best of both: fast local polling, with the cloud filling in cloud-only data (DST auto-sync, portal event log, AC Couple parameters) and acting as a fallback path for control writes if the local link drops.
Supported Equipment
- Inverters: FlexBOSS21, FlexBOSS18, 18kPV, 12kPV, XP series (6000XP/12000XP), LXP-EU (three-phase), LXP-LB-BR (Brazil 10 kW)
- GridBOSS: microgrid interconnection device with smart port monitoring and configuration
- Batteries: all EG4-compatible modules with BMS integration and individual cell monitoring — including banks with more than 4 batteries (round-robin battery tracking)
- Multi-station: monitor multiple installations from one account, multiple inverters in parallel groups, full Station → Parallel Group → Inverter → Battery device hierarchy
Monitoring
Inverters (~50+ sensors each): AC/DC power, PV generation per string, battery charge/discharge, voltages, currents, frequency, split-phase per-leg detail, daily/lifetime energy, temperatures, firmware version, plus a friendly Operating State sensor and Off-Grid binary sensor decoded from the status code.
Individual batteries (~15 sensors each, one HA device per battery): voltage, current, SoC, SoH, cycle count, capacities, max/min cell voltages and temperatures, and a calculated Cell Voltage Delta sensor — great for spotting cell imbalance.
Battery bank aggregates: bank-level voltage, current, SoC, cell extremes, and charge/discharge current limits straight from the BMS — no CAN bus needed.
GridBOSS (~80+ sensors): grid interconnection L1/L2 phases, UPS and backup load management, 4 smart load ports (Unused / Smart Load / AC Couple), AC coupling energy, generator monitoring.
Portal event log (Cloud/Hybrid): a Last Event diagnostic sensor per inverter and GridBOSS surfaces faults/warnings that only exist in EG4’s cloud event log (transients that fall between register polls), with event code, type, timestamps, and status as attributes.
Data integrity: WiFi dongle cross-request validation, canary checks against corrupt Modbus reads, and energy monotonicity guards — bad readings get rejected instead of polluting your energy dashboard.
Control Entities
This is where the integration really goes beyond monitoring:
- Switches: Quick Charge (with local Modbus start on supported models — per-inverter, unlike the portal’s group-wide start), Battery Backup (EPS), AC Charge, Forced Charge/Discharge, Grid Sell Back, Fast Zero Export, Share Battery, AC Couple, DST, and more
- Numbers: SOC limits (on-grid/off-grid cutoffs, system charge limit — including 101% for LiFePO4 top-balancing), charge/discharge current and power limits, AC/PV charge power, grid peak shaving power, voltage limits (charge, cut-off, AC charge start/end, stop discharge), start charge/discharge power thresholds, AC Couple Start/End SOC window, Quick Charge duration
- Selects: operating mode, GridBOSS smart port modes, and battery control mode — regulate by SOC (default) or Voltage, with the full EG4-portal label cross-reference documented
- Time entities: schedule windows for seven schedule families — AC Charge, Forced Charge, Forced Discharge, AC First, Peak Shaving, Generator, and Off-Grid (3 windows each where supported)
- Update entities: firmware updates from within Home Assistant, including multi-step/multi-component update chains with progress reporting
- Button: force an immediate data refresh
Controls are capability-aware: entities that don’t apply to your model or grid configuration (grid-tied vs. off-grid families) are gated automatically, and unsupported writes surface proper HA errors instead of failing silently.
Service Actions
| Service | What it does |
|---|---|
eg4_web_monitor.import_historical_data |
Backfill years of daily energy history from the EG4 cloud into HA long-term statistics (PV yield, consumption, grid import/export, battery charge/discharge) — selectable in the Energy dashboard, idempotent, with a dry-run preview |
eg4_web_monitor.reconcile_history |
Fill gaps in your energy-sensor history from the cloud (e.g. after HA downtime) |
eg4_web_monitor.fetch_events |
Pull the recent portal event log on demand as response data |
eg4_web_monitor.refresh_data |
Force an immediate refresh of all device data |
The historical import is a favorite for new installs: your Energy dashboard doesn’t have to start from zero — pull in your system’s full history back to commissioning day.
Automation Examples
The docs ship worked examples, including:
- Off-peak charging: turn Quick Charge on/off on a schedule
- Battery cell balancing: watch the Cell Voltage Delta sensors, bump the SOC limit to 101% for a top-balance when imbalance persists, then return to normal automatically
- Grid outage detection: a debounced template binary sensor built from grid voltage + frequency (the reliable signal on off-grid-configured systems), with outage/recovery notifications
- Smart port transfer: script the AC Couple switch to safely de-energize a smart-port source on demand
# Taste of it — charge during off-peak:
automation:
- alias: "Charge Batteries During Off-Peak"
trigger:
- platform: time
at: "23:00:00"
action:
- service: switch.turn_on
target:
entity_id: switch.18kpv_1234567890_quick_charge
See the README for the full versions.
Installation
HACS (recommended):
- Add custom repository:
https://github.com/joyfulhouse/eg4_web_monitor - Install EG4 Web Monitor, restart Home Assistant
- Settings → Devices & Services → Add Integration → “EG4 Web Monitor”
- Pick Cloud (enter credentials, select station) or Local Device (Modbus TCP / WiFi dongle / Serial — model and serial auto-detected). Add both for Hybrid.
Requires Home Assistant 2026.1.0 or newer.
Production Quality
Home Assistant Platinum quality tier — fully async, strict mypy typing, websession injection- 2,000+ automated tests across the integration and the underlying pylxpweb library
- Register-level documentation — every register→sensor and API→sensor mapping is documented in the repo (
docs/DATA_MAPPING.md), plus a full OpenAPI spec of the EG4 cloud API - UI reconfiguration & reauthentication — change credentials, stations, or local devices without losing entities
- 12 languages: Chinese (Simplified & Traditional), Dutch, French, German, Italian, Japanese, Korean, Polish, Portuguese, Russian, Spanish
Documentation & Support
- GitHub: GitHub - joyfulhouse/eg4_web_monitor: Local (RS485 Modbus) + Cloud hybrid integration for EG4 and Luxpower inverters — GridBOSS, FlexBOSS, 18kPV, 12kPV, XP, LXP-LB, and batteries · GitHub — full installation, configuration, troubleshooting, and architecture docs
- Discord: joyful.house — JoyfulHouse community server for support and discussion
- Issues & feature requests: GitHub issues — much of the current feature set came directly from community reports and live hardware testing by users
Credits
Built on the pylxpweb library. This integration was inspired by and built upon the pioneering work of @twistedroutes and the eg4_inverter_ha project.
Disclaimer
This is an unofficial integration, not affiliated with EG4 Electronics. Control entities write settings to your inverter — use at your own risk and verify compatibility with your equipment. MIT licensed.
Running EG4 gear? Try it out and let me know how it works for your setup — questions, issues, and success stories welcome below! 
EG4 Web Monitor v1.3.0: Quick Charge Control Implementation
Switch Entity Implementation
Device Compatibility
Entity Examples
User Experience
How to Get It
What to Expect
Troubleshooting
