Pre-release

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 → Battery objects with auto-scaled properties
Async/Await: Built on aiohttp for 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, over TCP (an RS-485-to-Ethernet gateway) or serial (a USB adapter, or a serial URL such as socket://, rfc2217://, or esphome:// for a network / ESPHome serial proxy).
- The default setting is backend="auto", resolving to pymodbus except for esphome:// serial ports or an injected unit=, which select modbus_connection. The two wire backends are backend="pymodbus" and backend="modbus_connection", Home Assistant's shared-connection library (tmodbus + serialx; install the pylxpweb[modbus-connection] extra). esphome:// ports need the latter and are selected automatically. Both transports also accept a host-provided unit= (Home Assistant's async_get_unit()) to run over a link the host owns.
- The optional backend strictly matches TCP transaction IDs. Gateways that return zero or incorrect IDs can time out even when pymodbus's gateway workaround succeeds; validate the exact gateway and firmware with a packet capture before switching.
- To roll back an owned TCP or pyserial-supported serial transport, set its persisted backend to pymodbus (or auto) and recreate it with the same connection settings. An injected unit cannot roll back by toggle: remove the injection and coordinate ownership with the host first. An esphome:// port needs a different bridge or port to use pymodbus; auto continues selecting the optional backend for that URL.
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.

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.

_{Built with Omnigent — the open-source AI agent framework and meta-harness.}

Metadata

Release files for pylxpweb 0.10.0b11

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pylxpweb 0.10.0b11
File	Size	Uploaded	Provenance
pylxpweb-0.10.0b11.tar.gz	497.2 kB	Oct 4, 2026	With provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for pylxpweb 0.10.0b11
File	Interpreter	ABI	Platform	Reset
pylxpweb-0.10.0b11-py3-none-any.whl 554.1 kB Oct 4, 2026 With provenance	Python 3	none	any	Details

Total release size: 1.1 MB

Release files / pylxpweb-0.10.0b11.tar.gz

Download URL	pylxpweb-0.10.0b11.tar.gz
Size	497.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`497972c77dd5b098b1a187f8299a9aa78b7362010166b287aa5da2bb5cfbabc9`
BLAKE2b-256 checksum How to use checksums	`49546152bba7b83b5bdd371446b03acb9f3ccab5213f8963e5bd1801e35adc2d`
Upload date	Oct 4, 2026
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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/joyfulhouse/pylxpweb
Publishing commit: github.com/joyfulhouse/pylxpweb/tree/106b297eee3026230cf0e34a69a9efe638d68fda

Workflow

Publishing configuration: github.com/joyfulhouse/pylxpweb/blob/106b297eee3026230cf0e34a69a9efe638d68fda/.github/workflows/release.yml
Publishing logs: github.com/joyfulhouse/pylxpweb/actions/runs/37171026769/attempts/1

Artifact

Subject: pylxpweb-0.10.0b11.tar.gz
SHA-256 checksum: 497972c77dd5b098b1a187f8299a9aa78b7362010166b287aa5da2bb5cfbabc9 Verifying attestations

Release files / pylxpweb-0.10.0b11-py3-none-any.whl

Download URL	pylxpweb-0.10.0b11-py3-none-any.whl
Size	554.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`3c59cedca978058dd588d81e40f5836b93abf1d42b5db5adc663e6074d841a0c`
BLAKE2b-256 checksum How to use checksums	`b9669e3c8e596458bd11e50c6175b12b45edf6041a700f9d8f77684f6499a2ac`
Upload date	Oct 4, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/joyfulhouse/pylxpweb
Publishing commit: github.com/joyfulhouse/pylxpweb/tree/106b297eee3026230cf0e34a69a9efe638d68fda

Workflow

Publishing configuration: github.com/joyfulhouse/pylxpweb/blob/106b297eee3026230cf0e34a69a9efe638d68fda/.github/workflows/release.yml
Publishing logs: github.com/joyfulhouse/pylxpweb/actions/runs/37171026769/attempts/1

Artifact

Subject: pylxpweb-0.10.0b11-py3-none-any.whl
SHA-256 checksum: 3c59cedca978058dd588d81e40f5836b93abf1d42b5db5adc663e6074d841a0c Verifying attestations

Security for pylxpweb 0.10.0b11

Report project as malware

Provenance

Full provenance

All 2 files in this release have been uploaded with provenance metadata.

Attestation for pylxpweb-0.10.0b11.tar.gz

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/joyfulhouse/pylxpweb
Publishing commit: github.com/joyfulhouse/pylxpweb/tree/106b297eee3026230cf0e34a69a9efe638d68fda

Workflow

Publishing configuration: github.com/joyfulhouse/pylxpweb/blob/106b297eee3026230cf0e34a69a9efe638d68fda/.github/workflows/release.yml
Publishing logs: github.com/joyfulhouse/pylxpweb/actions/runs/37171026769/attempts/1

Artifact

Subject: pylxpweb-0.10.0b11.tar.gz
SHA-256 checksum: 497972c77dd5b098b1a187f8299a9aa78b7362010166b287aa5da2bb5cfbabc9 Verifying attestations

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.