This release is a pre-release and may not be stable for production use.
pylxpweb
A Python client library for Luxpower/EG4 solar inverters and energy storage systems.
What It Does
pylxpweb provides programmatic access to Luxpower/EG4 inverters — via the cloud web monitoring API or a direct local connection — enabling Python applications and Home Assistant integrations to read real-time inverter data, energy statistics, battery information, and GridBOSS metrics. It is the library backing the EG4 Web Monitor Home Assistant integration.
Features
- Complete API Coverage: Inverter runtime, energy statistics, battery BMS, and GridBOSS data
- Device Object Hierarchy: High-level
Station→ParallelGroup→BaseInverter/MIDDevice/BatteryBank→Batteryobjects with auto-scaled properties - Async/Await: Built on
aiohttpfor efficient async I/O - Session Management: Automatic authentication and session renewal
- Smart Caching: Configurable TTL caching to minimise API calls
- Type Safe: Comprehensive type hints and Pydantic models throughout
- Error Handling: Robust error handling with automatic retry and backoff
- Regional Endpoints: Supports all global Luxpower and EG4 endpoints
- Control Operations: Read and write inverter parameters, enable quick charge, set SOC limits
- Multiple Transports: cloud API, local WiFi dongle, direct Modbus (RS-485), or hybrid local+cloud
Supported Devices
- Inverters: FlexBOSS21, FlexBOSS18, 18KPV, 12KPV, XP series, and LXP variants
- GridBOSS: Microgrid interconnection devices (MID)
- Batteries: All EG4-compatible battery modules with BMS integration
Supported Regional Endpoints
| Region | Endpoint |
|---|---|
| US (EG4 Electronics) | https://monitor.eg4electronics.com (default) |
| US (Luxpower) | https://us.luxpowertek.com |
| Americas (Luxpower) | https://na.luxpowertek.com |
| Europe (Luxpower) | https://eu.luxpowertek.com |
| Asia Pacific (Luxpower) | https://sea.luxpowertek.com |
| Middle East & Africa (Luxpower) | https://af.luxpowertek.com |
| China (Luxpower) | https://server.luxpowertek.com |
The base URL is fully configurable to support regional variations and future endpoints.
Supported Transports
- Cloud (web API) — the original access method, via the regional endpoints above.
- WiFi dongle — connects locally to the inverter's WiFi dongle (the same device that
uploads data to the cloud), using Modbus encapsulated in a proprietary frame format.
- The dongle serves the cloud and local clients at the same time but does not clearly separate which side requested what, so occasional "Response mismatch" debug messages are expected — the library detects a response meant for the cloud and retries.
- Dongles with encryption enabled (label E-WIFI ENC) do not work locally; if you have one, ask Luxpower support to downgrade its firmware.
- Modbus — a direct Modbus connection to the inverter's RS-485 port.
- Hybrid — combines one local connection with the cloud API (local polling with cloud fallback and cloud-only supplemental data).
A local connection must have a single client: sharing the same dongle or RS-485 line between multiple applications (e.g. Home Assistant plus a script, or two Home Assistant instances) causes interleaved responses, data corruption, and intermittent errors.
Installation
See INSTALL.md for the complete guide.
pip install pylxpweb
# or
uv add pylxpweb
Requires Python 3.13+.
Quick Start
Using Device Objects (Recommended)
import asyncio
from pylxpweb import LuxpowerClient
from pylxpweb.devices.station import Station
async def main():
async with LuxpowerClient(
username="your_username",
password="your_password",
base_url="https://monitor.eg4electronics.com"
) as client:
stations = await Station.load_all(client)
station = stations[0]
for inverter in station.all_inverters:
await inverter.refresh()
print(f"{inverter.model} {inverter.serial_number}:")
print(f" PV Power: {inverter.pv_total_power}W")
print(f" Battery: {inverter.battery_soc}% @ {inverter.battery_voltage}V")
print(f" Grid: {inverter.grid_voltage_r}V @ {inverter.grid_frequency}Hz")
print(f" Today: {inverter.total_energy_today}kWh")
asyncio.run(main())
Device objects handle all value scaling automatically — no manual division required.
Usage
Low-Level API Access
For direct endpoint calls without the device-object layer:
async with LuxpowerClient(username, password) as client:
plants = await client.api.plants.get_plants()
plant_id = plants.rows[0].plantId
devices = await client.api.devices.get_devices(str(plant_id))
serial = devices.rows[0].serialNum
runtime = await client.api.devices.get_inverter_runtime(serial)
# Raw API returns scaled integers — divide as needed:
print(f"Grid Voltage: {runtime.vacr / 10}V")
print(f"Grid Frequency: {runtime.fac / 100}Hz")
print(f"Battery Voltage: {runtime.vBat / 10}V")
Control Operations
async with LuxpowerClient(username, password) as client:
serial = "1234567890"
await client.set_quick_charge(serial, enabled=True)
await client.set_charge_soc_limit(serial, limit=90)
await client.set_operating_mode(serial, mode="standby")
params = await client.read_parameters(serial, [21, 22, 23])
Error Handling
from pylxpweb import LuxpowerClient, AuthenticationError, ConnectionError, APIError
try:
async with LuxpowerClient(username, password) as client:
runtime = await client.get_inverter_runtime(serial)
except AuthenticationError as e:
print(f"Login failed: {e}")
except ConnectionError as e:
print(f"Network error: {e}")
except APIError as e:
print(f"API error: {e}")
Data Scaling
Device objects auto-scale all values. For raw API use, apply these factors manually:
| Data Type | Factor | Example raw | Scaled |
|---|---|---|---|
| Inverter Voltage | ÷10 | 2410 | 241.0 V |
| Battery Voltage (Bank) | ÷10 | 539 | 53.9 V |
| Battery Voltage (Module) | ÷100 | 5394 | 53.94 V |
| Cell Voltage | ÷1000 | 3364 | 3.364 V |
| Current | ÷100 | 1500 | 15.00 A |
| Frequency | ÷100 | 5998 | 59.98 Hz |
| Power | Direct | 1030 | 1030 W |
| Temperature | Direct | 39 | 39 °C |
| Energy | ÷10 | 184 | 18.4 kWh |
See docs/SCALING_GUIDE.md for the full reference.
API Reference
Full reference documentation lives in docs/. Key entry points:
| Document | Contents |
|---|---|
| docs/api/LUXPOWER_API.md | Complete endpoint catalog, authentication, error codes |
| docs/PROPERTY_REFERENCE.md | All device properties with types and scaling |
| docs/PARAMETER_REFERENCE.md | Hold/input register definitions and control parameters |
| docs/SCALING_GUIDE.md | Scaling factors for raw API data |
| docs/USAGE_GUIDE.md | Comprehensive usage examples |
| docs/DEVICE_TYPES.md | Supported device types and capabilities |
The docs/ index is at docs/README.md.
Development
See docs/DEVELOPMENT.md. In short:
git clone https://github.com/joyfulhouse/pylxpweb.git
cd pylxpweb
uv sync
uv run pytest
uv run ruff check
uv run mypy
Support
- Join the JoyfulHouse Discord for support and discussion across all JoyfulHouse Home Assistant integrations and libraries.
- Issues: https://github.com/joyfulhouse/pylxpweb/issues
- PyPI: https://pypi.org/project/pylxpweb/
Support Development
If this library is useful to you, please consider supporting its development:
License
This project is licensed under the MIT License — see LICENSE for details.
Related Projects
- EG4 Web Monitor — the Home Assistant integration built on this library.
Credits
This project builds upon research and knowledge from the Home Assistant community. Special thanks to the Home Assistant community for their pioneering work with EG4 and Luxpower devices — API endpoint research, documentation, and best practices shaped this library from the start.
Disclaimer: Unofficial library, not affiliated with Luxpower or EG4 Electronics. Communicates with the official API using the same endpoints as the official web interface.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pylxpweb-0.9.39b2.tar.gz.
File metadata
- Download URL: pylxpweb-0.9.39b2.tar.gz
- Upload date:
- Size: 412.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
692982d5da3735bd3a292595ab708ecf7a32b7aa1e02513f9a24d4a66412b615
|
|
| MD5 |
ecd94a92e83931091bbb71d2738a9fab
|
|
| BLAKE2b-256 |
53a295883d55a3952f92c2164204d6397e12c93b61c837cbbcd28fe4019e1dca
|
Provenance
The following attestation bundles were made for pylxpweb-0.9.39b2.tar.gz:
Publisher:
release.yml on joyfulhouse/pylxpweb
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pylxpweb-0.9.39b2.tar.gz -
Subject digest:
692982d5da3735bd3a292595ab708ecf7a32b7aa1e02513f9a24d4a66412b615 - Sigstore transparency entry: 2182363255
- Sigstore integration time:
-
Permalink:
joyfulhouse/pylxpweb@9a4dd8f8dfe13e8cc55ce60eb995e7116ecb784d -
Branch / Tag:
refs/tags/v0.9.39b2 - Owner: https://github.com/joyfulhouse
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@9a4dd8f8dfe13e8cc55ce60eb995e7116ecb784d -
Trigger Event:
release
-
Statement type:
File details
Details for the file pylxpweb-0.9.39b2-py3-none-any.whl.
File metadata
- Download URL: pylxpweb-0.9.39b2-py3-none-any.whl
- Upload date:
- Size: 466.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
35da07b5f0ba26ba9a82d68441e6e7bf9693e04818ab7ee0e1a312b787d4a88e
|
|
| MD5 |
2f380f49aaf0c2ae560c597343fdf928
|
|
| BLAKE2b-256 |
e6dfd6f9e49737ef93745ed0e12ef2fcfcf5c351c3b063ec82d9045306b43bd4
|
Provenance
The following attestation bundles were made for pylxpweb-0.9.39b2-py3-none-any.whl:
Publisher:
release.yml on joyfulhouse/pylxpweb
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
pylxpweb-0.9.39b2-py3-none-any.whl -
Subject digest:
35da07b5f0ba26ba9a82d68441e6e7bf9693e04818ab7ee0e1a312b787d4a88e - Sigstore transparency entry: 2182363861
- Sigstore integration time:
-
Permalink:
joyfulhouse/pylxpweb@9a4dd8f8dfe13e8cc55ce60eb995e7116ecb784d -
Branch / Tag:
refs/tags/v0.9.39b2 - Owner: https://github.com/joyfulhouse
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@9a4dd8f8dfe13e8cc55ce60eb995e7116ecb784d -
Trigger Event:
release
-
Statement type:
