« Back to Product

Documentation

Send feedback!

Data Exchange

Reachability

The JSON-RPC API, which has been available since IP-Symcon 3.0, can be accessed via port 3777 by default. Port 3777 is only bound to the local system and does not require any authentication.
The JSON-RPC API is also active on every web server set up in IP-Symcon. This means that the WebFront and the mobile apps can have access to IP-Symcon on every host/port/SSL configuration.

Password and Features

The JSON-RPC API is authenticated via the license username and the Remote Access password. If no password is given, no access will be granted.
A special case are some WFC_* functions that are authenticated using the password of the respective WebFront configurator. In this case "webfront" is used as the username. These functions enable isolated access to the sub-areas of the object tree defined by the configurator. Only the WFC_GetConfigurators function is made available without any authentication. This is necessary to enable the listing of the WebFront configurators for the WebFront and the mobile apps.
In addition, the IP address Autostart Function is thereby implemented. In this function, only the ID/title/icon/position/editability of the respective configurator, whether a password is required and whether this configurator has been activated for the mobile apps is transmitted. By default, the use of mobile apps is deactivated in the configurator in order to avoid a security problem on the basic tree (ID = 0).

Authentication

The "user" folder, which is shared for user-defined content. The basic authentication offered in the web server applies exclusively to it, provided the web server is used for the WebFront. If the web server is used for another directory, the authentication applies to all content that is located in this directory - but not to the JSON-RPC API, as this is subject to the aforementioned authentication rules.

Warning

The normal commands of the Command Reference and Module Reference can be used for the function calls.

Warning

Your license username must be used as username. The password can be set using Remote Access.

JSON-RPC interface (via PHP/IP-Symcon)

Read Kernel Version

$rpc = new JSONRPC("http://user:password@127.0.0.1:3777/api/");
$result = $rpc->IPS_GetKernelVersion();
echo "KernelVersion: ".$result;

Start Scripts

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

Read Variables

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

Change Variables

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

Switch HomeMatic Device

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

Return value if not available

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 Interface (via JavaScript)

Changes in the system can be received as quickly as possible via the Websocket interface.

Full API

//IP-Symcon 5.1/IP-Symcon 5.2
//Normal
var connection = new WebSocket('ws://127.0.0.1:3777/api/', [btoa('email:remoteaccesspw').replace(/=/g, '')]);
//SSL
var connection = new WebSocket('wss://127.0.0.1:3777/api/', [btoa('email:remoteaccesspw').replace(/=/g, '')]);
//since IP-Symcon 5.3
//Normal
var connection = new WebSocket('ws://127.0.0.1:3777/api/', [encodeURIComponent(btoa('email:remoteaccesspw'))]);
//SSL
var connection = new WebSocket('wss://127.0.0.1:3777/api/', [encodeURIComponent(btoa('email:remoteaccesspw'))]);

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, '')]);
//since 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 Interface (via cURL)

Invoke via Command Line

Change Variables

For the username mail%40provider.de or password @ must not be written. => Instead: %40
Enter username (mail), password and IP without <,>!

Warning

To encode and to take special characters into account, the page urlencoder.org can be used for username and password.

//SetValue Integer with the parameters ID = 12345 and value = 42
curl -i -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"SetValue\", \"params\": [12345, 42]}" http://&lt;mail%40provider.de>:<Passwort>@<IP>:3777/api/
//SetValue Float with the parameters ID = 12346 and value = 1.23
curl -i -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"SetValue\", \"params\": [12346, 1.23]}" http://&lt;mail%40provider.de>:<Passwort>@<IP>:3777/api/
//SetValue Boolean with the parameters ID = 12347 and value = false
curl -i -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"SetValue\", \"params\": [12347, false]}" http://&lt;mail%40provider.de>:<Passwort>@<IP>:3777/api/
//SetValue string with the parameters ID = 12348 and value = "my string"
curl -i -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"SetValue\", \"params\": [12348, \"my string\"]}" http://&lt;mail%40provider.de>:<Passwort>@<IP>:3777/api/
//Return-value if successful
{"jsonrpc":"2.0","id":"0","result":true}

Read Variables

//GetValue with the parameters ID = 12345
curl -i -X POST -H "Content-Type: application/json" -d "{\"jsonrpc\": \"2.0\", \"id\": \"0\", \"method\": \"GetValue\", \"params\": [12345]}" http://&lt;mail%40provider.de>:<Passwort>@<IP>:3777/api/
//Return-value
{"jsonrpc":"2.0","id":"0","result":42}
Any questions?