« Zurück zu Produkt

Dokumentation

Feedback senden!

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.

Warning

Für die Funktionsaufrufe können die normalen Befehle der Befehlsreferenz und Modulreferenz verwendet werden.

Warning

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!

Warning

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}
Haben Sie noch Fragen?