goodwe-modbus

Python library to communicate with Goodwe inverters over Modbus.

Built on top of modbus-connection, a framework that maps Modbus register maps to typed Python objects.

Installation

pip install goodwe-modbus

Quick start

import asyncio
from modbus_connection import ModbusConnection, ModbusTcpParams
from goodwe_modbus import GoodweInverter

async def main():
    connection = ModbusConnection(
        ModbusTcpParams(host="10.0.0.234", port=502),
    )
    await connection.connect()
    try:
        unit = connection.for_unit(246)
        device = GoodweInverter(unit)
        await device.async_update()

        print(f"Serial: {device.identity.serial}")
        print(f"Model: {device.identity.type}")
        print(f"State: {device.state.system_state}")
        print(f"Grid power: {device.grid.power} W")
        print(f"Temperature: {device.state.inverter_temperature} C")
        print(f"Energy today: {device.energy.daily_energy} kWh")
        print(f"Energy total: {device.energy.lifetime_energy} kWh")
    finally:
        await connection.close()

asyncio.run(main())

API

GoodweInverter

The top-level object. Reach it through a ModbusUnit:

device = GoodweInverter(unit)
await device.async_update()

Sub-components

Update methods

Writing settings

await device.powercontrol.async_set_active_power_export_limit(75)

Limits export to 75 % of rated output.

CLI tool

A command-line query tool is included:

# TCP connection
python -m goodwe_modbus.query --host 10.0.0.234 --port 502 --unit 246

# Serial over TCP (socket://)
python -m goodwe_modbus.query --device socket://10.0.0.234:502 --unit 246

Development

git clone https://github.com/theneweinstein/goodwe_modbus.git
cd goodwe_modbus
uv sync

Linting

ruff check .
ruff format --check .

Related

• ha-goodwe-modbus -- Home Assistant integration that uses this library.