Script-Syntax

• + Aufbau des Dateinamens

  - Aufbau des Dateinamens

  Die Dateien müssen generell in UTF-8 ohne BOM codiert sein.

  Der Name einer PseudoGeräte-Script-Datei muss folgendermaßen aufgebaut sein:

  psgname.php

  • Der erste Teil "psg" bedeutet, dass es sich um eine PseudoGeräte-Datei handelt.
  • Der zweite Teil "name" steht für den angezeigten Gerätenamen in den Scripten.
  • Die Groß- und Kleinbuchstaben A-Z und a-z, die Zahlen 0-9, das Leerzeichen " " sowie der Bindestrich "-" sind für den Namensteil "name" erlaubt (bei einigen Servern auch die Umlaute ä, ö, ü, ß). Dieser wird dann auch in der WebGUI so angezeigt.
    Beispiel: psgFX-Dose 1.php
    Anzeige im WebGUI: FX-Dose 1
  • Steht im Namen die Zeichenfolge "auto", so wird dieses Script in der sas.php nicht angezeigt, kann aber in der sasap.php eingesetzt werden.
  • Der letzte Teil ".php" ist wieder Pflicht.
  • Der Dateiname darf außer im Teil "name" keine Großbuchstaben enthalten.
  • Seltene Sonderzeichen und Umlaute werden von einigen Servern nicht akzeptiert und sollten gemieden werden.

