pysolarfocus

Python client for Solarfocus eco^{manager-touch} via Modbus TCP

Important

This library is in maintenance mode. Its successor is aiosolarfocus.

aiosolarfocus is the async rewrite: every call is awaited rather than blocking, the register map is validated data rather than branches in component constructors, and it ships py.typed. home-assistant-solarfocus reads through it from version 7.0.0 on, and no longer depends on this library.

The rewrite exists because several defects here are not fixable without it. A register the document grants to one system was read on all of them, and a read spanning an address the firmware does not map comes back compacted rather than padded — so every value after the gap silently lands under the wrong name. That is #61 and #62, and it is why a pellet boiler here reports a return flow temperature of 270 °C where its sensor says 22.1. Fixing it properly means gating every register per system and firmware version, which is the change aiosolarfocus is.

What maintenance mode means: this library keeps working, stays on PyPI, and security fixes still go out. New registers, new firmware versions and the open defects above go to aiosolarfocus instead. If you are starting something new, start there; if you depend on this one, migrating is the path forward.

Table of Contents

1. About
2. Supported Solarfocus Software and Hardware
3. How To
   • Installation
   • Basic Example
   • Handling multiple components
   • Conveniently set modes
   • API-Version specification
4. Changelog of API-Versions

About

Python client library to interact with heating systems of Solarfocus (eco^{manager-touch}) via Modbus TCP. This library has been developed for the integration into Home-Assistant via a custom integration, but can be used indepdently. That integration moved to aiosolarfocus in its 7.0.0 release, and this library is in maintenance mode — see the notice at the top.

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^{manager-touch} version 25.030.

Supported versions: 21.140 - 26.020. Features added in later versions are not yet supported.

The eco^{manager-touch} Modbus TCP specification can be found here).

Hardware

The eco^{manager-touch} can integrate the following heating systems

• Vamp^air heat pumps
• Thermin^nator biomass boilers
• Ecotop^light / Ecotop^zero biomass boilers
• Octo^plus biomass boilers
• Pellet^top biomass boilers

Components	Supported
Heating Circuit 1 - 8 (Heizkreis)	✅
Buffer 1 - 4 (Puffer)	✅
Solar 1 - 4 (Solar)	✅
Boiler 1 - 4 (Boiler)	✅
Heat Pump (Wärmepumpe)	✅
Biomass Boiler (Kessel)	✅
Fresh Water Module 1 - 4 (Frischwassermodul)	✅
Differential Module 1 - 4 (Differenzmodul)	✅
Circulation 1 - 4 (Zirkulation)	✅

How To

Installation

$ pip3 install pysolarfocus

Basic Example

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.

# 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

# 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-Version21.140. If your system is newer, you can specify the version by using the api_version parameter.

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:

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 for the changelog of this library.

26.020

• Add HEMS target electrical power for the PV overcharge (photovoltaic.hems_target_electrical_power, register 33415).

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.