[](https://img.shields.io/github/v/tag/lavermanjj/pysolarfocus?style=for-the-badge&label=Version&color=orange)
[](https://img.shields.io/github/license/lavermanjj/pysolarfocus?style=for-the-badge)
<p align="center">
<a href="https://github.com/lavermanjj/home-assistant-solarfocus">
<img src="https://brands.home-assistant.io/solarfocus/logo.png" alt="Logo" height="80">
</a>
</p>
<h3 align="center">pysolarfocus</h3>
<p align="center">
Python client for <a href="https://www.solarfocus.com/">Solarfocus</a> eco<sup>manager-touch</sup> via Modbus TCP
</p>
<details open="open">
<summary>Table of Contents</summary>
1. [About](#about)
2. [Supported Solarfocus Software and Hardware](#supported-solarfocus-software-and-hardware)
3. [How To](#how-to)
- [Installation](#installation)
- [Basic Example](#basic-example)
- [Handling multiple components](#handling-multiple-components)
- [Conveniently set modes](#convenitently-set-modes)
- [API-Version specification](#api-version-specification)
4. [Changelog of API-Versions](#changelog-of-api-versions)
</details>
## About
Python client library to interact with heating systems of [Solarfocus](https://www.solarfocus.com/) (eco<sup>_manager-touch_</sup>) via Modbus TCP. This library has been developed for the integration into [Home-Assistant](https://www.home-assistant.io/) via a [custom integration](https://github.com/LavermanJJ/home-assistant-solarfocus), but can be used indepdently.
> **Warning**
> Use with caution, in case of doubt check with Solarfocus or your installer if a feature / functionality (e.g. cooling) is supported by your installation to avoid damages to your heating system or the building.
## Supported Solarfocus Software and Hardware
### Software
> **Important**
> This integration has been tested with Solarfocus eco<sup>manager-touch</sup> version `23.020`.
Supported versions: `21.140` - `23.020`. Features added in later versions are not yet supported.
The eco<sup>manager-touch</sup> Modbus TCP specification can be found [here](https://www.solarfocus.com/de/partnerportal/pdf/open/UGFydG5lcmJlcmVpY2gtREUvUmVnZWx1bmdfZWNvbWFuYWdlci10b3VjaC9BbmxlaXR1bmdlbi9lY29tYW5hZ2VyLXRvdWNoX01vZGJ1cy1UQ1AtUmVnaXN0ZXJkYXRlbl9BbmxlaXR1bmcucGRm/117920/0/Lng_YSxpM245S30zMTc4W2Y8cVRRXWlJVWRQJDsv?serialNumber=21010).
### Hardware
The eco<sup>manager-touch</sup> can integrate the following heating systems
- [Vamp<sup>air</sup>](https://www.solarfocus.com/en/products/air-source-heat-pump-vampair) heat pumps
- [Thermin<sup>nator</sup>](https://www.solarfocus.com/en/products/biomassheating) biomass boilers
- [Ecotop<sup>light</sup> / Ecotop<sup>zero</sup>](https://www.solarfocus.com/de/produkte/biomasseheizung/pelletkessel/ecotop) biomass boilers
- [Octo<sup>plus</sup>](https://www.solarfocus.com/en/products/biomassheating/pellet-boiler/octoplus) biomass boilers
- [Pellet<sup>top</sup>](https://www.solarfocus.com/en/products/biomassheating/pellet-boiler/pellettop) biomass boilers
| Components | Supported |
|---|---|
| Heating Circuit 1 - 8 (_Heizkreis_)| :white_check_mark: |
| Buffer 1 - 4 (_Puffer_) | :white_check_mark: |
| Solar (_Solar_)| :white_check_mark: |
| Boiler 1 - 4 (_Boiler_) | :white_check_mark: |
| Heat Pump (_Wärmepumpe_) | :white_check_mark: |
| Biomass Boiler (_Kessel_) | :white_check_mark: |
| Fresh Water Module 1 - 4 (_Frischwassermodul_) | :white_check_mark: |
## How To
### Installation
```
$ pip3 install pysolarfocus
```
### Basic Example
```python
from pysolarfocus import SolarfocusAPI,Systems,ApiVersions
# Create the Solarfocus API client
solarfocus = SolarfocusAPI(
ip="solarfocus", # adapt IP-Address
system=Systems.VAMPAIR, # for biomass boiler change to Systems.THERMINATOR / ECOTOP
api_version=ApiVersions.V_23_020) # select Solarfocus version
solarfocus.connect()
# Fetch the values
solarfocus.update()
# Print the values
print(solarfocus)
print(solarfocus.heating_circuits[0])
```
Output:
```
--------------------------------------------------
SolarfocusAPI, v3.6.4
--------------------------------------------------
+ API Version: 23.020
+ System: Vampair
+ Components:
+ Heat pump: True
+ Biomass boiler: False
+ Heating circuit: 1
+ Buffer: 1
+ Boiler: 1
+ Fresh water module: 1
+ Solar: False
+ Photovoltaic: False
--------------------------------------------------
============
HeatingCircuit
============
---Input:
supply_temperature| raw:258 scaled:25.8
room_temperature| raw:222 scaled:22.2
humidity| raw:480 scaled:48.0
limit_thermostat| raw:1 scaled:1
circulator_pump| raw:1 scaled:1
mixer_valve| raw:34 scaled:34
state| raw:12 scaled:12
---Holding:
target_supply_temperature | raw:0 scaled:0.0
cooling | raw:0 scaled:0
mode | raw:0 scaled:0
target_room_temperatur | raw:0 scaled:0.0
indoor_temperatur_external | raw:222 scaled:22.2
indoor_humidity_external | raw:480 scaled:48.0
```
### Handling multiple components
Solarfocus systems allow the use of multiple heating circuits, buffers, boilers, and fresh water modules. The api can be configured to interact with multiple components.
```python
# Create the Solarfocus API client with 2 Heating Circuits
solarfocus = SolarfocusAPI(ip="[Your-IP]",heating_circuit_count=2,system=Systems.VAMPAIR)
# Connect to the heating system
solarfocus.connect()
# Update all heating circuits
solarfocus.update_heating()
# Update only the first heating circuit
solarfocus.heating_circuits[0].update()
# Print the first heating circuit
print(solarfocus.heating_circuits[0])
# Set the temperature of the first heating circuit to 30°C
solarfocus.heating_circuits[0].indoor_temperatur_external.set_unscaled_value(30)
# Write the value to the heating system
solarfocus.heating_circuits[0].indoor_temperatur_external.commit()
```
### Convenitently set modes
Control the heating system by setting modes using the provided classes
```python
# Without convenience method
solarfocus.heating_circuits[0].mode.set_unscaled_value(0)
solarfocus.heating_circuits[0].mode.commit()
# RECOMMENDED: Uitilizing convenience methods for modes
solarfocus.set_heating_circuit_mode(0, HeatingCircuitMode.ALWAYS_ON)
```
### API-Version specification
By default, the integration uses API-Version`21.140`. If your system is newer, you can specify
the version by using the `api_version` parameter.
```python
solarfocus = SolarfocusAPI(ip="[Your-IP]", system=Systems.VAMPAIR, api_version=ApiVersions.V_23_020)
```
You can find the API-Version displayed in the header of the screen of your Solarfocus system:
<img src="images/sf-version.png?raw=true" width="500">
## Changelog of API-Versions
> **Note**
> The API-Version of Solarfocus is independent of the versions of this library. Below list refers to to
> the Solarfocus versions. See [releases](https://github.com/LavermanJJ/pysolarfocus/releases) for the changelog
> of this library.
#### 23.020
* Add fresh water module state.
#### 23.010
* Add biomass boiler pellet statistics.
#### 22.090
* Add biomass boiler sweep function control.
* Allow input of external buffer values.
Raw data
{
"_id": null,
"home_page": "https://github.com/lavermanjj/pysolarfocus",
"name": "pysolarfocus",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.11,<4.0",
"maintainer_email": "",
"keywords": "solarfocus,api client",
"author": "Jeroen Laverman",
"author_email": "jjlaverman@web.de",
"download_url": "https://files.pythonhosted.org/packages/de/bb/7503ad37b49aa40226e19ace9fec5c6f61d8a770ebe998a72e8d983e5cf0/pysolarfocus-4.1.0.tar.gz",
"platform": null,
"description": "[](https://img.shields.io/github/v/tag/lavermanjj/pysolarfocus?style=for-the-badge&label=Version&color=orange)\n[](https://img.shields.io/github/license/lavermanjj/pysolarfocus?style=for-the-badge)\n\n\n<p align=\"center\">\n <a href=\"https://github.com/lavermanjj/home-assistant-solarfocus\">\n <img src=\"https://brands.home-assistant.io/solarfocus/logo.png\" alt=\"Logo\" height=\"80\">\n </a>\n</p>\n\n<h3 align=\"center\">pysolarfocus</h3>\n\n<p align=\"center\">\n Python client for <a href=\"https://www.solarfocus.com/\">Solarfocus</a> eco<sup>manager-touch</sup> via Modbus TCP\n</p>\n\n\n<details open=\"open\">\n <summary>Table of Contents</summary>\n\n1. [About](#about)\n2. [Supported Solarfocus Software and Hardware](#supported-solarfocus-software-and-hardware)\n3. [How To](#how-to)\n - [Installation](#installation)\n - [Basic Example](#basic-example)\n - [Handling multiple components](#handling-multiple-components)\n - [Conveniently set modes](#convenitently-set-modes)\n - [API-Version specification](#api-version-specification)\n4. [Changelog of API-Versions](#changelog-of-api-versions)\n\n \n</details>\n\n\n## About\n\nPython client library to interact with heating systems of [Solarfocus](https://www.solarfocus.com/) (eco<sup>_manager-touch_</sup>) via Modbus TCP. This library has been developed for the integration into [Home-Assistant](https://www.home-assistant.io/) via a [custom integration](https://github.com/LavermanJJ/home-assistant-solarfocus), but can be used indepdently.\n\n> **Warning**\n> Use with caution, in case of doubt check with Solarfocus or your installer if a feature / functionality (e.g. cooling) is supported by your installation to avoid damages to your heating system or the building.\n\n\n## Supported Solarfocus Software and Hardware\n\n### Software\n\n> **Important**\n> This integration has been tested with Solarfocus eco<sup>manager-touch</sup> version `23.020`.\n\nSupported versions: `21.140` - `23.020`. Features added in later versions are not yet supported.\n\nThe eco<sup>manager-touch</sup> Modbus TCP specification can be found [here](https://www.solarfocus.com/de/partnerportal/pdf/open/UGFydG5lcmJlcmVpY2gtREUvUmVnZWx1bmdfZWNvbWFuYWdlci10b3VjaC9BbmxlaXR1bmdlbi9lY29tYW5hZ2VyLXRvdWNoX01vZGJ1cy1UQ1AtUmVnaXN0ZXJkYXRlbl9BbmxlaXR1bmcucGRm/117920/0/Lng_YSxpM245S30zMTc4W2Y8cVRRXWlJVWRQJDsv?serialNumber=21010).\n\n### Hardware\n\nThe eco<sup>manager-touch</sup> can integrate the following heating systems\n- [Vamp<sup>air</sup>](https://www.solarfocus.com/en/products/air-source-heat-pump-vampair) heat pumps\n- [Thermin<sup>nator</sup>](https://www.solarfocus.com/en/products/biomassheating) biomass boilers\n- [Ecotop<sup>light</sup> / Ecotop<sup>zero</sup>](https://www.solarfocus.com/de/produkte/biomasseheizung/pelletkessel/ecotop) biomass boilers\n- [Octo<sup>plus</sup>](https://www.solarfocus.com/en/products/biomassheating/pellet-boiler/octoplus) biomass boilers\n- [Pellet<sup>top</sup>](https://www.solarfocus.com/en/products/biomassheating/pellet-boiler/pellettop) biomass boilers\n\n| Components | Supported |\n|---|---|\n| Heating Circuit 1 - 8 (_Heizkreis_)| :white_check_mark: |\n| Buffer 1 - 4 (_Puffer_) | :white_check_mark: |\n| Solar (_Solar_)| :white_check_mark: |\n| Boiler 1 - 4 (_Boiler_) | :white_check_mark: |\n| Heat Pump (_W\u00e4rmepumpe_) | :white_check_mark: |\n| Biomass Boiler (_Kessel_) | :white_check_mark: | \n| Fresh Water Module 1 - 4 (_Frischwassermodul_) | :white_check_mark: |\n\n## How To\n\n### Installation\n\n```\n$ pip3 install pysolarfocus\n```\n\n### Basic Example \n\n```python\nfrom pysolarfocus import SolarfocusAPI,Systems,ApiVersions\n\n# Create the Solarfocus API client\nsolarfocus = SolarfocusAPI(\n ip=\"solarfocus\", # adapt IP-Address \n system=Systems.VAMPAIR, # for biomass boiler change to Systems.THERMINATOR / ECOTOP \n api_version=ApiVersions.V_23_020) # select Solarfocus version\n\nsolarfocus.connect()\n# Fetch the values\nsolarfocus.update()\n\n# Print the values\nprint(solarfocus)\nprint(solarfocus.heating_circuits[0])\n```\n\nOutput: \n\n```\n--------------------------------------------------\nSolarfocusAPI, v3.6.4\n--------------------------------------------------\n+ API Version: 23.020\n+ System: Vampair\n+ Components:\n + Heat pump: True\n + Biomass boiler: False\n + Heating circuit: 1\n + Buffer: 1\n + Boiler: 1\n + Fresh water module: 1\n + Solar: False\n + Photovoltaic: False\n--------------------------------------------------\n\n\n============\nHeatingCircuit\n============\n---Input:\nsupply_temperature| raw:258 scaled:25.8\nroom_temperature| raw:222 scaled:22.2\nhumidity| raw:480 scaled:48.0\nlimit_thermostat| raw:1 scaled:1\ncirculator_pump| raw:1 scaled:1\nmixer_valve| raw:34 scaled:34\nstate| raw:12 scaled:12\n---Holding:\ntarget_supply_temperature | raw:0 scaled:0.0\ncooling | raw:0 scaled:0\nmode | raw:0 scaled:0\ntarget_room_temperatur | raw:0 scaled:0.0\nindoor_temperatur_external | raw:222 scaled:22.2\nindoor_humidity_external | raw:480 scaled:48.0\n```\n\n### Handling multiple components\nSolarfocus systems allow the use of multiple heating circuits, buffers, boilers, and fresh water modules. The api can be configured to interact with multiple components.\n\n```python \n# Create the Solarfocus API client with 2 Heating Circuits\nsolarfocus = SolarfocusAPI(ip=\"[Your-IP]\",heating_circuit_count=2,system=Systems.VAMPAIR)\n# Connect to the heating system\nsolarfocus.connect()\n\n# Update all heating circuits\nsolarfocus.update_heating()\n\n# Update only the first heating circuit\nsolarfocus.heating_circuits[0].update()\n# Print the first heating circuit\nprint(solarfocus.heating_circuits[0])\n\n# Set the temperature of the first heating circuit to 30\u00b0C\nsolarfocus.heating_circuits[0].indoor_temperatur_external.set_unscaled_value(30)\n# Write the value to the heating system\nsolarfocus.heating_circuits[0].indoor_temperatur_external.commit()\n```\n\n### Convenitently set modes\nControl the heating system by setting modes using the provided classes\n\n```python\n# Without convenience method\nsolarfocus.heating_circuits[0].mode.set_unscaled_value(0)\nsolarfocus.heating_circuits[0].mode.commit()\n\n# RECOMMENDED: Uitilizing convenience methods for modes\nsolarfocus.set_heating_circuit_mode(0, HeatingCircuitMode.ALWAYS_ON)\n```\n\n### API-Version specification\nBy default, the integration uses API-Version`21.140`. If your system is newer, you can specify\nthe version by using the `api_version` parameter. \n\n```python\nsolarfocus = SolarfocusAPI(ip=\"[Your-IP]\", system=Systems.VAMPAIR, api_version=ApiVersions.V_23_020)\n```\n\nYou can find the API-Version displayed in the header of the screen of your Solarfocus system:\n\n<img src=\"images/sf-version.png?raw=true\" width=\"500\">\n\n## Changelog of API-Versions\n> **Note**\n> The API-Version of Solarfocus is independent of the versions of this library. Below list refers to to \n> the Solarfocus versions. See [releases](https://github.com/LavermanJJ/pysolarfocus/releases) for the changelog\n> of this library.\n\n\n#### 23.020\n* Add fresh water module state.\n\n#### 23.010\n* Add biomass boiler pellet statistics.\n\n#### 22.090\n* Add biomass boiler sweep function control.\n* Allow input of external buffer values.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Unofficial, local Solarfocus client",
"version": "4.1.0",
"project_urls": {
"Homepage": "https://github.com/lavermanjj/pysolarfocus",
"Repository": "https://github.com/lavermanjj/pysolarfocus"
},
"split_keywords": [
"solarfocus",
"api client"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ad0e02354f153b2c4ca0afb5d0e833148c98be3314bcd5689c8c1d30d176864a",
"md5": "5c45293934b9a83894589cc32e4133b9",
"sha256": "a7243b1862f069e96b4176a7d60f1243861aec70c44e6f289ff1bd7402fb9c27"
},
"downloads": -1,
"filename": "pysolarfocus-4.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5c45293934b9a83894589cc32e4133b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11,<4.0",
"size": 27723,
"upload_time": "2024-02-19T19:47:16",
"upload_time_iso_8601": "2024-02-19T19:47:16.947881Z",
"url": "https://files.pythonhosted.org/packages/ad/0e/02354f153b2c4ca0afb5d0e833148c98be3314bcd5689c8c1d30d176864a/pysolarfocus-4.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "debb7503ad37b49aa40226e19ace9fec5c6f61d8a770ebe998a72e8d983e5cf0",
"md5": "af15ae028f98ff1b897d2f5cbdaeadf6",
"sha256": "1124f1d6c92d8d9ca1f90e7242557dc045bf858a3b6337431ce260f7557ea32b"
},
"downloads": -1,
"filename": "pysolarfocus-4.1.0.tar.gz",
"has_sig": false,
"md5_digest": "af15ae028f98ff1b897d2f5cbdaeadf6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11,<4.0",
"size": 20267,
"upload_time": "2024-02-19T19:47:18",
"upload_time_iso_8601": "2024-02-19T19:47:18.240321Z",
"url": "https://files.pythonhosted.org/packages/de/bb/7503ad37b49aa40226e19ace9fec5c6f61d8a770ebe998a72e8d983e5cf0/pysolarfocus-4.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-19 19:47:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lavermanjj",
"github_project": "pysolarfocus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pysolarfocus"
}
JSON
