CURL
Im Folgenden werden einige Beispielaufrufe mit dem Werkzeug CURL gezeigt. Manche Antworten wurden aus Platzgründen gekürzt.
Falls im CCU-Jack Benutzer angelegt worden sind, müssen mit der Option -u <Benutzer>:<Passwort> die Zugangsdaten angegeben werden. Mit der Option -k kann bei Bedarf die Zertifikatsüberprüfung für HTTPS-Verbindungen abgeschaltet werden.
Unter Linux muss das Zeichen $ in der URL durch %24 ersetzt werden. Oder die ganze URL muss in Hochkommata ' eingeschlossen werden.
Das Lesen eines Datenpunktes erfolgt über die HTTP-Methode GET. Der aktuelle Wert kann also auch mit einem Web-Browser gelesen werden. In der Web-UI der CCU kann unter Einstellungen → Geräte die Seriennummer des Kanals ermittelt werden. Der : in der Seriennummer muss duch / ersetzt werden. Der Parametername ist beispielsweise STATE bei einem Schaltaktor oder LEVEL bei einem Rollladenaktor.
Aufruf:
curl http://localhost:2121/device/HEQ0123456/1/STATE/~pv
Antwort:
{
"ts": 1546297200000,
"v": false,
"s": 0
}Die Eigenschaft v enthält den aktuellen Wert des Datenpunktes. ts enthält den Zeitstempel der letzten Aktualisierung des Wertes (Millisekunden seit 1.1.1970 UTC, hier 1.1.2019 00:00 MEZ). s gibt Auskunft über die Qualität des Wertes (hier immer 0 → Gut).
Das Setzen eines Datenpunktes erfolgt über die HTTP-Methode PUT.
Aufruf (Linux):
curl -X PUT -d '{"v":true}' http://localhost:2121/device/HEQ0123456/1/STATE/~pv
Aufruf (Windows):
curl -X PUT -d "{""v"":true}" http://localhost:2121/device/HEQ0123456/1/STATE/~pv
Antwort:
HTTP/1.1 200 OK
Fehler werden über den HTTP-Status angezeigt.
Aufruf:
curl http://127.0.0.1:2121
Antwort:
{
"description": "Root of the CCU-Jack VEAP server",
"identifier": "root",
"title": "Root",
"~links": [
{
"rel": "domain",
"href": "~vendor",
"title": "Vendor Information"
},
{
"rel": "domain",
"href": "device",
"title": "Devices"
},
{
"rel": "domain",
"href": "sysvar",
"title": "System variables"
}
]
}Die Eigenschaft href der Objekte im ~links-Array kann zur weiteren Erkundung des VEAP-Servers genutzt werden.
curl http://127.0.0.1:2121/device
Antwort:
{
"description": "CCU Devices",
"identifier": "device",
"title": "Devices",
"~links": [
{
"rel": "device",
"href": "NEQ1234567",
"title": "Rollladen Bad"
},
{
"rel": "device",
"href": "OEQ0123456",
"title": "Türkontakt Terrasse"
},
{
"rel": "device",
"href": "GEQ0123456",
"title": "Bewegungsmelder Flur EG"
},
...
]
}curl http://localhost:2121/device/OEQ0123456
Antwort:
{
"address": "OEQ0123456",
"aesActive": 0,
"availableFirmware": "",
"children": [
"OEQ0123456:0",
"OEQ0123456:1"
],
"direction": 0,
"firmware": "2.4",
"flags": 1,
"group": "",
"identifier": "OEQ0123456",
"index": 0,
"interface": "PEQ0123456",
"linkSourceRoles": "",
"linkTargetRoles": "",
"paramsets": [
"MASTER"
],
"parent": "",
"parentType": "",
"rfAddress": 5855058,
"roaming": 0,
"rxMode": 12,
"team": "",
"teamChannels": null,
"teamTag": "",
"title": "Türkontakt Terrasse",
"type": "HM-Sec-SC-2",
"version": 16,
"~links": [
{
"rel": "channel",
"href": "0",
"title": "Türkontakt Terrasse:0"
},
{
"rel": "channel",
"href": "1",
"title": "Türzustand Terrasse"
},
{
"rel": "devices",
"href": "..",
"title": "Devices"
}
]
}curl http://localhost:2121/device/OEQ0123456/1
Antwort:
{
"address": "OEQ0123456:1",
"aesActive": 1,
"availableFirmware": "",
"children": null,
"direction": 1,
"firmware": "",
"flags": 1,
"group": "",
"identifier": "1",
"index": 1,
"interface": "",
"linkSourceRoles": "KEYMATIC SWITCH WINDOW_SWITCH_RECEIVER WINMATIC",
"linkTargetRoles": "",
"paramsets": [
"LINK",
"MASTER",
"VALUES"
],
"parent": "OEQ0123456",
"parentType": "HM-Sec-SC-2",
"rfAddress": 0,
"roaming": 0,
"rxMode": 0,
"team": "",
"teamChannels": null,
"teamTag": "",
"title": "Türzustand Terrasse",
"type": "SHUTTER_CONTACT",
"version": 16,
"~links": [
{
"rel": "parameter",
"href": "INSTALL_TEST",
"title": "INSTALL_TEST"
},
{
"rel": "parameter",
"href": "LOWBAT",
"title": "LOWBAT"
},
{
"rel": "parameter",
"href": "STATE",
"title": "STATE"
},
{
"rel": "parameter",
"href": "ERROR",
"title": "ERROR"
},
{
"rel": "device",
"href": "..",
"title": "Türkontakt Terrasse"
},
{
"rel": "room",
"href": "/room/1248",
"title": "Wohnzimmer"
},
{
"rel": "function",
"href": "/function/1243",
"title": "Sicherheit"
}
]
}Bei den ~links sind ebenfalls Verweise auf die Räume ("rel":"room") und Gewerke ("rel":"function") des Kanals zu finden. In den title-Eigenschaften sind in der Regel die benutzerspezifischen Namen zu finden. Die Abfrageadresse eines Datenpuntkes ändert sich also nicht, wenn der Kanal in der CCU umbenannt wird. Das gleiche gilt auch für Systemvariablen.
curl http://localhost:2121/device/OEQ0123456/1/STATE
Antwort:
{
"control": "DOOR_SENSOR.STATE",
"default": false,
"flags": 1,
"id": "STATE",
"identifier": "STATE",
"maximum": true,
"minimum": false,
"operations": 5,
"tabOrder": 0,
"title": "STATE",
"type": "BOOL",
"unit": "",
"~links": [
{
"rel": "channel",
"href": "..",
"title": "Türzustand Terrasse"
},
{
"rel": "~service",
"href": "~pv",
"title": "PV Service"
}
]
}Der Dienst PV Service kennzeichnet einen Datenpunkt. Durch Anhängen von /~pv an die Adresse des Datenpunktes kann auf den aktuellen Wert zugegriffen werden.
curl http://localhost:2121/room
Antwort:
{
"description": "Rooms of the ReGaHss",
"identifier": "room",
"title": "Rooms",
"~links": [
{
"rel": "room",
"href": "1248",
"title": "Wohnzimmer"
},
{
"rel": "room",
"href": "2194",
"title": "Außengelände"
},
{
"rel": "room",
"href": "6510",
"title": "Bad"
},
...
]
}Das oben genannte gilt analog für die Erkundung der Gewerke (/function).
curl http://localhost:2121/room/1248
Antwort:
{
"identifier": "1248",
"title": "Wohnzimmer",
"~links": [
{
"rel": "collection",
"href": "..",
"title": "Rooms"
},
{
"rel": "channel",
"href": "/device/GEQ0123456/1",
"title": "Bewegung Wohnzimmer"
},
{
"rel": "channel",
"href": "/device/GEQ0012345/1",
"title": "Rollladen Esstisch"
},
...
]
}In der ~links-Eigenschaft werden die einem Raum zugewiesenen Kanäle aufgelistet. Über den enthaltenen Verweis kann direkt zu den Datenpunkten gesprungen werden.
Das Gleiche gilt analog für ein Gewerk.
HomeMatic Geräte und die zugehörigen Kanäle können Konfigurationoptionen besitzen. Sie befinden sich im sogenannten Parametersatz MASTER. Über die REST-API des CCU-Jacks kann dieser Parametersatz gelsesen und gesetzt werden. Im Folgenden Beispiel werden die Konfigurationsdaten eines Kanals einer Innensirene gelesen.
Aufruf (Linux):
curl 'http://localhost:2121/device/NEQ0123456/1/$MASTER/~pv'
Aufruf (Windows):
curl http://localhost:2121/device/NEQ0123456/1/$MASTER/~pv
Antwort:
{
"ts": 1583613359343,
"v": {
"AES_ACTIVE": false,
"SOUND_ID": 64,
"STATUSINFO_MINDELAY": 2,
"STATUSINFO_RANDOM": 1,
"TRANSMIT_TRY_MAX": 6
},
"s": 0
}Das Setzen einer Geräte- pzw. Kanalkonfiguration erfolgt über die HTTP-Methode PUT. Es brauchen nur die Parameter angegeben zu werden, die auch geändert werden sollen. Im Folgenden Beispiel wird der Signalton einer Innensirene geändert.
Aufruf (Linux):
curl -X PUT -d '{"v":{"SOUND_ID":64}}' 'http://localhost:2121/device/NEQ0123456/1/$MASTER/~pv'
Aufruf (Windows):
curl -X PUT -d "{""v"":{""SOUND_ID"":64}}" http://localhost:2121/device/NEQ0123456/1/$MASTER/~pv
Antwort:
HTTP/1.1 200 OK
Fehler werden über den HTTP-Status angezeigt.
Die Programme der CCU können über die Aufzählung /program erkundet werden:
curl http://localhost:2121/program
Die Informationen zu einem Programm können anhand der ISE-ID abgefragt werden. Diese wird in der obigen Erkundung im Attribut href zurückgegeben:
curl http://localhost:2121/program/123
Ein CCU-Programm ist im CCU-Jack auch eine Variable. Der Zeitpunkt der letzten Ausführung kann durch das Lesen des Variablenwertes ermittelt werden. Der Zeitstempel des Prozesswertes (Eigenschaft ts) entspricht dem Zeitpunkt der letzten Ausführung:
curl http://localhost:2121/program/123/~pv
Ein CCU-Programm kann durch das Schreiben des Wertes true ausgeführt werden.
Aufruf (Linux):
curl -X PUT -d '{"v":true}' http://localhost:2121/program/123/~pv
Aufruf (Windows):
curl -X PUT -d "{""v"":true}" http://localhost:2121/program/123/~pv
curl http://127.0.0.1:2121
Antwort:
{
"description": "Information about the server and the vendor",
"identifier": "~vendor",
"serverDescription": "VEAP-Server for the HomeMatic CCU",
"serverName": "CCU-Jack",
"serverVersion": "1.0.0-alpha.2",
"title": "Vendor Information",
"veapVersion": "1",
"vendorName": "[email protected]",
"~links": [
{
"rel": "item",
"href": "statistics",
"title": "HTTP(S) Handler Statistics"
},
{
"rel": "collection",
"href": "..",
"title": "Root"
}
]
}Autor dieses Handbuchs ist Mathias Dzionsko. Dieses Handbuch steht unter folgender Lizenz:
