Skip to main content

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)

Source distribution for kaco-modbus 2.0.0
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)

Table of built distributions (wheels) for kaco-modbus 2.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page