• Parameterübergabe

  Die Dateien erhalten durch $_GET ihre Parameter und geben mit Standardanzeigebefehlen wie echo oder printf() Werte zurück.

  • + Statusabfrage

    - Statusabfrage

    psgname.php?info=status

    • Dies ist der Aufruf durch SensorAndSwitch um Sensor-Werte zu erhalten.
      $_GET["info"] beinhaltet den String "status".
    • Dabei zeigt dann psgname.php als "echo"-Ausgabe:
    • S#n# - n steht für 0, 1 oder 2 - Schalter ist aus, an oder nicht abrufbar.
    • W#nnn# - n steht für einen beliebigen numerischen Wert für Leistung/Verbrauch.
    • W#nnn*mmm# - n steht für einen beliebigen numerischen Wert für Leistung/Verbrauch - m steht für einen beliebigen numerischen Wert für Gesamtenergieverbrauch.
    • T#nnn# - n steht für einen beliebigen numerischen Wert für Temperatur.
    • T#nnn*mmm# - n steht für einen beliebigen numerischen Wert für Temperatur - m steht für einen beliebigen numerischen Wert für Korrekturwert.
    • P#nnn*xxx# - n steht für einen beliebigen numerischen Wert - x steht für die (Mess-)Einheit.
    • P#xxx*HTML# - x steht für beliebigen Text (auch HTML) / Nur Anzeige, keine Auswertung möglich.
    • I#xxx# - x steht für beliebigen Text (auch HTML) / Nur Anzeige, keine Auswertung möglich, kompletter, jedoch schmalerer Bereich nutzbar, nicht kombinierbar mit anderen Pseudos.
    • IB#xxx# - x steht für beliebigen Text (auch HTML) / Nur Anzeige, keine Auswertung möglich, kompletter, doppelt hoher Bereich nutzbar, nicht kombinierbar mit anderen Pseudos.
    • V#xxx# - x steht für beliebigen Text in Form einer Versionsangabe, kombinierbar mit anderen Pseudos.
    • V#xxx*vvv# - v steht für einen Variablennamen und x steht für den neuen Inhalt der Variablen, mehrfach kombinierbar mit anderen Pseudos
    • FN#xxx# - x steht für beliebigen Text als WebGUI-Anzeigename (friendly name), kombinierbar mit anderen Pseudos.
    • E#xxx# - allgemeiner Fehler, Gerät nicht verfügbar, Messwert nicht lesbar, Webseite nicht abrufbar, etc.; x kann als Fehlerrückgabegrund angegeben werden, wird aber zur Zeit noch nicht ausgewertet.
    • C#xxx# - Das Script meldet an sas.php, dass keine anderen Pseudos ausgewertet werden sollen. Dafür werden die alten in der Datenbank gespeicherten Werte erneut angezeigt und die interne Variable $gerarray["Counter"] wird um 1 erhöht; x kann als Variablenwert angegeben werden, wird aber zur Zeit noch nicht ausgewertet
    • Diese Pseudos können in einer Zeile auch gemischt ausgegeben werden (Ausnahme I## und IB##).
    • Die Reihenfolge der Priorität der PseudoSensoren/-Schalter ist festgelegt auf P##, S##, W## und T##. Wird Pseudo P## verwendet, so werden die Sensorwerte W## und T## versteckt, sind aber für die Automation abrufbar. S## wird angezeigt. C## hat höchste Priorität und verhindert die Auswertung anderer Pseudos.

    Beispiele:

    • T#22.4# - gibt SensorAndSwitch an, dass es ein Sensorgerät für Temperatur ist und zeigt dieses mit 22,4°C an.
    • W#133.220#S#1#V#V 1.00# - gibt SensorAndSwitch an, dass es sich um ein schaltbares Gerät mit Watt-Messung handelt und zeigt an, dass es an ist und 133.22 Watt verbraucht, sowie dass es die Version V 1.00 des Scriptes ist.
    • T##E## - gibt SensorAndSwitch an, dass es ein Sensorgerät für Temperatur ist, aber nicht aktiv/verfügbar ist.
    • V#111*ID#V#0*Schalter# - weist den SensorAndSwitch-Variablen ID den Wert 111 und der Variablen Schalter den Wert 0 zu. Damit sind sehr tiefgreifende Manipulationen möglich. Bitte umsichtig benutzen!

    Die Pseudogeräte-Dateien müssen diese Werte so darstellen, so dass SensorAndSwitch sie erkennen und weiterverarbeiten kann.

    Beim Erstellen eigener PseudoGeräte-Dateien ist darauf unbedingt zu achten!

    Ein gutes Beispiel für den Einsatz des Pseudos C## ist die in den Beispielen mitgelieferte psgWetter.php. Hier kann man sich ansehen, wie dieses in Verbindung mit der Variablen $gerarray["Counter"] eine Verzögerung der Abfrage bewirken kann.

  • + Schaltvorgang

    - Schaltvorgang

    psgname.php?schalter=1

    psgname.php?schalter=0

    • Hier muss innerhalb der PseudoGeräte-Datei $_GET["schalter"] mit den Werten "0" oder "1" ausgewertet und ein entprechender Schaltbefehl per URL an das reale Gerät geschickt werden.
    • Es muss ein Pseudo
      • S#0# für aus
      • S#1# für an
      • S#2# für nicht erreichbar
      • S##E## für schwerwiegender Fehler
      zurückgeliefert werden.

Besondere Pseudos

• + Pseudo P#xxx*HTML#

  - Pseudo P#xxx*HTML#

  Der nutzbare Bereich ist 310x60 Pixel groß.

  Standardmäßig wird der eingefügte Inhalt 20px nach unten rechtsbündig eingefügt.

  Dies kann folgendermaßen beeinflusst werden:

  • Positionsbeginn links oben:
    <div style='text-align:left;width:310px;position:absolute;top:-20px;'>
  • Um einen Image-Button als solchen hervorzuheben, dass er auf ein Überschweben des Mauszeigers reagiert, kann man diesen mitsamt <img>- und <a>-Tag in einen <span>-Tag setzen:
    ...<span id="klick"><a ...><img ...></a></span>...
  • Das Einbinden von Bildern erfolgt am besten mit der Funktion picdesign("bilddateiname.png"). Diese liefert entweder den Bilddateinamen aus dem aktivierten Design oder, wenn dort nicht vorhanden, aus dem Standard-Design zurück.

  Weitere Beispiele

  • echo "P#<div style='position:absolute;top:-20px;font-size:14px;'>".$Status."</div>*HTML#";
  • position:absolute;top:-20px;
    damit kommt man nach oben an den Rand.
  • font-size:nnnpx;
    damit wählt man eine kleinere Schriftgröße für mehrzeilige Nutzung.
  • echo "P#<div style='text-align:center;width:310px;position:absolute;top:-20px;font-size:14px;'>".$Status."</div>*HTML#";
  • text-align:center;width:310px;
    damit zentriert man.

  Zusammengefasst

  • Der verfügbare <div>-Bereich ist: width:310px; height:60px; groß.
  • Die Zeile ist auf top:20px; festgelegt. Änderbar durch position:absolute;top:-20px;

  text-align:center;width:310px;

  • auf einen <div>-Bereich zentriert den Eintrag.

  text-align:left;width:310px;

  • auf einen <div>-Bereich beginnt den Text links.

• + Pseudo I#xxx#

  - Pseudo I#xxx#

  Der nutzbare Bereich ist 690x40 Pixel groß.

  Standardmäßig wird der eingefügte Inhalt 10px nach unten linksbündig eingefügt.

  Dies kann folgendermaßen beeinflusst werden:

  • Positionsbeginn links oben:
    <div style='top:-10px;'>
  • Das Einbinden von Bildern erfolgt am besten mit der Funktion picdesign("bilddateiname.png"). Diese liefert entweder den Bilddateinamen aus dem aktivierten Design oder, wenn dort nicht vorhanden, aus dem Standard-Design zurück.

• + Pseudo C#xxx#

  - Pseudo C#xxx#

  Dies ist eine besondere Form der Pseudos. Mit diesem kann man einen Aufrufzyklenzähler benutzen und damit eine Verzögerung der tatsächlichen Übergabe von ermittelten Werten erreichen. Stattdessen werden die alten Cache-Werte aus der Datenbank verwendet.

  Einsatzort sind z. B. Webseiten mit Sensordaten, die sich nicht häufig hintereinander aufrufen lassen. Um dann einen zu schnellen tatsächlichen Abruf der Webseite zu verhindern, kann man das Pseudo C## nun nutzen.

  In den Beispieldateien befindet sich mit psgWetter.php ein gutes Beispiel, auf dessen Befehlsteile nun näher eingegangen wird.

  • include __DIR__."/../include/psg.php"; - Bindet alle öffentlichen SAS-Funktionen ein.
  • $gerarray=getGerInfo(substr(basename(__FILE__,".php"),3)); - liest die Datenbankdaten des PSG (PseudoGerätes).
  • if ($gerarray["Counter"]>10) { - Fragt den Counter (Aufrufzyklenzähler) ab.
    Hat dieser eine bestimmte Anzahl erreicht, wird die Webseite im Folgenden ausgewertet.
  • else {echo "C##";} - Wurde der Zähler noch nicht erreicht, sendet das Script das Pseudo C## zurück, was sasap.php dazu veranlasst alle eventuell mitgelieferten Pseudos nicht auszuwerten, sondern sämtliche vorhandenen alten Daten aus der Datenbank zu benutzen. $gerarray["Counter"] wird dabei automatisch um 1 erhöht.
  • Gibt das Script nicht den Pseudo C## zurück, so wird $gerarray["Counter"] automatisch immer auf 0 zurückgesetzt.