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:82/api/");
$result = $rpc->IPS_GetKernelVersion();
echo "KernelVersion: ".$result;

Skripte starten

$rpc = new JSONRPC("http://user:password@127.0.0.1:82/api/");
$rpc->IPS_RunScript(34956);

Variablen auslesen

$rpc = new JSONRPC("http://user:password@127.0.0.1:82/api/");
echo $rpc->GetValueFormatted(58383);

Variablen verändern

$rpc = new JSONRPC("http://user:password@127.0.0.1:82/api/");
$rpc->SetValue(38809, 18.5);

HomeMatic Gerät schalten

$rpc = new JSONRPC("http://user:password@127.0.0.1:82/api/");
$rpc->HM_WriteValueBoolean(20558, "STATE", false);

Rückgabewert bei nicht Erreichbarkeit

try {
    $rpc = new JSONRPC("http://user:password@127.0.0.1:82/api/");
    $rpc->IPS_GetKernelDir();
} catch (JSONRPCException $e) {
    echo 'RPC Problem: ',  $e->getMessage(), "\n";
} catch (Exception $e) {
    echo 'Server Problem: ',  $e->getMessage(), "\n";
}

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!

//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}

SOAP Schnittstelle (veraltet)

Es sollte die JSON-RPC Schnittstelle verwendet werden, da diese wesentlich schneller ist und eine Authentifizerung bietet. Außerdem können alle Befehle der Befehlsreferenz und Modulreferenz ohne zusätzliche Modifikationen oder Kenntnis der WSDL Beschreibung aufgerufen werden! Seit IP-Symcon 3.1 ist die SOAP Schnittstelle standardmäßig deaktiviert.

Die SOAP Schnittstelle/WSDL Beschreibungen können über folgende Adresse erreicht werden, sofern diese über die Spezialschalter aktiviert wurde:

Kompatibilität wurde bereits mit Delphi, Java, C#, VB.Net geprüft.

Alle Befehle der SOAP Schnittstelle verhalten sich äquivalent zu denen in PHP, müssen doch über die korrekt WSDL angesprochen werden und werden dabei ohne dem in PHP vorhandenen Prefix aufgerufen. Die normale Befehlsreferenz/Modulreferenz kann als Dokumentationsgrundlage verwendet werden.

Für Modulbefehle muss der TIDHeader mitgesendet, in dem die anzusprechende InstanzID angegeben wird.

Bekannte Probleme:

Seit IP-Symcon 2.5 wird die benötigte PHP SOAP Extension automatisch installiert.

Kernelversion auslesen

$soap = new SoapClient("http://127.0.0.1:3773/wsdl/IIPSSimpleKernel");
$result = $soap->GetKernelVersion();
echo "KernelVersion: ".$result;

Skripte starten

$soap = new SoapClient("http://127.0.0.1:3773/wsdl/IIPSScriptEngine");
$result = $soap->ExecuteScript(12345, true);
echo base64_decode($result);

Variablen verändern

$soap = new SoapClient("http://127.0.0.1:3773/wsdl/IIPSVariableManager");
$soap->WriteVariableFloat(12345, 23.4);

FS20 Gerät schalten

$soap = new SoapClient("http://127.0.0.1:3773/wsdl/IIPSFS20");
$id = 12345;
$soap->__setSoapHeaders(new SOAPHeader("urn:UIPSModuleTypes", 'TIDHeader',array('ID' => $id)));
echo $soap->SwitchMode(false);