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
Metadata
1 maintainer
Release files for pylxpweb 0.10.0b9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pylxpweb-0.10.0b9.tar.gz | 483.7 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pylxpweb-0.10.0b9-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 1.0 MB
Release files / pylxpweb-0.10.0b9.tar.gz
| Download URL | pylxpweb-0.10.0b9.tar.gz |
|---|---|
| Size | 483.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7a3da3150c3eec367edbbef35012861455007c0bd0f59445cd0375bfa5fbd208
|
|
BLAKE2b-256 checksum How to use checksums |
c6634c3a3b545f245cfa3e33cb35cfb3d070447a9f878472c7ad8f829d76fa91
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency logRelease files / pylxpweb-0.10.0b9-py3-none-any.whl
| Download URL | pylxpweb-0.10.0b9-py3-none-any.whl |
|---|---|
| Size | 539.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
13369bd77f8c6079659a0b1c88bd0b90865709f9d7b25d420ad519205f345ead
|
|
BLAKE2b-256 checksum How to use checksums |
a4f24976581862c872cc15cd45232e74b08a23837b4f92e97fadcecc871fcad0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 4, 2026.
Transparency log
