pylxpweb

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

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.

• 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

• Inverters: FlexBOSS21, FlexBOSS18, 18KPV, 12KPV, XP series, and LXP variants
• GridBOSS: Microgrid interconnection devices (MID)
• Batteries: All EG4-compatible battery modules with BMS integration

The base URL is fully configurable to support regional variations and future endpoints.

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

See INSTALL.md for the complete guide.

pip install pylxpweb
# or
uv add pylxpweb

Requires Python 3.13+.

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.

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")

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])

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}")

Device objects auto-scale all values. For raw API use, apply these factors manually:

See docs/SCALING_GUIDE.md for the full reference.

Full reference documentation lives in docs/. Key entry points:

The docs/ index is at docs/README.md.

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

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

If this library is useful to you, please consider supporting its development:

• GitHub Sponsors
• Ko-fi

This project is licensed under the MIT License — see LICENSE for details.

• EG4 Web Monitor — the Home Assistant integration built on this library.

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.}