pylxpweb 0.9.36b12

Python client library for Luxpower/EG4 inverter web monitoring API

pylxpweb

A Python client library for Luxpower/EG4 solar inverters and energy storage systems.

What It Does

pylxpweb provides programmatic access to the Luxpower/EG4 web monitoring API, 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

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.

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

• 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:

• GitHub Sponsors
• Ko-fi

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.