pykoplenti 1.5.0rc1

Python REST-Client for Kostal Plenticore Solar Inverters

Python Library for Accessing Kostal Plenticore Inverters

This repository provides a python library and command line interface for the REST-API of Kostal Plenticore Solar Inverter.

This library is not affiliated with Kostal and is no offical product. It uses the interfaces of the inverter like other libs (eg. https://github.com/kilianknoll/kostal-RESTAPI) and uses information from their swagger documentation (ip-addr/api/v1/).

Features

• Authenticate
• Read/Write settings
• Read process data
• Read events
• Download of log data
• Full async-Support for reading and writing data
• Commandline interface for shell access
• Dynamic data model - adapts automatically to new process data or settings
• Virtual Process Data values

Getting Started

Prerequisites

You will need Python >=3.9.

Installing the library

Packages of this library are released on PyPI and can be installed with pip. Alternatively the packages can also be downloaded from GitHub.

I recommend to use a virtual environment for this, because it installs the dependecies independently from the system. The installed CLI tools can then be called without activating the virtual environment it.

# Install with command line support
$ pip install pykoplenti[cli]

# Install without command line support (library only)
$ pip install pykoplenti

Using the command line interface

After installing with CLI support, you can use the command:

$ pykoplenti --help
Usage: python -m pykoplenti.cli [OPTIONS] COMMAND [ARGS]...

  Handling of global arguments with click

Options:
  --host TEXT           Hostname or IP of the inverter
  --port INTEGER        Port of the inverter  [default: 80]
  --password TEXT       Password or master key (also device id)
  --service-code TEXT   service code for installer access
  --password-file FILE  Path to password file - deprecated, use --credentials
                        [default: secrets]
  --credentials FILE    Path to the credentials file. This has a simple ini-
                        format without sections. For user access, use the
                        'password'. For installer access, use the 'master-key'
                        and 'service-key'.
  --help                Show this message and exit.

Commands:
  all-processdata   Returns a list of all available process data.
  all-settings      Returns the ids of all settings.
  download-log      Download the log data from the inverter to a file.
  read-events       Returns the last events
  read-processdata  Returns the values of the given process data.
  read-settings     Read the value of the given settings.
  repl              Provides a simple REPL for executing API requests to...
  write-settings    Write the values of the given settings.

Visit Command Line Help for example usage.

Using the library from python

The library is fully async, there for you need an async loop and an async ClientSession. Please refer to the example directory for full code.

Import the client module:

from pykoplenti import ApiClient

To communicate with the inverter you need to instantiate the client:

# session is a aiohttp ClientSession
client = ApiClient(session, '192.168.1.100')

Login to gain full access to process data and settings:

await client.login(passwd)

Now you can access the API. For example to read process data values:

data = await client.get_process_data_values('devices:local', ['Inverter:State', 'Home_P'])

device_local = data['devices:local']
inverter_state = device_local['Inverter:State']
home_p = device_local['Home_P']

See the full example here: read_process_data.py.

If you should need installer access use the master key (printed on a label at the side of the inverter) and additionally pass your service code:

await client.login(my_master_key, service_code=my_service_code)

Documentation

• Command Line Interface
• Examples
• Virtual Process Data
• Notes about Process Data

Built With

• AIOHTTPO - asyncio for HTTP
• click - command line interface framework
• black - Python code formatter
• ruff - Python linter
• pydantic - Data validation library
• pytest - Python test framework
• mypy - Python type checker
• hatchling - Modern Python build backend
• tox - Automate testing

License

apache-2.0

Acknowledgments

• kilianknoll for the kostal-RESTAPI project