Continuing the discussion from Controme Smart-Heat:
Controme Smart Heat Setup for openHAB 5
My last post was approximately eight years ago. Recently, I set up a new system in a new house and once again chose Controme as an excellent smart control system for my heating.
As time has moved on, I am now using openHAB 5 and its UI to configure my system. This guide describes, step by step, how to integrate Controme temperature data into openHAB using the HTTP Binding.
It covers reading actual (IST) temperatures, reading and setting target (SOLL) temperatures, and preparing the data for use in the openHAB UI and Apple Home (HomeKit).
At the end of this guide, indications are also provided on how to integrate valve status information as well as return temperatures from the underfloor heating system.
1. Prerequisites
- Controme system with API access enabled
- openHAB with HTTP Binding installed
- Username and password for Controme
API documentation: API – Controme Support Center
2. GET actual Temperatures (Ist-Temperaturen)
2.2 HTTP-Thing anlegen
Create an HTTP Thing:
Settings → Things → + → HTTP Binding → HTTP URL Thing
Configuration:
- Label: Controme IST Temperatures
- Base URL: http://[Controme-IP]/get/json/v1/1/temps/
- Authentication Mode: BASIC
- Username / Password: your Controme credentials
- Ignore SSL Errors: true
- State Method: GET
- Refresh Interval: 30 seconds
- Timeout: 3000 ms
UID: http:url:6f66d1678a
label: Controme IST Temperaturen
thingTypeUID: http:url
configuration:
authMode: BASIC
ignoreSSLErrors: true
baseURL: http://xxx.xxx.xxx.xx/
password: [password|
delay: 0
stateMethod: GET
refresh: 30
commandMethod: POST
contentType: application/json
timeout: 3000
bufferSize: 2048
username: [username]
location: Hausanschlussraum
channels:
- id: last-failure
channelTypeUID: http:request-date-time
label: Last Failure
configuration: {}
- id: last-success
channelTypeUID: http:request-date-time
label: Last Success
configuration: {}
- id: ContromeIstTemperaturen
channelTypeUID: http:string
label: Controme Ist Temperaturen
description: ""
configuration:
mode: READONLY
stateExtension: get/json/v1/1/temps/
- id: ContromeIstTemperaturenSoll
channelTypeUID: http:string
label: Controme Ist Temperaturen Soll
description: ""
configuration:
mode: READONLY
stateExtension: get/json/v1/1/temps/
- id: ContromeIstZustandHeizkreiseOH
channelTypeUID: http:string
label: Controme Ist Zustand Heizkreise OG
description: ""
configuration:
mode: READONLY
stateExtension: get/[mac-adresse-gateway]/all/
- id: ContromeIstZustandHeizkreiseEG
channelTypeUID: http:string
label: Controme Ist Zustand Heizkreise EG
description: ""
configuration:
mode: READONLY
stateExtension: get/[mac-adresse-gateway]/all/
2.2 Create a channel for the actual temperature (one for all …)
Im Thing → Channels → Add Channel
Channel basic data:
- Channel ID: Controme_Ist_Temperaturen
- Label: Controme Ist Temperaturen
Channel configuration:
- Mode: READONLY
2.3 Items for actual temperature (Ist-Temperatur)
Path: Settings → Items → + → Add Link to Item
Item data:
- Name: Wohnzimmer_Temperatur_Ist
- Label: Wohnzimmer Temperatur [%.1f %unit%]
- Type: Number:Temperature
- Unit: °C
- Icon: temperature
Semantik:
- Location: Wohnzimmer
- Point: Measurement
- Property: Temperature
Channel-Link:
- Thing: Controme IST Temperaturen
- Channel: Controme Ist Temperaturen
Profil:
- Profil: JSONPATH
- Expression:
$\[?(@.etagenname=='EG')\].raeume\[?(@.name=='Wohnzimmer')\].temperatue
Use the same room name as provided in the information data from controme - ( http://[Controme-IP]/get/json/v1/1/temps/) → place e.g. in your browser to find out.
Metadata:
- AppleHomeKit: Thermostat.CurrentTemperature
3 GET operational mode (Betriebsart)
Path: Settings → Items → + → Add Link to Item
So that the HomeKit app can control the heating system from Controme via openHAB, the operating modes must be read out and created as an item (below the Thing “Controme Actual Temperatures” and below the Channel “Controme Actual Temperatures”):
3.1. Create item for actual operating mode Heat (Betriebsart IST)
Path: Settings → Items → + → Add Link to Item
Item data:
- Name: Controme_OperatingMode_Heat
- Label: Controme Operating Mode Heat
- Type: String
- Icon: temperature_hot
Semantics:
- Point: Status
- Property: Temperature
Channel link:
- Thing: Controme Actual Temperatures
- Channel: Controme Actual Temperatures
Profile:
- Profile: JSONPATH
- Expression:
$[?(@.etagenname=='EG')].raeume[?(@.name==Wohnzimmer)].betriebsart
Here, the room name must be selected according to the information from Controme (see basics above).
Parent groups:
- All rooms in which a thermostat is installed
Metadaten:
- AppleHomeKit: Thermostat.TargetHeatingCoolingMode
- Auf die “transformation” der Zustände achten!
Repeat the same steps for the target operating mode as well!!
4. GET target temperatures (Soll-Temperaturen)
So that the HomeKit app can control the heating system from Controme via openHAB, the configured target temperatures must be read and created as a channel (below the Thing “Controme Actual Temperatures”):
4.1. Create a channel for the configured target temperature (one for all)
In Thing → Channels → Add Channel
Channel basic data:
- Channel ID: Controme_Ist_Temperaturen_Soll
- Label: Controme Actual Temperatures Target
Channel configuration:
- Mode: READONLY
4.2. Create items for target temperature
Path: Settings → Items → + → Add Link to Item
Item data:
- Name: Controme Actual Temperatures Target Living Room
- Label: Heating Living Room Temperature [%.1f %unit%]
- Type: Number:Temperature
- Unit: °C
- Icon: temperature
Semantics:
- Location: Heating Living Room
- Point: Measurement
- Property: Temperature
Channel link:
- Thing: Controme Actual Temperatures
- Channel: Controme Actual Temperatures Target
Profile:
- Profile: JSONPATH
- Expression:
$[?(@.etagenname=='EG')].raeume[?(@.name=='Wohnzimmer')].solltemperatur
Here, the room name must be selected according to the information from Controme (see basics above).
5. SET target temperatures (POST command)
5.1 Create an HTTP Thing
Path: Settings → Things → + → HTTP Binding → HTTP URL Thing
Thing configuration:
- Label: Controme TARGET Temperatures
- Base URL: http://[Controme IP address]/ (the rest will follow later)
- Auth Mode: BASIC
- Username: [username]
- Password: [password]
- Ignore SSL Errors: true
- State Method: GET
- Command Method: POST
- Refresh: 20
- Timeout: 3000
- Header: Content-Type=application/x-www-form-urlencoded
5.2 Create a channel for target temperature (per room!)
In Thing → Channels → Add Channel
Channel basic data:
- Channel ID: Temperatur_Soll_Wohnzimmer
(a separate channel is required for each room) - Label: Target Temperature Living Room
Channel configuration:
- Mode: WRITEONLY
- CommandExtension:
set/json/v1/1/soll/9/
(the “9” here is the room number “id” according to the initial setup described above) - CommandTransformation:
JINJA(user=[user]&password=[password]&soll={{ '%.1f'|format(value|float) }})
(user and password according to the credentials for the Controme server)
5.3. Create an item for target temperature
Path: Settings → Items → + → Add Link to Item
Item data:
- Name: Target_Temperature_Living_Room
- Label: Target Temperature Living Room [%.1f %unit%]
- Type: Number:Temperature
- Dimension: Temperature
- Unit: °C
- Icon: temperature
Semantics:
- Location: Living Room
- Point: Setpoint
- Property: Temperature
Channel link:
- Thing: Controme Target Temperatures
- Channel: Target Temperature Living Room
Metadaten:
- AppleHomeKit: Thermostat.TargetTemperture
UID: http:url:ab05a7b4c1
label: Controme SOLL Temperaturen
thingTypeUID: http:url
configuration:
authMode: BASIC
headers:
- Content-Type=application/x-www-form-urlencoded
ignoreSSLErrors: false
baseURL: http://xxx.xxx.xxx.xx/
password: [password]
delay: 0
stateMethod: GET
refresh: 30
commandMethod: POST
timeout: 3000
bufferSize: 2048
username: [username|
location: Hausanschlussraum
channels:
- id: last-failure
channelTypeUID: http:request-date-time
label: Last Failure
configuration: {}
- id: last-success
channelTypeUID: http:request-date-time
label: Last Success
configuration: {}
- id: Temperatur_Soll_Wohnzimmer
channelTypeUID: http:number
label: Temperatur Soll Wohnzimmer
description: ""
configuration:
mode: WRITEONLY
commandExtension: set/json/v1/1/soll/9/
commandTransformation:
- JINJA(user=[user]&password=[password]&soll={{
'%.1f'|format(value|float) }})
6. Rule for updating the actual and target temperatures in the displays
To keep the displayed target temperatures always up to date (for example, when a setting is changed directly on the thermostat or in another app), the configured value must be regularly read and written back using the following rule:
DSL Script in rule:
if (Controme_Ist_Temperaturen_Soll_Wohnzimmer.state == NULL || Controme_Ist_Temperaturen_Soll_Wohnzimmer == UNDEF) return;
Soll_Temperatur_Wohnzimmer.postUpdate(Controme_Ist_Temperaturen_Soll_Wohnzimmer.state);
8. Optional: Apple Home (HomeKit)
Create an equipment item under the room in which the thermostat is located:
Item data:
- Name: Heating_Living_Room
- Label: Heating Living Room
- Type: Group
- Icon: temperature
Semantik:
- Location: Wohnzimmer → Parent Group.
- Semantic Equipment: HVAC-Thermostat
I hope my explanation helps sombody. In case there is need to have input regarding the return temperatures and/or the valve setting feel free to contact me.