Dokumentation
Datenaustausch
Erreichbarkeit
Die seit IP-Symcon 3.0 verfügbare JSON-RPC API ist standardmäßig über den Port 3777 erreichbar. Dabei ist der Port 3777 nur am lokalen System gebunden und erfordert keinerlei Authentifizierung.
Weiterhin ist die JSON-RPC API auf jedem in IP-Symcon eingerichteten WebServer aktiv. Dadurch können auf jeder Host/Port/SSL Konfiguration das WebFront und die Mobilen Apps einen Zugriff zu IP-Symcon bekommen.
Kennwort und Funktionen
Die JSON-RPC API wird über den Lizenz-Benutzernamen und das Fernzugriff Kennwort authentifiziert. Wenn kein Kennwort angegeben wird, so wird keinerlei Zugriff gewährt.
Ein Sonderfall sind einige WFC_* Funktionen, welche über das Kennwort des jeweiligen WebFront-Konfigurators authentifiziert werden. In diesem Fall wird als Benutzername "webfront" verwendet. Diese Funktionen ermöglichen den isolierten Zugriff auf die vom Konfigurator definierten Teilbereiche des Objektbaums. Ausschließlich die WFC_GetConfigurators Funktion wird ohne jegliche Authentifizierung zur Verfügung gestellt. Diese ist erforderlich, um die Auflistung der WebFront-Konfiguratoren für das WebFront und die Mobilen Apps zu ermöglichen.
Zusätzlich wird dadurch die IP-Adressen Autostart Funktion realisiert. Übertragen werden in dieser Funktion nur die ID/Titel/Icon/Position/Editierbarkeit des jeweiligen Konfigurators, ob ein Kennwort erforderlich ist und ob dieser Konfigurator für die Mobile Apps aktiviert wurde. Standardmäßig ist die Nutzung für Mobile Apps im Konfigurator deaktiviert, um ein Sicherheitsproblem auf den Basis-Baum (ID = 0) zu vermeiden.
Authentifizierung
Die im WebServer angebotene Basis-Authentifizierung gilt, sofern der WebServer für das WebFront genutzt wird, ausschließlich für den "user"-Ordner, der für benutzerdefinierte Inhalte freigegeben ist. Wenn der WebServer für ein anderes Verzeichnis genutzt wird, so gilt die Authentifizerung für alle Inhalte, die innerhalb dieses Verzeichnisses liegen - jedoch nicht für die JSON-RPC API, da diese den vorher genannten Authentifizierungsregeln unterliegt.
Für die Funktionsaufrufe können die normalen Befehle der Befehlsreferenz und Modulreferenz verwendet werden.
Als Benutzername muss Ihr Lizenz-Benutzername verwendet werden. Das Kennwort kann über Fernzugriff aktivieren gesetzt werden.
JSON-RPC Schnittstelle (über PHP/IP-Symcon)
Kernelversion auslesen
$rpc = new JSONRPC("http://user:password@127.0.0.1:3777/api/"); $result = $rpc->IPS_GetKernelVersion(); echo "KernelVersion: ".$result;
Skripte starten
$rpc = new JSONRPC("http://user:password@127.0.0.1:3777/api/"); $rpc->IPS_RunScript(34956);
Variablen auslesen
$rpc = new JSONRPC("http://user:password@127.0.0.1:3777/api/"); echo $rpc->GetValueFormatted(58383);
Variablen verändern
$rpc = new JSONRPC("http://user:password@127.0.0.1:3777/api/"); $rpc->SetValue(38809, 18.5);
HomeMatic Gerät schalten
$rpc = new JSONRPC("http://user:password@127.0.0.1:3777/api/"); $rpc->HM_WriteValueBoolean(20558, "STATE", false);
Rückgabewert bei nicht Erreichbarkeit
try { $rpc = new JSONRPC("http://user:password@127.0.0.1:3777/api/"); $rpc->IPS_GetKernelDir(); } catch (JSONRPCException $e) { echo 'RPC Problem: ', $e->getMessage(), "\n"; } catch (Exception $e) { echo 'Server Problem: ', $e->getMessage(), "\n"; }
WebSocket Schnittstelle (über JavaScript)
Änderungen im System können über die Websocket Schnittstelle schnellstmöglich empfangen werden.
Gesamte API
//IP-Symcon 5.1/IP-Symcon 5.2 //Normal var connection = new WebSocket('ws://127.0.0.1:3777/api/', [btoa('email:fernzugriffpw').replace(/=/g, '')]); //SSL var connection = new WebSocket('wss://127.0.0.1:3777/api/', [btoa('email:fernzugriffpw').replace(/=/g, '')]); //ab IP-Symcon 5.3 //Normal var connection = new WebSocket('ws://127.0.0.1:3777/api/', [encodeURIComponent(btoa('email:fernzugriffpw'))]); //SSL var connection = new WebSocket('wss://127.0.0.1:3777/api/', [encodeURIComponent(btoa('email:fernzugriffpw'))]);
WebFront API
//IP-Symcon 5.1 //Normal var connection = new WebSocket('ws://127.0.0.1:3777/api/wfc/12345', [btoa('webfront:webfrontpw').replace(/=/g, '')]); //SSL var connection = new WebSocket('wss://127.0.0.1:3777/api/wfc/12345', [btoa('webfront:webfrontpw').replace(/=/g, '')]); //IP-Symcon 5.2 //Normal var connection = new WebSocket('ws://127.0.0.1:3777/wfc/12345/api/', [btoa('webfront:webfrontpw').replace(/=/g, '')]); //SSL var connection = new WebSocket('wss://127.0.0.1:3777/wfc/12345/api/', [btoa('webfront:webfrontpw').replace(/=/g, '')]); //ab IP-Symcon 5.3 //Normal var connection = new WebSocket('ws://127.0.0.1:3777/wfc/12345/api/', [encodeURIComponent(btoa('webfront:webfrontpw'))]); //SSL var connection = new WebSocket('wss://127.0.0.1:3777/wfc/12345/api/', [encodeURIComponent(btoa('webfront:webfrontpw'))]);
JSON-RPC Schnittstelle (über cURL)
Aufruf via Kommandozeile
Variablen verändern
Beim Benutzername mail%40provider.de oder Passwort darf @ nicht geschrieben werden. => Als Ersatz: %40
Benutzername (Mail), Passwort und IP ohne <,> eintragen!
Zur Kodierung und Berücksichtigung von Sonderzeichen kann die Seite urlencoder.org für Benutzername und Passwort genutzt werden.
//SetValue Integer mit den Parametern ID = 12345 und Wert = 42 curl -i -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"SetValue\", \"params\": [12345, 42]}" http://<mail%40provider.de>:<Passwort>@<IP>:3777/api/ //SetValue Float mit den Parametern ID = 12346 und Wert = 1.23 curl -i -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"SetValue\", \"params\": [12346, 1.23]}" http://<mail%40provider.de>:<Passwort>@<IP>:3777/api/ //SetValue Boolean mit den Parametern ID = 12347 und Wert = false curl -i -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"SetValue\", \"params\": [12347, false]}" http://<mail%40provider.de>:<Passwort>@<IP>:3777/api/ //SetValue String mit den Parametern ID = 12348 und Wert = "mein String" curl -i -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"SetValue\", \"params\": [12348, \"mein String\"]}" http://<mail%40provider.de>:<Passwort>@<IP>:3777/api/ //Rückgabewert bei Erfolg {"jsonrpc":"2.0","id":"0","result":true}
Variablen auslesen
//GetValue mit den Parametern ID = 12345 curl -i -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"GetValue\", \"params\": [12345]}" http://<mail%40provider.de>:<Passwort>@<IP>:3777/api/ //Rückgabewert {"jsonrpc":"2.0","id":"0","result":42}