Contents
- 1 Heizungssteuerung API
- 1.1 Allgemeine Beschreibung
- 1.2 get-Methoden
- 1.3 set-Methoden
- 1.4 PHP-Script Beispiele
- 1.5 Implementierungsbeispiel in OpenHab
- 1.6 Hinweise zur Controme API
- 1.7 Problembehebung
Heizungssteuerung API
Controme ermöglicht die Steuerung und das Abfragen von Temperaturen über einfache http-Befehle. Mit der API können mit einfachen http-Befehlen Informationen abgerufen und Einstellungen vorgenommen werden. Die Kommunikation erfolgt über den Controme Quad-Core Miniserver.
Ein kleines Tool zur Implementierung in Open Hab finden Sie hier.
Zum testen und zum Verständnis der Funktionsweise der API verwenden Sie am besten das kostenlose Programm Postman: https://www.getpostman.com/
Sofern Controme an einen KNX-Server angebunden werden soll, kann dieser nach entsprechender Einrichtung per http-Befehl sowohl Solltemperaturen an Controme schicken, als auch Soll- und Ist-Temperaturen von Controme abfragen.
Allgemeine Beschreibung
Hinweis: Die Controme-API wird auf Anfrage auf Ihrem lokalen Controme-Server freigeschalten. Bitte senden Sie uns hierzu eine Email mit der Mac-Adresse ihres Controme-Servers an support@controme.com
Adressformat:
/get/json/v1/[HAUSID]/[
und
/set/json/v1/[HAUSID]/[
wobei [DATA] je nach Methode optional ist.
Die Methoden sind:
get-Methoden
get-deviation
Enthält
- Raumname („name)
- Temperaturdifferenz Isttemperatur zu Zieltemperatur („deviation“)
Deviation-Wert ist negativ, wenn der Raum zu kalt ist. Deviation-Wert ist positiv, wenn der Raum zu warm ist.
ACHTUNG: Dieser Endpunkt funktioniert nur, wenn das Plugin „Vorlauftemperaturkorrektur“ aktiviert ist.
URL:
…/get/json/v1/1/deviation/
…/get/json/v1/1/deviation/11/
„11“ ist in o.g. Beispiel die Raumnummer.
Beispiel:
get-fps
Enthält
- Name („name“)
- Wert („value“)
URL:
…/get/json/v1/1/fps/
…/get/json/v1/1/fps/3
„3“ ist in o.g. Beispiel die Nummer der Regelung (zu finden in der URL). Wird die Nummer freigelassen, werden alle angelegten Regelungen abgefragt.
get-heizprogramm
Enthält
- Schaltzeitpunkte des Heizprogramms
- Temperaturszenen, die beim jeweiligen Schaltzeitpunkt aktiviert werden.
URL:
…/get/json/v1/1/heizprogramm/
Beispiel:
get-Kalender
Enthält
- aktuell aktive und kommende Einträge im Modul Kalender (Jahreskalender)
- Nächste Start-Zeit
- Nächste End-Zeit
- Raumnamen
- Offset
- Eintrag-ID
URL:
…/get/json/v1/1/jahreskalender/
Beispiel:
get-rooms
Enthält alle Räume mit jeweils:
- Etagenname
- Raum-ID
- Icon-Name
URL:
…/get/json/v1/1/rooms/
Beispiel:
# [
# {
# „id“: etage.id
# „etagenname“: etage.name,
# „raeume: [
# {
# „id“: raum.id
# „name“: raum.name,
# „icon“: raum.icon
# },
# …
# ]
# },
# …
# ]
get-roomoffsets
Enthält:
- Modulname
- aktiver Offset
- Raum- oder Hausoffset
- Raum-ID
- Raumname
URL:
…/get/json/v1/1/roomoffsets/3
Beispiel:
+ /get/…/roomoffsets/[RAUMID]/
# [
# {
# „id“: etage.id,
# „name“: raum.name,
# „offsets“: offsets
# }
# ]
+ /get/…/rltemps/[RAUMID]/
# [
# {
# „id“: sensor.id,
# „name“: sensor.name,
# „beschreibung“: sensor.description,
# „wert“: last_val or null,
# „letzte_uebertragung“: last_ts or null,
# „ausgang“: last_out or null
# },
# …
# ]
+ /get/…/outs/
# [
# {
# „id“: etage.id
# „etagenname“: etage.name,
# „raeume“: [
# {
# „id“: raum.id
# „name“: raum.name,
# „ausgang“: {
# „[[nummer]]“: 1/0,
# …
# }
# },
# …
# ]
# },
# …
# ]
get-outputs
Enthält:
- Ausgangsstati 0/1 jedes Relais von FBH-Gateways und Mini-Gateways
- Reihenfolge 1-15 entsprechend der Ausgangsnummerierung
URL:
…/get/MacAdresse/all
Beispiel:
<0;0;0;0;0;0;0;0;0;0;0;0;0;0;1>
get-tempforecast
Enthält:
- Nächsten Schaltzeitpunkt aller Temperaturszenen
- Zugeordnete Solltemperaturen aller Räume für alle Temperaturszenen
- Relative Zeit bis zum Schaltzeitpunkt der jeweiligen Temperaturszene
URL:
…/get/MacAdresse/tempforecast/
Beispiel:
get-temps
Enthält alle Räume mit jeweils:
- Etagenname
- Raum-ID
- Summe der Modul-Offsets
- Solltemperatur
- Isttemperatur
- Luftfeuchte
- Raumname
- Alle Module inkl. aktueller Offsets
- Sensortypen
- Letzter Übertragungszeitpunkt je Sensor
- Sensor-ID
- Sensorwert
- Sensor-Beschreibung
URL:
…/get/json/v1/1/temps
Beispiel:
# [
# {
# „id“: etage.id,
# „etagenname“: etage.name,
# „raeume“: [
# {
# „id“: raum.id
# „name“: raum.name,
# „solltemperatur“: raum.solltemp,
# „total_offset“: total_offset,
# „offsets“: offsets,
# „temperatur“: last,
# „sensoren“: [
# {
# „name“: sensor.name,
# „beschreibung“: sensor.description,
# „wert“: last_val,
# „letzte_uebertragung“: last_ts,
# „raumtemperatursensor“: true/false
# },
# …
# ]
# },
# …
# ]
# },
# …
# ]
get-temperaturszenen
Enthält alle angelegten Temperaturszenen, aktiv ja/nein, die zugehörigen Räume, Raumnamen und Temperaturen.
URL:
…/get/json/v1/1/temperaturszenen/
Beispiel:
get-timer
Enthält
- aktuell aktive und kommende Einträge im Modul Timer
- Nächste Start-Zeit
- Nächste End-Zeit
- Raumnamen
- Offset
URL:
…/get/json/v1/1/timer/
Beispiel:
get-upcoming offsets
Enthält
- in der Zukunft eintretende geplante Offsets von Jahreskalender
- in der Zukunft eintretende geplante Offsets von Timer
- in der Zukunft eintretende geplante Solltemperaturänderungen von Heizprogramm
URL:
…/get/json/v1/1/upcomingoffsets/
Beispiel:
get-vtr
Enthält
- Name („name“)
- Vorlauftemperatur („ist“)
- Vorlauf-Solltemperatur („soll“)
- Vorlauf-Offset („offset“)
- Vorlauf-Zieltemperatur („ziel“
- Temperatur Mischereingang („eingang“)
- Außentemperatur („AT“)
- Fehlermeldung („fehler“)
- Mischerposition (position“)
- Rücklauftemperatur („ruecklauf“)
URL:
…/get/json/v1/1/vtr/
…/get/json/v1/1/vtr/3
„3“ ist in o.g. Beispiel die Nummer der Regelung (zu finden in der URL). Wird die Nummer freigelassen, werden alle angelegten Regelungen abgefragt.
Beispiel:
get-wetter-pro
Enthält
- Name
- Wert
URL:
…/get/json/v1/1/wetter_pro/
…/get/json/v1/1/wetter_pro/3
„3“ ist in o.g. Beispiel die Nummer der Regelung (zu finden in der URL). Wird die Nummer freigelassen, werden alle angelegten Regelungen abgefragt.
Beispiel:
set-Methoden
Die /set/ Aufrufe haben POST als HTTP Methode. In den POST Daten muss immer “user” und “password” mit Ihren Logindaten enthalten sein. Da wir auf dem Miniserver keine Zertifikate installiert haben, wäre es sinnvoll, wenn Sie /set/ Aufrufe nur im lokalen Netz abschicken. Wenn der Benutzer nicht authentifiziert werden kann, wird ein Statuscode 403 zurückgegeben.
set-soll
+ /set/…/soll/[RAUMID]/
Setzt die Solltemperatur im Raum. POST enthält zusätzlich “soll” mit einer Dezimalzahl als Wert.
URL:
…/set/json/v1/1/soll/3/
Methode:
- POST
Body:
- user
- password
- soll
Beispiel:
set-ziel
+ /set/…/ziel/[RAUMID]/
Setzt die Zieltemperatur im Raum. POST enthält zusätzlich “ziel” mit einer Dezimalzahl als Wert UND „duration“ mit einer Zeitangabe in Minuten als Wert. Als „duration“ kann auch „default“ als Wert angegeben werden.
URL:
…/set/json/v1/1/ziel/3/
Methode:
- POST
Body:
- user
- password
- ziel
- duration
Beispiel:
set-temperaturszenen
Aktiviert Temperaturszenen. POST enthält zusätzlich OPTIONAL “duration” mit einer Zeitangabe in Minuten als Wert. Als „duration“ kann auch „default“ als Wert angegeben werden. In diesem Fall wird die Temperaturszene temporär für die angegebene Zeit aktiviert und fixiert. Fehlt „duration“, wird die Temperaturszene dauerhaft aktiviert und bleibt bis zum nächsten manuellen switch oder bis zum nächsten switch des Heizprogramms.
URL:
…/set/json/v1/1/temperaturszenen/4/
Methode:
- POST
Body:
- user
- password
- duration (optional)
Beispiel:
set-default-duration
Setzt die Default-duration, die für temporäre Befehle über die API verwendet wird und für die automatisch vorgeschlagene Zeitdauer im Quick-UI.
URL:
…/set/json/v1/1/quickui/
Methode:
- POST
Body:
- user
- password
- duration
Beispiel:
set-roomoffset
+ /set/…/roomoffset/[RAUMID]/
Legt ein Modul für einen Raum an mit einem gegebenen Namen und Offset. Das Modul speichert übergebene Werte nur im Cache mit einer Lebenszeit von 10 Minuten. Die Werte müssen also ggf. regelmäßig erneuert werden. POST enthält zusätzlich “offset” (eine Dezimalzahl) und “offset_name” (ein String).
set-houseoffset
+ /set/…/houseoffset/
PHP-Script Beispiele
Lesen von Temperaturen
Where $argv[1] is the sensor name you have been configured in the Controme set-up. It will be later defined in the .item file.
Auslesen der Set-Temperaturen
Setzen von Set-Temperaturen
Setzen von Ist-Temperaturen
Es können Ist-Temperaturen von externen Systemen gesetzt werden. Hierzu müssen Sensor-Schnittstellen mit Lizenz-IDs von Controme generiert werden, die in Smart-Heat-OS angelegt werden können. Pro Sensor fallen hierfür Kosten in Höhe von €10,- netto an. Die lizensierten Sensor-IDs und die zugehörige Schnittstellenbeschreibung erhalten Sie auf Anfrage per Email. Bitte senden Sie bei Bedarf eine Anfrage an support@controme.com
Achtung: Aufgrund interner Filter nimmt Smart-Heat-OS nur Temperaturen an, die durch 0,125 teilbar sind. Wobei die Endungen .125 als .12 zu senden sind (…, 22.0, 22.12, 22.5, 22.62, 22.75, …). Bei der Umsetzung bitte entsprechend Runden (auf 0.125, 0.25 oder 0.5).
Implementierungsbeispiel in OpenHab
Hinweise zur Controme API
Die Schnittstellenbeschreibungen für das Controme Smart-Heat-System sind für erfahrene Entwickler gedacht, welche Drittsysteme an Controme Smart-Heat anbinden wollen. Bitte beachten Sie, dass wir seitens Controme keinen technischen Support für die API liefern.
Die Schnittstellenbeschreibungen werden mit jedem Update von Controme Smart-Heat laufend aktualisiert. Wir behalten es uns vor mit einem Update Änderungen an den Schnittstellen vorzunehmen.
Problembehebung
API gibt nichts aus
Bitte prüfen Sie in diesem Fall zunächst, ob Sie die korrekte Haus-ID verwenden. Aus unterschiedlichen Gründen ist die ID manchmal „2“ und nicht „1“. Der korrekte Endpunkt ist deshalb bei einigen Systemen z.b.
/get/json/v1/2/temps
und nicht
/get/json/v1/1/temps