GivEnergy Modbus
A Python library for communicating with GivEnergy inverters via Modbus TCP on a local network, with no dependency on the GivEnergy Cloud. Inspired by and originally built on pymodbus, it now provides its own asyncio-based framer, decoder and PDUs specific to the GivEnergy implementation.
⚠️ This project makes no representations as to its completeness or correctness. You use it at your own risk — if your inverter mysteriously explodes because you accidentally set the
BOOMTIMEregister or you consume a MWh of electricity doing SOC calibration: you really are on your own. We make every effort to prevent you from shooting yourself in the foot, so as long as you use the client and its exposed methods, you should be perfectly safe.
- Documentation: https://dewet22.github.io/givenergy-modbus
- GitHub: https://github.com/dewet22/givenergy-modbus
- PyPI: https://pypi.org/project/givenergy-modbus/
- Free software: Apache-2.0
Features
- Reading all registers and decoding them into their representative datatypes
- Writing data to holding registers that are deemed to be safe to set configuration on the inverter
Supported hardware
The library speaks to GivEnergy plants through the wifi/ethernet data adapter ("dongle") using their Modbus-TCP variant. Support is evidence-based: validated means the decode is pinned by golden-master tests against committed wire captures from real hardware in tests/fixtures/captures/.
| Plant type | Status | Notes |
|---|---|---|
| Single-phase hybrid (Gen 1/Gen 3) | ✅ Validated | The reference platform. Battery-less (AC/PV-only) configurations detect correctly too. |
| AC-coupled single-phase (AC / AC Gen 3) | ✅ Validated | Including EMS-managed operation. |
| All-in-One (AIO) | ✅ Validated | HV battery stack decoded per-module (BCU + BMS + per-BMU cell data at their own device addresses). |
| Three-phase hybrid (HV) | ✅ Validated | Per-phase electrical data; HV stacks with per-cell BMU decode. |
| EMS controller | ✅ Validated | Plant-level rollup, managed-inverter enumeration, EMS-specific register banks. |
| Gateway (Gen 1) | ✅ Validated | Fronting parallel AIOs; battery data register-embedded per-AIO in the gateway rollup. |
| Single-phase hybrid Gen 2 | ⚠️ Untested | Modelled, but no Gen 2 unit has ever been observed — a field report from an EA-prefix owner would settle the device type code. |
| Polar, commercial variants (AIO/EMS Commercial), 3-phase AC | ⚠️ Untested | Model codes known; decode unverified against real hardware. |
Batteries: LV packs (chained at their own device addresses), the LV BCU, HV stacks (BCU/BMS/per-module BMUs), and gateway-embedded per-AIO data are all modelled. Energy meters (EM115/EM418, up to eight) decode including per-phase power factor and apparent power.
Firmware oddities are documented as we find them in hardware & firmware quirks. If your hardware isn't listed — or misbehaves — an issue with a short wire capture is the fastest route to support: every ✅ above exists because someone contributed one.
How to use
The client is async. Use it inside an asyncio event loop; commands are plain functions that return request lists
which you send via one_shot_command or execute:
import asyncio
from givenergy_modbus.client.client import Client
from givenergy_modbus.client import commands
from givenergy_modbus.model import TimeSlot
from givenergy_modbus.model.inverter import Model
async def main():
client = Client(host="192.168.99.99", port=8899)
await client.connect()
# Detect the topology once, then read the config banks (needed for slot_map)
await client.detect()
await client.load_config()
plant = client.plant
# Write configuration to the device
await client.one_shot_command(commands.set_charge_target_enabled(80))
# set a charging slot from 00:30 to 04:30; slot_map selects correct registers for this model
await client.one_shot_command(
commands.set_charge_slot(1, TimeSlot.from_components(0, 30, 4, 30), plant.inverter.slot_map)
)
# set the inverter to charge from excess solar and discharge to meet demand
await client.one_shot_command(commands.set_mode_dynamic())
assert plant.inverter_serial_number == 'SA1234G567'
assert plant.inverter.model == Model.HYBRID
assert plant.inverter.enable_charge_target
assert plant.inverter.charge_slot_1 == TimeSlot.from_components(0, 30, 4, 30)
assert plant.inverter.model_dump() == {
'serial_number': 'SA1234G567',
'device_type_code': '3001',
'charge_slot_1': TimeSlot.from_components(0, 30, 4, 30),
...
}
assert plant.inverter.model_dump_json() == '{"serial_number": "SA1234G567", "device_type_code": "3001", ...'
assert plant.batteries[0].serial_number == 'BG1234G567'
assert plant.batteries[0].v_cell_01 == 3.117
assert plant.batteries[0].model_dump() == {
'bms_firmware_version': 3005,
'cap_design': 160.0,
...
}
assert plant.batteries[0].model_dump_json() == '{"serial_number": "BG1234G567", "v_cell_01": 3.117, ...'
await client.close()
asyncio.run(main())
Credits
This package was created with Cookiecutter and the waynerv/cookiecutter-pypackage project template.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file givenergy_modbus-2.13.0.tar.gz.
File metadata
- Download URL: givenergy_modbus-2.13.0.tar.gz
- Upload date:
- Size: 610.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
f39939aaf5becd1d0a6e7b603993f0064f4528e2890e6f2632ba104c6f60b467
|
|
| MD5 |
bd420a34181228b7073f465cae63f202
|
|
| BLAKE2b-256 |
1e5bea97d904e6eedfff9a1cb0612c6028802788edf69ce4fa485e9fcfbf232c
|
Provenance
The following attestation bundles were made for givenergy_modbus-2.13.0.tar.gz:
Publisher:
release.yml on dewet22/givenergy-modbus
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
givenergy_modbus-2.13.0.tar.gz -
Subject digest:
f39939aaf5becd1d0a6e7b603993f0064f4528e2890e6f2632ba104c6f60b467 - Sigstore transparency entry: 2334844284
- Sigstore integration time:
-
Permalink:
dewet22/givenergy-modbus@dbb558f54238bda914a1f295bd6e51259a2ff89d -
Branch / Tag:
refs/heads/main - Owner: https://github.com/dewet22
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@dbb558f54238bda914a1f295bd6e51259a2ff89d -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file givenergy_modbus-2.13.0-py3-none-any.whl.
File metadata
- Download URL: givenergy_modbus-2.13.0-py3-none-any.whl
- Upload date:
- Size: 220.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: twine/6.1.0 CPython/3.13.13
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
48109fac7ccb2affca0169f82ebc7615f332940ebf5e737ff87d679d71cf392d
|
|
| MD5 |
b560303183dc3a5a08e5a781599dac2e
|
|
| BLAKE2b-256 |
d1fba057f0dbe535139c5848bf0d4f43f4aa2acb7f7f63cdd30895686ec5ab55
|
Provenance
The following attestation bundles were made for givenergy_modbus-2.13.0-py3-none-any.whl:
Publisher:
release.yml on dewet22/givenergy-modbus
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
givenergy_modbus-2.13.0-py3-none-any.whl -
Subject digest:
48109fac7ccb2affca0169f82ebc7615f332940ebf5e737ff87d679d71cf392d - Sigstore transparency entry: 2334844303
- Sigstore integration time:
-
Permalink:
dewet22/givenergy-modbus@dbb558f54238bda914a1f295bd6e51259a2ff89d -
Branch / Tag:
refs/heads/main - Owner: https://github.com/dewet22
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@dbb558f54238bda914a1f295bd6e51259a2ff89d -
Trigger Event:
workflow_dispatch
-
Statement type:
