Module

Ladbare Code Module (SmartHomeNG Module) stellen zusätzliche Funktionalitäten zur Verfügung, die zur Programmierung von Plugins und Logiken genutzt werden können. Sie implementieren Funktionalitäten, die nicht unbedingt benötigt werden und deshalb nicht direkt im Core implementiert und zwangsweise geladen werden.

Module werden in der Datei ../etc/modules.yaml oder in der Admin GUI konfiguriert. Die Parameter sind in der jeweiligen README.md beschrieben.

Bisher existieren die folgenden Module:

Ein Modul besteht aus mindestens zwei Dateien:

dem Programm Code: __init__.py
den Metadaten: module.yaml

Beide Dateien lliegen in einem Unterordnet des Ordners ../modules und dieser Unterordnet trägt den Namen des Mooduls.

Metadaten

Die Metadaten Datei trägt den Namen ../modules/<name of the module>/module.yaml. Sie hat zwei Haupt Abschnitte:

module: - Globale Metadaten des Moduls
parameters: - Definition der Parameter welche in ../etc/module.yaml zur Konfiguration des Moduls genutzt werden können.

module

Der globale Metadaten Abschnitt module: kennt die folgenden Schlüsselbegriffe:

# Metadata for the module
module:
    # Global module attributes
    classname: Http
    version: 1.4.3
#    sh_minversion: 1.7          # minimum shNG version to use this module (leave empty if no special requirement)
#    sh_maxversion:              # maximum shNG version to use this module (leave empty if latest)
#    py_minversion: 3.6          # minimum Python version needed for this module (leave empty if no special requirement)
#    py_maxversion:              # maximum Python version to use this module (leave empty if no special requirement)
    description:
        de: 'Modul zur Implementierung von Backend-Webinterfaces für Plugins'
        en: 'Module for implementing a backend-webinterface for plugins'

Beschreibung der Schlüsselbegriffe im Abschnitt module:

classname: Name der Python Klasse die das Modul implementiert un die zum Start des Moduls initialisiert wird

version: VersionsNumber des Moduls. Sie wird beim Laden mit der Versionsnummer die im Code definierert ist verglichen.

sh_minversion: Minimale SmartHomeNG Version mit der das Modul kmpatibel ist. Falls sh_minversion` leer ist, nimmt SmartHomeNG an, dass das Modul mit jeder älteren Version von SmartHomeNG kompatibel ist.

sh_maxversion: Maximale SmartHomeNG Version mit der das Modul kmpatibel ist. Falls sh_maxversion` leer ist, nimmt SmartHomeNG an, dass das Modul mit jeder neueren Version von SmartHomeNG kompatibel ist.

py_minversion: Minimale Python Version mit der das Modul kmpatibel ist. Falls py_minversion` leer ist, nimmt SmartHomeNG an, dass das Modul mit jeder älteren Python Version komatibel ist die von SmartHomeNG unterstützt wird.

py_maxversion: Maximale Python Version mit der das Modul kmpatibel ist. Falls py_maxversion` leer ist, nimmt SmartHomeNG an, dass das Modul mit jeder neueren Python Version komatibel ist die von SmartHomeNG unterstützt wird.

description: Mehrsprachiger Text, der die Funktion das Plugins beschreibt. Die Beschreibung wird bei der Generierung des Dokumentations-Seiten des Plugins verwendet - Die Texte in den verschiedenen Sprachen werden als Unter-Einträge in der Form <Sprache>: <Text> erfasst. Zur Identifikation der Sprache werden die 2-stelligen Länder-Kürzel verwendet (de, en, fr, pl, …)

de und en müssen angegeben werden. Weitere Sprachen sind optional.

parameters

Parameter-Metadaten werden benutzt um die Gültigkeit von Parametern zu prüfen, die im Verzeichnis ../etc konfiguriert wurden. Falls für einen Parameter ein ungültiger Wert konfiguriert wurde, wird eine Warnung im Logfile von SmartHomeNG eingetragen.

Wenn ein gültiger Wert konfiguriert wurde, wird der Parameter an das Plugin/Modul übergeben, und zwar als der Datentyp, der in den Metadaten definiert wurde.

Der parameters: Abschnitt hat für jeden definierten Parameter einen Unter-Abschnitt, der den Parameter genauer beschreibt. Der Schlüssel des Unter-Abschnitts ist der Name des Parameters. Parameter Namen sollten keine Großbuchstaben und Sonderzeichen enthalten. Sie dürfen nicht mit einer Ziffer beginnen.

Die Definitionen im Abschnitt parameters: werden für die Gültigkeitsprüfung der konfigurierten Werte, sowie zur Dokumentation und zur Konfiguration in der Admin GUI benutzt.

parameters:
    param1:
        type: int
        default: 1234
        description:
            de: 'Deutsche Beschreibung'
            en: 'English description'
        valid_list:
          - 1234
          - 2222
          - 4321

    param2:
        type: ...

Hinweis

Der Parameter webif_pagelength wird jedem Plugin automatisch hinzugefügt und sollte daher NICHT manuell im plugin.yaml File hinterlegt werden.

