A comprehensive Home Assistant integration to monitor and control LuxPower inverters via their Modbus TCP interface.
This integration connects directly to your inverter's WiFi dongle, providing real-time data and control over various settings without relying on the cloud.
Note
Version 1.0.0 brings a major architecture overhaul, 140+ new entities, and Battery BMS monitoring with auto-discovery. See the Battery Monitoring section below for details.
- Real-time Monitoring: Track PV power, battery state of charge (SOC), grid import/export, load consumption, and more.
- Inverter Control: Change charge/discharge currents, set timed charging/discharging periods, and enable/disable features like grid feed-in.
- Organized Device Structure: (v0.2.0+) Entities are automatically grouped into logical sub-devices (PV, Grid, EPS, Generator, Battery) for better organization in Home Assistant.
- Detailed States: A user-friendly text sensor shows exactly what the inverter is doing (e.g., "PV Powering Load & Charging Battery").
- Calculated Sensors: Includes derived sensors like "Load Percentage" for a clearer view of your system's performance.
- Local Polling: All communication is local. No cloud dependency.
Your LuxPower inverter's WiFi data logging dongle must be connected to the same local network as your Home Assistant instance. You will need to know its IP address.
This integration is available in the default HACS repository.
- Navigate to HACS > Integrations in your Home Assistant instance.
- Click the Explore & Download Repositories button.
- Search for "Luxpower Inverter (Modbus)" and click "Download".
- Restart Home Assistant when prompted.
- Copy the
lxp_modbusfolder from this repository into your Home Assistantcustom_componentsdirectory. - Restart Home Assistant.
Configuration is done entirely through the Home Assistant UI.
- Go to Settings > Devices & Services.
- Click Add Integration and search for "Luxpower Inverter (Modbus)".
- Fill in the required details for your inverter.
| Name | Type | Description |
|---|---|---|
| IP Address | string | (Required) The IP address of your inverter's WiFi dongle. |
| Port | integer | (Required) The communication port for the Modbus connection, typically 8000. |
| Dongle Serial Number | string | (Required) The 10-character serial number of your WiFi dongle. |
| Inverter Serial Number | string | (Required) The 10-character serial number of your inverter. |
| Polling Interval | integer | (Required) How often (in seconds) to poll the inverter for data. Default is 60. |
| Inverter Rated Power | integer | (Required) The rated power of your inverter in Watts (e.g., 5000 for a 5kW model). |
| Entity Prefix | string | (Optional) A custom prefix for all entity names (e.g., 'LXP'). Leave blank for no prefix. |
| Read-Only Mode | boolean | (Optional) See the important warning below before changing this setting. |
| Register Block Size | integer | (Optional) Size of register blocks to read. Use 125 (default) for most inverters, use 40 for older firmware versions that don't support larger blocks. |
| Connection Retry Attempts | integer | Number of connection retry attempts before giving up (default is 3). |
| Enable Device Grouping | boolean | (v0.2.0+) Group entities into logical sub-devices for better organization (default: enabled). |
| Battery Entities | string | (v1.0.0+) Battery monitoring configuration: none (disabled), auto (auto-discover), or comma-separated battery serial numbers. |
Warning
The Read-Only Mode setting fundamentally changes the type of entities this integration creates for inverter controls.
- If
Read-Only Modeis OFF (default): The integration will create interactive entities likenumber,switch, andselectto allow you to control your inverter. - If
Read-Only Modeis ON: All of those control entities will instead be created as read-onlysensorentities. You will be able to see the current settings, but you will not be able to change them.
Please choose this setting carefully during the initial setup. Changing this option later by reconfiguring the integration will delete your existing control entities and create new sensor entities (or vice-versa). This will break any dashboards, automations, or history that relied on the old entities.
Tip
The Register Block Size option allows you to adjust how the integration communicates with your inverter:
- 125 (Default): Use for most modern inverter firmware versions for optimal performance.
- 40: Use if you have an older inverter firmware that doesn't support larger register block reads.
If you experience communication errors with the default setting, try switching to the smaller block size.
Tip
This integration includes advanced reconnection logic to handle temporary network or inverter communication issues:
- Connection Retry Attempts: Configure how many immediate retry attempts the integration makes when connection fails (default: 3).
- Automatic Recovery: If connection is lost, the integration will temporarily use cached data while attempting to reconnect.
- Adaptive Polling: During recovery mode, the polling frequency automatically adjusts to find the optimal balance between quick reconnection and network load.
- Graceful Degradation: Entities remain available with last known good values during brief connection interruptions.
These features ensure that temporary network issues don't cause your automations to fail or entities to show as unavailable.
Important
Starting with version 0.2.0, this integration introduces Device Grouping to better organize the 250+ entities created by your inverter:
- PV Group (25 entities): Solar panel monitoring and MPPT controls
- Grid Group (42 entities): Utility grid connection and import/export data
- EPS Group (18 entities): Emergency Power Supply / backup load outputs
- Generator Group (12 entities): Backup generator monitoring and controls
- Battery Group (62 entities): BMS data, cell voltages, temperatures, and battery controls
Configuration Options:
- Enabled by default for new installations - provides much better organization in Home Assistant
- Optional - can be disabled in integration settings if you prefer all entities under one device
- Configurable - can be toggled on/off at any time through the integration options
For Existing Users: When updating to v0.2.0+, device grouping will be automatically enabled. If you prefer the old single-device layout, you can disable it in the integration settings.
Tip
Starting with version 1.0.0, this integration can read battery data directly from the BMS via Modbus register range 5000+. This provides 18 sensors per battery, including:
- State: SOC, SOH, Voltage, Current, Capacity, Cycle Count
- Cell Details: Max/Min Cell Voltage, Max/Min Cell Temperature, Cell Voltage Difference
- Diagnostics: Firmware Version, Max Charge/Discharge Current
Configuration Options:
none(default): Battery monitoring is disabled.auto: Automatically discovers connected batteries and creates entities dynamically.- Comma-separated serial numbers (e.g.,
SN1234567890,SN0987654321): Manually specify which batteries to monitor.
When Device Grouping is enabled, each battery appears as a separate sub-device under the main inverter for easy navigation.
Requirements: Battery data polling requires a Register Block Size of at least 120. If your block size is set to 40 (older firmware), battery monitoring will not be available.
This integration creates a wide range of entities to give you full visibility and control over your inverter.
Provides detailed operational data, including:
- Inverter State (Text and Code)
- Battery SOC & SOH
- PV Power (Total and per-string)
- Grid Import/Export Power
- Load Power
- Battery Charge/Discharge Power
- Daily & Total Energy Statistics (PV, Grid, Load, etc.)
- Temperatures (Battery, Radiator, etc.)
- Voltages, Currents, and Frequencies for Grid, EPS, and Battery.
- Calculated Load Percentage
Allows control over inverter settings:
- Charge & Discharge Currents
- AC Charge Power Limit
- End of Discharge (EOD) SOC
- Battery Stop Charging Voltage/SOC
Enable or disable key features on the fly:
- AC Charging Enable
- Feed-In Grid Enable
- Forced Discharge Enable
- Eco & Green Modes
Choose from predefined operational modes:
- AC Charge Type (by Time, SOC, etc.)
- Output Priority (Battery first, PV first, etc.)
Set schedules for timed operations:
- AC Charging Start & End Times
- Peak Shaving Start & End Times
This integration includes blueprints to help you get started with powerful automations.
There are two ways to get the blueprints into your Home Assistant instance.
Method 1: Direct Import Button (Easiest)
Click the "Import Blueprint" button under the blueprint you wish to use. This will take you to your Home Assistant instance to complete the import.
Method 2: Manual Import
1. In Home Assistant, go to Settings > Automations & Scenes. 2. Select the Blueprints tab. 3. Click the Import Blueprint button in the bottom right. 4. Paste the "Manual Import URL" for the blueprint you want. 5. Click "Preview Blueprint" and then "Import Blueprint".
This script blueprint allows you to temporarily force the inverter to charge from the grid for a set amount of time. It saves your existing settings, applies the temporary charge schedule, and restores your settings when finished.
Manual Import URL:
https://raw.githubusercontent.com/ant0nkr/luxpower-ha-integration/main/blueprints/script/lxp_force_charge.yaml
This automation blueprint allows you to charge your inverter's battery from the AC grid until it reaches a specific State of Charge (SOC) percentage. It automatically saves a snapshot of your current inverter settings before starting and perfectly restores them once the target SOC is met.
Manual Import URL:
https://raw.githubusercontent.com/ant0nkr/luxpower-ha-integration/main/blueprints/automation/lxp_charge_automation.yaml
If you are having issues, you can enable debug logging by adding the following to your configuration.yaml file:
logger:
default: info
logs:
custom_components.lxp_modbus: debug