kaco-modbus
Read and control KACO solar inverters over SunSpec Modbus.
Built on modbus-connection.
The library never opens a connection of its own: you hand it a ModbusUnit and keep
ownership of the socket. It contains no Home Assistant imports.
Developed against a KACO blueplanet 8.6 TL3 INT (firmware V5.53). It is driven by SunSpec discovery rather than a fixed register map, so it should work with any KACO inverter that exposes SunSpec over Modbus TCP — KACO's whole current range is three-phase, which is what this targets. Older Powador units that speak KACO's proprietary RS485 ASCII protocol are not supported; that is a different protocol.
Install
pip install kaco-modbus
You also need a Modbus backend, chosen by you rather than by this library:
pip install "modbus-connection[tmodbus]" # or [pymodbus]
Use
import asyncio
from modbus_connection import ModbusTcpParams
from modbus_connection.tmodbus import ModbusConnection
from kaco_modbus import KacoInverter
async def main() -> None:
connection = ModbusConnection(ModbusTcpParams(host="192.168.0.155"))
try:
inverter = KacoInverter(connection.for_unit(1))
await inverter.async_update()
print(inverter.info.model, inverter.info.serial_number)
print(inverter.inverter.w, "W") # AC power, scale factor applied
for string in inverter.strings:
print(string.id_str, string.dcw, "W") # per MPPT string
finally:
await connection.close()
asyncio.run(main())
async_update() establishes first that the device really is a KACO, raising
NotAKacoInverterError if not. SunSpec is a shared specification, so another
vendor's inverter answers the same models at the same addresses — but
everything this library knows beyond the bare register map is KACO-specific
(see docs/quirks.md), and applied elsewhere it would report
plausible nonsense rather than fail outright. The check is SunSpec model 1's
manufacturer, matched as a prefix.
Command line
pip install "kaco-modbus[cli]"
Two tools, for two different readers.
kaco-status — what the inverter is doing
kaco-status 192.168.0.155
kaco-status 192.168.0.155 --watch # live, refreshing every 5 s
Plain language, real units, and a judgement on each grid reading. No SunSpec
vocabulary: the operating state reads "Producing power", not MPPT.
╭────────────────────── blueplanet 8.6 TL3 INT ───────────────────────╮
│ ● Producing power KACO new energy · 8.60 kW rated│
│ │
│ 1.18 kW ████░░░░░░░░░░░░░░░░░░░░░░ 14% of capacity │
│ │
│ ╭─────── Solar panels ────────╮ ╭────────── Grid ──────────╮ │
│ │ String Voltage Power │ │ Phase 1 230.1 V normal│ │
│ │ String 1 344 V 270 W │ │ Frequency 50.07 Hz normal │
│ │ String 2 537 V 460 W │ │ Power factor 1.00 │ │
│ ╰─────────────────────────────╯ ╰──────────────────────────╯ │
│ │
│ Generated all-time Conversion efficiency Temperature │
│ 12.19 MWh 98.0% 46 °C │
╰──────────────── 8.6TL00000000 · firmware V5.53 ─────────────────────╯
It withholds numbers it cannot stand behind. Conversion efficiency is blank below 1 kW, because the inverter reports power in 10 W steps and the rounding would show a false 100 %.
kaco-query — every register, for developers
kaco-query 192.168.0.155
kaco-query 192.168.0.155 --raw # plus an undecoded register dump
Prints the discovered SunSpec model chain and every decoded field under its real
SunSpec name, with — for the ones this firmware does not implement.
kaco-limit — supervised power limit tests
kaco-limit 192.168.0.155 show
kaco-limit 192.168.0.155 set 50 --revert 300 --watch 420 --yes-write-to-inverter
kaco-limit 192.168.0.155 resend --revert 300 --yes-write-to-inverter
kaco-limit 192.168.0.155 clear --yes-write-to-inverter
Writes to the inverter's grid control (see Control), for checking on hardware
what the setters do. Nothing is sent without --yes-write-to-inverter, and an inverter
that ignores the writes is reported.
At night
A KACO stays on Modbus after dark rather than going silent, but parks the readings it is no longer taking at zero — reporting 0 Hz and 0 V for a grid that is plainly still live. The device object withholds those rather than passing them on:
inverter.is_running # False while asleep
inverter.frequency # None unless running
inverter.phase_voltages # (None, None, None) unless running
inverter.temperature # None unless running
inverter.power_factor # None unless running
Power, current and energy are not withheld — zero is genuinely correct for those.
See docs/quirks.md.
Control
Writes are limited to SunSpec model 123 (immediate controls):
await inverter.async_set_power_limit(50.0, revert_seconds=3600) # curtail to 50 % for an hour
await inverter.async_resend_power_limit(3600) # still in force? send it again
await inverter.async_clear_power_limit()
The inverter drops a power limit revert_seconds after it was last written, and only a
write restarts that period, so a caller keeping a limit has to keep resending it. A limit
cannot be held without resending: the firmware refuses a period of 0.
Writing needs Modbus TCP Schreibzugriff (write access) enabled in the inverter's web
interface. With it off, the inverter acknowledges every write and ignores it, which the
setters report as SetpointRejectedError. See docs/quirks.md.
License
Apache-2.0
Metadata
Release files for kaco-modbus 2.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kaco_modbus-2.0.0.tar.gz | 94.2 kB | With provenance | Details for kaco_modbus-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kaco_modbus-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for kaco_modbus-2.0.0-py3-none-any.whl |
Total release size: 135.2 kB
Release files / kaco_modbus-2.0.0.tar.gz
| Download URL | kaco_modbus-2.0.0.tar.gz |
|---|---|
| Size | 94.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
12728b019c2dae9c24068646251aaa9d918d24c5c33e8396a199c7aa4618a906
|
|
BLAKE2b-256 checksum How to use checksums |
d8a3e9cadd1ba1f2d7b12fc2920af1b36a69f91084ce3a10c0da39b61edb2a4e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logRelease files / kaco_modbus-2.0.0-py3-none-any.whl
| Download URL | kaco_modbus-2.0.0-py3-none-any.whl |
|---|---|
| Size | 41.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
11bc4e2d1bb71fdc0d1b47853a2f83e268db8f42f2eea306655db26db07d8c23
|
|
BLAKE2b-256 checksum How to use checksums |
45b3a39306b68ac99ebe5034719fa9ff1fba371caa3afea0c86a5775ba014ef9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logSecurity for kaco-modbus 2.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for kaco_modbus-2.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.