| Name | pysolarfocus JSON |
| Version |
5.1.2
JSON |
| download |
| home_page | None |
| Summary | Unofficial, local Solarfocus client |
| upload_time | 2025-08-15 06:47:20 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | ~=3.11 |
| license | None |
| keywords |
api client
solarfocus
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
[](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 `25.030`.
Supported versions: `21.140` - `25.030`. 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/partnerbereich/ecomanager-touch_modbus-tcp_registerdaten_anleitung1.pdf)).
### 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 1 - 4 (_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: |
| Differential Module 1 - 4 (_Differenzmodul_)| :white_check_mark: |
| Circulation 1 - 4 (_Zirkulation_)| :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_25_030) # select Solarfocus version
solarfocus.connect()
# Fetch the values
solarfocus.update()
# Print the values
print(solarfocus)
print(solarfocus.heating_circuits[0])
```
Output:
```
❯ uv run example.py
--------------------------------------------------
SolarfocusAPI, v5.1.1
--------------------------------------------------
+ System: Vampair
+ Version: 25.030
--------------------------------------------------
============
HeatingCircuit
============
---Input:
supply_temperature | raw:257 scaled:25.700000000000003
room_temperature | raw:224 scaled:22.400000000000002
humidity | raw:480 scaled:48.0
limit_thermostat | raw:1 scaled:1
circulator_pump | raw:0 scaled:0
mixer_valve | raw:0 scaled:0
state | raw:0 scaled:0
---Holding:
target_supply_temperature | raw:0 scaled:0.0
cooling | raw:0 scaled:0
mode | raw:3 scaled:3
target_room_temperature | raw:0 scaled:0.0
indoor_temperature_external | raw:224 scaled:22.4
indoor_humidity_external | raw:480 scaled:48.0
heating_mode | raw:2 scaled:2
============
Boiler
============
---Input:
....
```
### 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_temperature_external.set_unscaled_value(30)
# Write the value to the heating system
solarfocus.heating_circuits[0].indoor_temperature_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
> the Solarfocus versions. See [releases](https://github.com/LavermanJJ/pysolarfocus/releases) for the changelog
> of this library.
#### 25.030
* Add differential modules
* Add circulation
* Add multiple solar modules
* Adapt for changes in registers for heat pump
#### 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": null,
"name": "pysolarfocus",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.11",
"maintainer_email": null,
"keywords": "api client, solarfocus",
"author": null,
"author_email": "Jeroen Laverman <jjlaverman@web.de>",
"download_url": "https://files.pythonhosted.org/packages/26/c6/16af8ce6d397f0432ea4bfb7bc34235d6bfb3131f16a49f4c72cc7114e78/pysolarfocus-5.1.2.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 `25.030`.\n\nSupported versions: `21.140` - `25.030`. 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/partnerbereich/ecomanager-touch_modbus-tcp_registerdaten_anleitung1.pdf)).\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 1 - 4 (_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| Differential Module 1 - 4 (_Differenzmodul_)| :white_check_mark: |\n| Circulation 1 - 4 (_Zirkulation_)| :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_25_030) # 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\u276f uv run example.py\n--------------------------------------------------\nSolarfocusAPI, v5.1.1\n--------------------------------------------------\n+ System: Vampair\n+ Version: 25.030\n--------------------------------------------------\n============\nHeatingCircuit\n============\n---Input:\nsupply_temperature | raw:257 scaled:25.700000000000003\nroom_temperature | raw:224 scaled:22.400000000000002\nhumidity | raw:480 scaled:48.0\nlimit_thermostat | raw:1 scaled:1\ncirculator_pump | raw:0 scaled:0\nmixer_valve | raw:0 scaled:0\nstate | raw:0 scaled:0\n---Holding:\ntarget_supply_temperature | raw:0 scaled:0.0\ncooling | raw:0 scaled:0\nmode | raw:3 scaled:3\ntarget_room_temperature | raw:0 scaled:0.0\nindoor_temperature_external | raw:224 scaled:22.4\nindoor_humidity_external | raw:480 scaled:48.0\nheating_mode | raw:2 scaled:2\n\n\n============\nBoiler\n============\n---Input:\n....\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_temperature_external.set_unscaled_value(30)\n# Write the value to the heating system\nsolarfocus.heating_circuits[0].indoor_temperature_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\n> the Solarfocus versions. See [releases](https://github.com/LavermanJJ/pysolarfocus/releases) for the changelog\n> of this library.\n\n#### 25.030\n* Add differential modules\n* Add circulation\n* Add multiple solar modules\n* Adapt for changes in registers for heat pump\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": null,
"summary": "Unofficial, local Solarfocus client",
"version": "5.1.2",
"project_urls": {
"Homepage": "https://github.com/lavermanjj/pysolarfocus",
"Repository": "https://github.com/lavermanjj/pysolarfocus"
},
"split_keywords": [
"api client",
" solarfocus"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0acf4ca85fa845c56ccfb399881020434dc3c3108d4c17be403469a551290d56",
"md5": "8f7701b5c2d328573059e487db14d850",
"sha256": "1986ecadb9c281c94dc5e850fbec66af7b5fc8ed27ae509547e5513cc6bec5cd"
},
"downloads": -1,
"filename": "pysolarfocus-5.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8f7701b5c2d328573059e487db14d850",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.11",
"size": 25901,
"upload_time": "2025-08-15T06:47:19",
"upload_time_iso_8601": "2025-08-15T06:47:19.706260Z",
"url": "https://files.pythonhosted.org/packages/0a/cf/4ca85fa845c56ccfb399881020434dc3c3108d4c17be403469a551290d56/pysolarfocus-5.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "26c616af8ce6d397f0432ea4bfb7bc34235d6bfb3131f16a49f4c72cc7114e78",
"md5": "ef255f03084de8a59148db34f25c47a2",
"sha256": "ca05583a033fcb0b6e25c73ee763837e3871aedeeae32b190969bfcb6a248d6e"
},
"downloads": -1,
"filename": "pysolarfocus-5.1.2.tar.gz",
"has_sig": false,
"md5_digest": "ef255f03084de8a59148db34f25c47a2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.11",
"size": 720315,
"upload_time": "2025-08-15T06:47:20",
"upload_time_iso_8601": "2025-08-15T06:47:20.679157Z",
"url": "https://files.pythonhosted.org/packages/26/c6/16af8ce6d397f0432ea4bfb7bc34235d6bfb3131f16a49f4c72cc7114e78/pysolarfocus-5.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 06:47:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "lavermanjj",
"github_project": "pysolarfocus",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pysolarfocus"
}
