Aktivierung Fernzugriff
Siehe auch die jeweils aktuelle Symcon-Dokumentation.
Einsatz:
Klassen zur Nutzung der JSON-API von IPSymcon
Download
vom GitHub
Perl und PHP-Klasse sowie PHP Wrapper für IPS Funktionen mit Beispielen für IPS4.0+
Funktion:
IPSymcon führte mit Version V3.0 eine JSON basierte API ein, mit deren Hilfe sich nahezu alle IPS-internen Funktionen von außerhalb aufrufen lassen.
Ab Version V3.1 wird diese API als Standard für die IPSymcon Konsole genutzt.
Die vorgestellten Klassen kapseln mittels Autoload-Funktion diese API und wickeln das Protokoll ab. Mit ihrer Hilfe ist es z.B. möglich,
Scripte mit den gleichen IPSymcon Befehlen unter Perl auf einem Unix-Server laufen zu lassen als ob sie lokal auf dem IPSServer sind.
Ein weiterer Einsatz ist die Möglichkeit der Entwicklung von IPSymcon PHP Scripten mit einer externen IDE wie
PHPStorm oder
Netbeans.
Der Vorteil gegenüber dem klassischen Delphi-SDK besteht darin, das man nicht mehr eine ganz spezielle Entwicklungsumgebung einer fest vorgegebenen
ProgrammierSprache braucht, sondern durch die Allgemeingültigkeit von
JSON ganz einfach das verwenden kann, was man selbst am besten kann, und das auch unabhängig von der verwendeten Plattform.
Limitierend ist eigentlich nur die nur begrenzt vorhande Echtzeitfähigkeit.
Installation und Konfiguration
Auf Zielsystem muss für PHP die Json- und Mbstring-Extensions installiert sein.
Die Perl-Scripte benötigen das REST::Client, MIME::Base64 und Json-Modul sowie deren Abhängigkeiten.
Das Perl-Modul bitte in einen von @INC durchsuchtes Verzeichnis legen oder den use Befehl im eigenen Script anpassen.
Falls nicht im gleichen Netz gearbeitet wird ist eine Freischaltung des IPS-WebFront Ports (default ab IPS4.0 Port 3777) notwendig.
Dort muss dieser Port auch für eingehende Zugriffe geöffnet werden.
Das PHP-Files sollten in das gleiche Verzeichnis wie das eigene Script gelegt werden oder die include-Befehle dort anpassen.
Gemeinsam genutzte Parameter können in eine Konfigrationsdatei ausgelagert werden (default IPS_JSON_config.cfg).
Die Datei wird ausgeführt/included, so das die Syntax der jeweiligen Sprache entsprechen muss (Bei PHP ohne <? ?> Tags!)
Für externe Zugriffe wie sie hier benötigt werden, muss der "Fernzugriff" z.B. über den IPSymcon-Tray->Informationen aktiviert werden.
Der User ist nun (fest) der Lizenz-Benutzername, das Password muss über "Ändern" gesetzt werden.
Bei gesetztem Password ist der Fernzugriff aktiv.
Aktivierung Fernzugriff
Siehe auch die jeweils aktuelle Symcon-Dokumentation.
Anwendungen
Zunächst muss die URL für den API-Zugriff gebildet und damit die Klasse instantiert werden. Dann kann die Aktion ausgeführt werden.
Fehler werden in eine Klassenvariable geschrieben und können dort geprüft werden. Alternativ kann bei PHP auch eine Exception ausgelöst werden.
Den genauen Funktionsumfang bitte der Inline-Dokumentation entnehmen. Im Download sind auch weiterführende Beispiele enthalten.
So wird dieser Wrapper aktuell für Icinga/Nagios Checks zur Prüfung und Logging von IPS Variablen
und zum Auslesen von WS300PC History Records verwendet.
Beispiele
#------------- #IPS_JSON_config.cfg for PHP and Perl #commandline parameter will have precedence over this #this code will be executed by the calling script, no Tags allowed $host='ips'; $user="user@ipsymcon.de"; $password="ipsymcon"; $port=3777;
use strict;
use IPS_JSON;
my $user='...';
my $password='...';
my $host='...';
my $port=...;
my $config='IPS_JSON_config.cfg';
if (-r $config) {
do($config);
}
my $url="http://".$host.":".$port."/api/";
my $id=123456;//FS20-Instance
my $state='On';//einschalten
my $ips=IPS_JSON->new($url,$user,$password,2);//2=timeout, see perldoc
my $action=$ips->bool($state=~/On|Ein|1/i);
my $res=$ips->FS20_SwitchMode($id,$action);
if ($res) {
print "Switch $state Instance $id succeeded\n";
exit (0);
}else{
die "Error:".$ips->getError;
}
include ('IPS_JSON.php');
$user='...';
$password='...';
$host='...';
$port=...;
$config='IPS_JSON_config.cfg';
if (file_exists($config)) {
$config_data=file_get_contents($config);
$res=eval($config_data);
if ($res===false) {
echo "eval of $config failed. Hint:Use code only, no leading php tags\n";
exit;
}
}
$id=123456;//FS20-Instance
$state='On';//einschalten
$url="http://".$host.":".$port."/api/";
$ips = new IPS_JSON($url,$user,$password);
$switch=preg_match("/On|Ein|1/i",$state)?true:false;
$res=$ips->FS20_SwitchMode($id,$switch); //FS20_SwitchMode ist ein Standard IPS-Befehl
if (!$res) {
die ("IPS Request failed:".$ips->getErrorMessage()."\n");
}else{
print "Send $state command to Instance $id successfully\n";
}
Aus dem Wunsch heraus, IPSymcon-Funktionen in einer "richtigen" IDE zu entwickeln und die gleichen Scripte
sowohl native in der normalen IPSymcon Umgebung als auch auf einem seperaten Webserver einsetzen zu können ist dieser Wrapper
entstanden. Dazu werden alle bekannten IPSymcon Funktionen ausgelesen und als Call der bereits vergestellten IPS_JSON Klasse neu definiert.
Zum Mappen der IPSymcon Funktionen auf die JSON API wird das generierte Script ips_wrapper.php eingebunden.
Anschliessend kann jede exportierte Funktion wie in der nativen IPSymcon PHP Umgebung aufgerufen werden.
Zur Generierung wird das Script gen_ips_wrapper.php verwendet.
Anschliessend müssen nur die folgenden Zeilen am Anfang der eigenen Scripte eingefügt werden und schon sind die internen PHP-Scripte auch extern lauffähig.
if (!function_exists('IPS_GetKernelVersion')) {
//we are outside of IPS and need the JSON wrapper
include('ips_wrapper.php');
}
//now you can call ips functions as usual
$version=IPS_GetKernelVersion();
print $version;
Die Dokumentation der API PHP-Klasse und des Wrappers ist hier zu finden.