Metadata-Version: 2.1
Name: pykoplenti
Version: 1.2.2
Summary: Python REST-Client for Kostal Plenticore Solar Inverters
Home-page: https://github.com/stegm/pyclient_koplenti
Author: @stegm
Project-URL: repository, https://github.com/stegm/pyclient_koplenti
Project-URL: changelog, https://github.com/stegm/pykoplenti/blob/master/CHANGELOG.md
Project-URL: issues, https://github.com/stegm/pykoplenti/issues
Keywords: rest kostal plenticore solar
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Topic :: Software Development :: Libraries
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp~=3.8
Requires-Dist: pycryptodome~=3.19
Requires-Dist: pydantic~=1.10
Provides-Extra: cli
Requires-Dist: prompt_toolkit>=3.0; extra == "cli"
Requires-Dist: click>=7.1; extra == "cli"

# 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/).

![CI](https://github.com/stegm/pykoplenti/workflows/CI/badge.svg)

## Features

- Authenticate
- Read/Write settings
- Read process data
- Read events
- Download of log data
- Full async-Support for reading and writing data
- [Commandline interface](doc/command_line.md) for shell access
- Dynamic data model - adapts automatically to new process data or settings
- [Virtual Process Data](doc/virtual_process_data.md) values

## Getting Started

### Prerequisites

You will need Python >=3.7.

### Installing the library

Packages of this library are released on [PyPI](https://pypi.org/project/kostal-plenticore/) and can be
installed with `pip`. Alternatively the packages can also be downloaded from
[GitHub](https://github.com/stegm/pykoplenti/releases/).

I recommend to use a [virtual environment](https://docs.python.org/3/library/venv.html) 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.

```shell
# Install with command line support
$ pip install pykoplenti[CLI]

# Install without command line support
$ pip install pykoplenti
```

### Using the command line interface

Installing the libray with `CLI` provides a new command.

```shell
$ pykoplenti --help
Usage: pykoplenti [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       the password
  --password-file TEXT  password file (default "secrets" in the current
                        working directory)

  --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.
  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](doc/command_line.md) 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:

```python
from pykoplenti import ApiClient
```

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

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

Login to gain full access to process data and settings:

```python
await client.login(passwd)
```

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

```python
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](examples/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:

```python
await client.login(my_master_key, service_code=my_service_code)
```

## Documentation

- [Command Line Interface](doc/command_line.md)
- [Examples](examples/)
- [Virtual Process Data](doc/virtual_process_data.md)
- [Notes about Process Data](doc/process_data.md)

## Built With

- [AIOHTTPO](https://docs.aiohttp.org/en/stable/) - asyncio for HTTP
- [click](https://click.palletsprojects.com/) - command line interface framework
- [black](https://github.com/psf/black) - Python code formatter
- [ruff](https://github.com/astral-sh/ruff) - Python linter
- [pytest](https://docs.pytest.org/) - Python test framework
- [mypy](https://mypy-lang.org/) - Python type checker
- [setuptools](https://github.com/pypa/setuptools) - Python packager

## License

apache-2.0

## Acknowledgments

- [kilianknoll](https://github.com/kilianknoll) for the kostal-RESTAPI project
