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