Beschreibung der Schlüssel im Abschnitt für einen Parameter bzw. ein Attribut:

type: Beschreibt den Datatyp des Parameters bzw. Attributes. Gültige Datentypen sind:
Einfache Datentypen:
bool - ein boolscher Wert

int - ein ganzzahliger Wert

scene - ein ganzzahliger Wert im Bereich von 0 bis 63, der eine Szenen Nummer repräsentiert

float - ein numerischer Wert der Nachkommastellen enthalten darf

num - das Equivalent zum Typ `float

str - ein String`

ip - ein String, der einen Hostnamen, eine ipv4-Adresse oder eine ipv6-Adresse repräsentiert

ipv4 - ein String, der eine ipv4-Adresse repräsentiert

ipv6 - ein String, der eine ipv6-Adresse repräsentiert

mac - ein String, der eine MAC Adresse repräsentiert

knx_ga - ein string, der eine KNX Gruppen Adresse (z.B..: 31/7/255) repräsentiert

foo - der universelle Datatyp
Komplexe Datentypen:
dict - ein Dictionary

list - eine Liste bei der jedes Element vom Datentyp foo ist

list(len) - eine Liste fester Länge bei der jedes Element vom Datentyp foo ist und deren Anzahl Elemente len ist

list(subtype) - eine Liste bei der jedes Element vom Datentyp subtype ist ¹ (z.B.: list(int) or list(ipv4))

list(subtype, subtype, ...) - eine Liste bei der jedes Element von einem angegebenen Datentyp ist. Falls die Liste länger ist als die Anzahl angegebener subtypes ¹, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.

list(len,subtype, subtype, ...) - eine Liste fester Länge bei der bei der für jedes Element ein subtype angegeben wird. Falls die Liste länger ist als die Anzahl angegebener subtypes ¹, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.

¹ subtype kann nur ein einfacher Datentyp sein
gui_type: Optional: Spezifiziert genauer, wie der Parameter in der Admin GUI shngadmin behandelt werden soll. Die Handhabung der Parameter in der Admin GUI wird durch den Parameter type bestimmt. type ist jedoch auf die Datentypen beschränkt, die SmartHomeNG kennt. Für das Editieren kann es jedoch wünschenswert sein, unterschiedlche Feld-Editoren für den selben Datentyp zu verwenden.

Bisher werden nur zwei Werte für gui_type unterstützt:
- wide_str wird benutzt, um ein breiteres Editor Feld zu verwenden (z.B. für Strings die einen längeren Inhalt haben können/sollen.
- readonly wird benutzt, wenn der Parameter nicht in der GUI konfiguriert werden soll, z.B. wenn das Webinterface des Plugins diesen Parameter konfiguriert.
default: Optional: Gibt einen Standardwert vor, der verwendet wird, falls bei der Konfiguration des Parameters in ../etc/plugin.yaml bzw. ../etc/module.yaml kein Wert angegeben wird.
description: Mehrsprachiger Text, der die Funktion das Plugins beschreibt. Die Beschreibung wird bei der Generierung des Dokumentations-Seiten des Plugins verwendet - Die Texte in den verschiedenen Sprachen werden als Unter-Einträge in der Form <Sprache>: <Text> erfasst. Zur Identifikation der Sprache werden die 2-stelligen Länder-Kürzel verwendet (de, en, fr, pl, …)

de und en müssen angegeben werden. Weitere Sprachen sind optional
valid_list: Optional: Liste der erlaubten Werte für den Parameter (case sensitive)
valid_list_ci: Optional: Liste der erlaubten Werte für den Parameter (nicht case sensitive) Der Wert wird dem Plugin/Modul in lower case übergeben. Falls valid_list_ci angegeben ist, wird eine evtl spezifizierte valid_list ignoriert.
valid_list_description: Optional: Beschreibung der Werte, die in valid_list: bzw. valid_list_ci: spezifiziert sind. Falls definiert, muss valid_list_description: Sub-Keys haben, um die Beschreibung in mehreren Sprachen (de, en, fr, pl, …) anzugeben.

Jeder Sprach-Sub-Key muss eine Liste sein, die für jeden Eintrag in valid_list eine Beschreibung enthält.
valid_min: Optional: Für die Datentypen int, pint, float, pfloat, num und scene kann hier ein minimal Wert angegeben werden
valid_max Optional: Für die Datentypen int, pint, float, pfloat, num und scene kann hier ein maximal Wert angegeben werden
mandatory: Optional: Falls auf True gesetzt, muss dieser Wert konfiguriert werden, damit das Plugin/Modul geladen/initialisiert wird. Diese Einschränkung ist wirkungslos, falls ein Wert für default: definiert ist.

Plugins/Module ohne Parameter

Falls ein Plugin oder Modul keine Parameter hat, wird das durch den folgenden Eintrag in der Datei plugin.yaml angezeigt:

parameters: NONE

Hinweis

Bitte beachten, dass hier NONE vollständig in Großbuchstaben geschrieben werden muss.

Falls ein Modul ein Python Package nutzt, welches nicht in der Standardinstallation von Python enthalten ist, muss diese Anforderung in der Datei ../modules/<name of the module>/requirements.txt dokumentiert werden.