Heizungssteuerung API

Mit der Controme API können mit einfachen http-Befehlen Informationen abgerufen und Einstellungen vorgenommen werden. So lassen sich Temperaturen und Systemstati abfragen und auch einzelne Werte setzen.

Die Kommunikation erfolgt über den lokal installierten Controme (Mini-)Server.

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/

Anwendungsbeispiel: Wenn 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.

API Aktivierung

Die Controme-API wird mit der Buchung dieses Artikels auf Ihrem lokalen Controme-Server freigeschaltet.

Bitte geben Sie dazu bei der Bestellung die Mac-Adresse ihres Controme-Servers an.

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.

Prinzipielles zur API Syntax

Adressformat:

/get/json/v1/[HAUSID]/[METHODE]/[DATA]*/

und

/set/json/v1/[HAUSID]/[METHODE]/[DATA]*/

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-info

Enthält

„hw“: Zeigt die Hardwareversion und die spezifische Hardware-Revision des Geräts an.
„sw-date“: Gibt das Datum und die Uhrzeit der installierten Softwareversion an, um sicherzustellen, dass die neueste Version verwendet wird.
„branch“: Zeigt den Software-Entwicklungszweig an, auf dem das System läuft (z.B. „dev“ für den Entwicklungszweig).
„os“: Gibt das Betriebssystem und die Version an, die auf dem Gerät ausgeführt wird, hilfreich für die Kompatibilitätsprüfung und Systemadministration.
„fbi“: Zeigt das Datum und die Uhrzeit an, wann die SD-Karte oder das Dateisystem zuletzt erstellt oder modifiziert wurde.
„app-compatibility“: Gibt an, ob das System mit der nativen Controme-App kompatibel ist (TRUE oder FALSE).

URL:

…/get/json/v1/1/info/

Beispiel:

{

„sw-date“:“2024-09-16 16:39:20″,

„hw“:“Raspberry Pi 3 Model B Rev 1.2 Revision: a02082″,

„branch“:“master“,

„app-compatibility“:true,

„fbi“:“Fri Jun 24 09:54:51 2022″,

„os“:“Raspbian GNU/Linux 9 (stretch)“

}

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-permissions

Enthält:

Die Antwort gibt an, ob der Benutzer temporäre Temperaturänderungen vornehmen darf.
Die Antwort gibt an, ob der Benutzer permanente Temperaturänderungen vornehmen darf.

Authentifizierung: Im Authorization-Header müssen Benutzername und Passwort mittels Basic Auth übermittelt werden.

URL:

…/get/json/v1/1/permissions/

Beispiel:

{

„can_make_permanent_changes“:true,

„can_make_temporary_changes“:true

}

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

Die Antwort enthält alle relevanten Informationen zu den Räumen, einschließlich:

„etagenname“: Der Name der Etage.
„id“: Die eindeutige ID der Etage.
„raeume“: Liste der Räume auf der Etage.
- „id“: Eindeutige ID des Raumes.
- „name“: Name des Raumes.
- „is_temporary_mode“: Gibt an, ob der temporäre Modus aktiv ist (true / false).
- „remaining_time“: Restliche Dauer des temporären Modus in Sekunden.
- „mode_end_datetime“: Datum und Uhrzeit für das Ende des temporären Modus im Format YYYY-MM-DD HH:MM:SS.
- „total_offset“: Gesamtbetrag der auf den Raum angewendeten Offsets.
- „solltemperatur“: Die aktuell gültige Solltemperatur.
- „perm_solltemperatur“: Die Solltemperatur, die ohne den temporären Modus gelten würde.
- „temperatur“: Die aktuelle Raumtemperatur.
- „offsets“: Liste der aktiven Plugin-Offsets für den Raum.
- „sensoren“: Liste der verbundenen Sensoren im Raum.
  - „raumtemperatursensor“: Gibt an, ob es sich um einen Raumtemperatursensor handelt (true / false).
  - „letzte_uebertragung“: Zeitstempel der letzten Sensorübertragung.
  - „name“: Eindeutige ID des Sensors.
  - „wert“: Der aktuelle Wert des Sensors.
  - „beschreibung“: Beschreibung des Sensors.
- „luftfeuchte“: Die gemessene Luftfeuchtigkeit im Raum.
- „betriebsart“: Der aktuelle Betriebsmodus, z.B. "heating", "cooling", "off", "on".

URL:

…/get/json/v1/1/temps/ (gibt alle Räume aus)

…/get/json/v1/1/temps/[room-id] (gibt die spezifische Raum-ID aus)

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“)
calculationMethod
- Weather („witterungsgeführt“)
- Demand („Bedarfsgerecht mit FloorCore™ (nur für FBH)“)
- PluginValue („Vorgabe aus anderem Plugin“)
- DirectFPS („Direkte Eingabe einer FPS-Formel“)

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.

set – ziel benötigt „duration“ mit einer Zeitangabe in Minuten als Wert im Body. Ohne „duration“ funktioniert es nicht.

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.

set – temperaturszenen kann temporär oder dauerhaft gesetzt werden. Ist „duration“ mit einer Zeitangabe in Minuten als Wert im Body, wird die Temperaturszene temporär für die angegebene Zeitdauer aktiviert.

URL:

…/set/json/v1/1/temperaturszenen/4/

Methode:

POST

Body:

user
password
duration (optionale Zeitangabe in Minuten oder „default“)
room_id (optional: Wenn angegeben, wird nur der Raum gesetzt. Wenn nicht angegeben, werden alle Räume gesetzt)

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-Betriebsart

Erlaubt das wechseln der Betriebsart für einen oder für alle Räume.

URL:

für einen spezifischen Raum: …/set/json/v1/1/rooms/{room-id}/

für alle Räume: …/set/json/v1/1/rooms/

Methode:

POST

Body:

user
password
action: „betriebsart“
value: „heating“, „cooling“, „off“, „on“

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 oder Luftfeuchtewerte für einen Raum 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 (oder Luftfeuchten) an, die durch 0,125 teilbar sind. Außerdem ist die API auf zwei Dezimalstellen begrenzt, d.h. beim Übertragen von Werten mit drei Nachkommstellen bitte die letzte Stelle entfernen (also z.B. 22.0, 22.12, 22.5, 22.62, 22.75, …).

Implementierungsbeispiel in OpenHab

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