« Zurück zu Produkt

Dokumentation

Module

Benötigt: IP-Symcon >= 4.0

Beschreibung

Ein Modul besteht grundlegend aus 2 Dateien. Der module.php und module.json.
Optional kann eine Konfigurationsseite (form.json) bereitgestellt werden.

form.json

Weitere Informationen zur Konfigurationsseite können unter Konfigurationsformulare nachgeschlagen werden.

locale.json

Weitere Informationen zur Übersetzung der Konfigurationsseite können unter Lokalisierungen nachgeschlagen werden.

module.json

Diese Datei beinhaltet Rahmeninformation, die unabdingbar sind, damit das Modul identifizierbar ist und korrekt eingebunden werden kann.

Parameter Datentyp Beschreibung
id string Einmalige GUID zur eindeutigen Identifikation. GUID Generator
name string Der Name des Moduls. (A-Z, a-z, 0-9, Leerzeichen, Unterstrich sind erlaubte Zeichen. Leerzeichen und Unterstriche dürfen dabei jedoch nicht am Anfang oder Ende sein. Ein leerer Name ist ebenfalls nicht gültig.)
type integer Type des Moduls (0: Kern, 1: I/O, 2: Splitter, 3: Gerät, 4: Konfigurator, 5: Discovery)
vendor string Herstellername und der Name des Menüpunkts unter dem das Gerät in "Instanz hinzufügen" gefunden werden kann. Wenn nichts angegeben wird, wird das Gerät unter "(Sonstige)" eingetragen.
aliases array [string] Zusätzliche Gerätenamen/-varianten
url string URL zur Dokumentationnsseite des Moduls (Muss mit http:// oder https:// beginnen. Darf Alternativ auch "" (leer) sein)
parentRequirements array [string] Datenfluss GUIDs, wodurch kompatible übergeordnete Instanzen ermittelt werden. Die übergeordnete Instanz muss mindestens eine dieser Datenfluss GUIDs als Implemented führen, um kompatibel zu sein
childRequirements array [string] Datenfluss GUIDs, wodurch kompatible untergeordnete Instanzen ermittelt werden. Die untergeordnete Instanz muss mindestens eine dieser Datenfluss GUIDs als Implemented führen, um kompatibel zu sein
implemented array [string] Unterstützte Datafluss GUIDs müssen in den jeweiligen ReceiveData/ForwardData Funktionen korrekt ausgewertet und unterstützt werden, sofern diese hier aufgelistet werden
prefix string Prefix, welcher den Funktionen vorausgeschrieben wird. Darf nur Zahlen und Buchstaben enthalten.
{
    "id": "{E5AA629B-75BD-45C0-9BCB-845C102B0411}",
    "name": "ModulnameXYZ",
    "type": 3,
    "vendor": "",
    "aliases":
    [
        "Name1UnterstütztesGerät",
        "Name2UnterstütztesGerät"
    ],
    "url": "https://www.symcon.de",
    "parentRequirements": [],
    "childRequirements": [],
    "implemented": [],
    "prefix": "ABC"
}

module.php

Dies ist die eigentliche Klassendatei, welche die Funktionen beinhaltet die hinterher Daten verarbeiten und weiterleiten.

Warning

Der Klassenname muss identisch zum "name" Parameter sein, welcher in der module.json definiert wurde. Einziger erlaubter Unterschied sind Leerzeichen. Diese müssen im Klassennamen innerhalb der module.php entfernt werden.

Warning

Funktionsnamen dürfen nur aus folgenden Zeichen bestehen: "a..z","A..Z","0..9". Des weiteren darf "$InstanceID" nicht als Parametername verwendet werden.

Seit IP-Symcon 8.1 gibt es die verbesserte Basisklasse IPSModuleStrict.
IPSModule ist weiter verfügbar, sollte jedoch für neue Module nicht mehr verwendet werden.

Die Folgende Tabelle zeigt die Unterschiede auf:

Merkmal IPSModule IPSModuleStrict
Type Hints Optional für public Funktionen Immer erforderlich
Fehlermeldungen bei fehlenden Type Hints in public Funktionen Nur Warnungen Führt zu Fehlern
Unterstützung veralteter Typen Integer/Boolean erlaubt Bitte int/bool benutzen
Rückgabe von RegisterVariable* Aktuelle Variablen-ID as int boolean, ob Variable erstellt wurde, um ggf. Startwert zu setzen)
Schreibzugriff auf erstellte Variablen Immer, auch Kundenseitig per SetValue Nur über $this->SetValue (Variablen sind über ReadOnly gesichert)
Datenfluss Verbindungen Komplex über ConnectParent/RequireParent/ForceParent Automatisch über die Kompatibilität und GetCompatibleParents()
Datenfluss Kodierung UTF-8 (utf8_encode/utf8_decode), Problematisch ab PHP 9.0 HEX-kodiert (bin2hex/hex2bin) und einfacher erkennbar wann eine Kodierung erforderlich ist

Vorlage minimal

// Klassendefinition
class ModulnameXYZ extends IPSModuleStrict {

    /**
    * Die folgenden Funktionen stehen automatisch zur Verfügung, wenn das Modul über das "Module Control" eingefügt wurden.
    * Die Funktionen werden, mit dem selbst eingerichteten Prefix, in PHP und JSON-RPC wie folgt zur Verfügung gestellt:
    *
    * ABC_MeineErsteEigeneFunktion($id);
    *
    */
    public function MeineErsteEigeneFunktion(): void {
        echo $this->InstanceID;
    }

}

Vorlage klassisch

// Klassendefinition
class ModulnameXYZ extends IPSModuleStrict {

    // Überschreibt die interne IPS_Create($id) Funktion
    public function Create(): void {
        // Diese Zeile nicht löschen.
        parent::Create();
    }

    // Überschreibt die interne IPS_ApplyChanges($id) Funktion
    public function ApplyChanges(): void {
        // Diese Zeile nicht löschen
        parent::ApplyChanges();
    }

    /**
    * Die folgenden Funktionen stehen automatisch zur Verfügung, wenn das Modul über die "Module Control" eingefügt wurden.
    * Die Funktionen werden, mit dem selbst eingerichteten Prefix, in PHP und JSON-RPC wie folgt zur Verfügung gestellt:
    *
    * ABC_MeineErsteEigeneFunktion($id);
    *
    */
    public function MeineErsteEigeneFunktion(): void {
        // Selbsterstellter Code
    }

}
Haben Sie noch Fragen?