Huawei Solar

3.0.0 verified Mon Apr 27 auth: no python

A Python wrapper for the Huawei Inverter Modbus TCP API. Current version is 3.0.0 (stable), released 2024. Releases are semi-regular. The v3 major release introduced breaking changes, including migration from pyModbus to tModbus, renaming of "bridge" classes to "device" classes, and replacement of `slave_id` with `unit_id`.

pip install huawei-solar

Common errors

error ImportError: cannot import name 'HuaweiSolarBridge' from 'huawei_solar' ↓

cause The class is no longer at top-level in v3, or you installed v3 but expect v2 API.

fix

Upgrade to v3 and import HuaweiSun2000: from huawei_solar import HuaweiSun2000

error AttributeError: 'HuaweiSun2000' object has no attribute 'read_batch' ↓

cause The method `read_batch` was renamed to `read` (which accepts multiple registers) or removed in v3.

fix

Use await inverter.read(['register1', 'register2']) instead.

error TypeError: __init__() got an unexpected keyword argument 'slave_id' ↓

cause In v3, `slave_id` was renamed to `unit_id`.

fix

Use unit_id=1 instead of slave_id=1.

Warnings

breaking v3 migration: `slave_id` parameter replaced with `unit_id` in all device classes. ↓

fix Change `slave_id=1` to `unit_id=1` when instantiating HuaweiSun2000.

gotcha The library uses asyncio; all read/write operations must be awaited. Forgetting `await` will hang the coroutine. ↓

fix Always use `await` when calling methods like `read()`, `write()`, `start()`, `stop()`.

deprecated The class `HuaweiSolarBridge` is deprecated in v3; use `HuaweiSun2000` (or `HuaweiSmartLogger`, `HuaweiSCharger`, `HuaweiSdongle`) instead. ↓

fix Replace `HuaweiSolarBridge` with the appropriate device class depending on the hardware.

gotcha When connecting via SmartLogger, not all registers are available (e.g., capacity control mode). ↓

fix Check the device's capabilities via `inverter.capabilities` attribute.

Imports

HuaweiSolarBridge
wrong
```
from huawei_solar.bridge import HuaweiSolarBridge
```
correct
```
from huawei_solar import HuaweiSolarBridge
```
In v2 the class was in huawei_solar.bridge; v3 moved it to top-level.
HuaweiSolarBridge
wrong
```
from huawei_solar.devices import HuaweiSolarBridge
```
correct
```
from huawei_solar import HuaweiSolarBridge
```
v3 renamed bridge classes to device classes (e.g., HuaweiSun2000), but bridge is an alias kept for backward compatibility.
HuaweiSun2000
```
from huawei_solar import HuaweiSun2000
```
The new device class for v3; replaces HuaweiSolarBridge for most use cases.

Quickstart

Connects to a Huawei inverter over TCP and reads a register.

import asyncio
from huawei_solar import HuaweiSun2000

async def main():
    # Connect over TCP
    inverter = HuaweiSun2000(host='192.168.1.100', port=502)
    await inverter.start()
    # Read a register, e.g., 'input_power'
    result = await inverter.read('input_power')
    print(f'Input power: {result.value} W')
    await inverter.stop()

asyncio.run(main())