Metadaten für Plugins
Plugins werden in der Datei ../etc/plugin.yaml
bzw. über die Admit GUI konfiguriert. Die Parameter sind in
der Dokumentation des Plugins beschrieben.
Ein Plugin besteht im minimum aus drei Dateien:
Der Plugin Code:
__init__.py
Die Metadaten:
plugin.yaml
und optional: Eine kurze Dokumentation:
user_doc.rst
Eine genaue Beschreibung welche weiteren Dateien und Unterverzeichnisse ein Plugin haben kann, ist im Abschnitt Entwicklung beschrieben.
Alle drei Dateien sind in einem Verzeichnis unterhalb von ../plugins
gespeichert, welches den Namen des
Plugins trägt (nur in Kleinbuchstaben).
Die Metadaten Datei eines Plugins heißt /plugins/<name of the plugin>/plugin.yaml
. Die bis zu sieben
Abschnitte, die im folgenden beschrieben sind.
additional sections:
plugin:
- Globale Metadaten des Pluginsparameters:
- Definition der Parameter, welche zur Konfiguration des Pluginsin der Datei../etc/plugin.yaml
benutzt werden könnenitem_attributes:
- Definition der Item Attribute, die durch das Plugin genutzt/unterstützt werdenitem_structs:
- Definition von Item Strukturen, welche im Zusammenhang mit dem Plugin genutzt werden könnenitem_attribute_prefixes:
- Definition von Item Attributen elche nur einen genmeinsamen Namens-Beginn habenlogic_parameters:
- Definition von Parameters welche steuern wie Logiken durch das Plugin genutzt/getriggert werden könnenplugin_functions:
- Beschreibung öffentlicher Funktionen des Plugins, die durch Logiken oder andere Plugins genutzt werden können
plugin
Der globale Metadaten Abschnitt plugin:
kennt die folgenden Schlüsselbegriffe:
# Metadata for the Smart-plugin
plugin:
# Global plugin attributes
type: web # plugin type (gateway, interface, protocol, system, cloud, un-classified)
description:
de: 'Plugin für ...'
en: 'Plugin for ...'
maintainer: msinn # Optional: Who maintains this plugin?
# tester: # Optional: Who tests this plugin?
state: qa-passed
keywords: weather # keywords, where applicable
documentation: https://github.com/smarthomeNG/... # url of additional wiki page (in addition to user_doc.rst of plugin
# support: https://knx-user-forum.de/forum/supportforen/smarthome-py # url of the support thread or forum
version: 1.4.3
sh_minversion: 1.7 # minimum shNG version to use this plugin (leave empty if no special requirement)
# sh_maxversion: # maximum shNG version to use this plugin (leave empty if latest)
# py_minversion: 3.6 # minimum Python version needed for this plugin (leave empty if no special requirement)
# py_maxversion: # maximum Python version to use this plugin (leave empty if no special requirement)
multi_instance: true # plugin supports multi instance (if not specified, False is assumed)
configuration_needed: true # False: The plugin will be enabled by the Admin GUI without configuration
classname: <plugin_class> # Name of the class that implements the plugin
Beschreibung der Schlüsselbegriffe im Abschnitt plugin:
type:
Beschreibt den Typ des Plugins (gültige Werte:gateway
,interface
,protocol
,system
,cloud
oder leer für ein nicht klassifiziertes Plugin
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
unden
müssen angegeben werden. Weitere Sprachen sind optional.
maintainer:
Hier kann angegeben werden, wer das Plugin pflegt und weiterentwickelt
tester:
Optional können hier die Nutzer angegeben werden, die sich bereit erklärt haben das Plugin zu testen
state:
Entwicklungs-Status des Plugins (gültige Werte:develop
,ready
,qa-passed
)
keywords:
Liste der Schlüsselwörter die das Plugin beschreiben (durch Leerzeichen getrennt)
documentation:
url die auf eine weiterführende Dokumentation verweist (damit sind nicht die Dateien user_doc.rst, developer_doc.rst oder die veraltete README.md gemeint)
support:
url die auf einen Support Thread oder ein Support Forum verweist
version:
VersionsNumber des Plugins. Sie wird beim Laden mit der Versionsnummer die im Code definierert ist verglichen.
sh_minversion:
Minimale SmartHomeNG Version mit der das Plugin kmpatibel ist. Falls sh_minversion` leer ist, nimmt SmartHomeNG an, dass das Plugin mit jeder älteren Version von SmartHomeNG kompatibel ist.
sh_maxversion:
Maximale SmartHomeNG Version mit der das Plugin kmpatibel ist. Falls sh_maxversion` leer ist, nimmt SmartHomeNG an, dass das Plugin mit jeder neueren Version von SmartHomeNG kompatibel ist.
py_minversion:
Minimale Python Version mit der das Plugin kmpatibel ist. Falls py_minversion` leer ist, nimmt SmartHomeNG an, dass das Plugin mit jeder älteren Python Version komatibel ist die von SmartHomeNG unterstützt wird.
py_maxversion:
Maximale Python Version mit der das Plugin kmpatibel ist. Falls py_maxversion` leer ist, nimmt SmartHomeNG an, dass das Plugin mit jeder neueren Python Version komatibel ist die von SmartHomeNG unterstützt wird.
multi_instance:
Ist das Plugin in der Lage in mehreren Instanzen gestartet zu werden? (True
,False
)
configuration_needed:
Normalerweise wird in der Admin GUI ein Plugin im Status disabled hinzugefügt und muss erst konfiguriert werden. Wenn dieser Parameter aufFalse
gesetzt wird, wird das Plugin im Statusenabled
hinzugefügt. Das ist sinnvoll bei Plugins, die ohne Konfiguration lauffähig sind. (True
,False
)
restartable:
Is the Plugin Restart bzw. Reload fählg? (gültige Werte:True
,False
,unknown
)
classname:
Name der Python Klasse die das Plugin implementiert un die zum Start des Plugins initialisiert wird
classpath:
Wird normalerweise nicht angegeben - Nur angeben, wenn das Plugin außerhalb des/plugins
Verzeichnisses gespeichert ist,
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: ...
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 Wertint
- ein ganzzahliger Wertscene
- ein ganzzahliger Wert im Bereich von 0 bis 63, der eine Szenen Nummer repräsentiertfloat
- ein numerischer Wert der Nachkommastellen enthalten darfnum
- das Equivalent zum Typ`float
str
- ein String`ip
- ein String, der einen Hostnamen, eine ipv4-Adresse oder eine ipv6-Adresse repräsentiertipv4
- ein String, der eine ipv4-Adresse repräsentiertipv6
- ein String, der eine ipv6-Adresse repräsentiertmac
- ein String, der eine MAC Adresse repräsentiertknx_ga
- ein string, der eine KNX Gruppen Adresse (z.B..: 31/7/255) repräsentiertfoo
- der universelle Datatyp
- Komplexe Datentypen:
dict
- ein Dictionarylist
- eine Liste bei der jedes Element vom Datentypfoo
istlist(len)
- eine Liste fester Länge bei der jedes Element vom Datentypfoo
ist und deren Anzahl Elementelen
istlist(subtype)
- eine Liste bei der jedes Element vom Datentypsubtype
ist 1 (z.B.:list(int)
orlist(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 1, 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 1, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.
1 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 Parametertype
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
unden
müssen angegeben werden. Weitere Sprachen sind optionalvalid_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. Fallsvalid_list_ci
angegeben ist, wird eine evtl spezifiziertevalid_list
ignoriert.valid_list_description:
Optional: Beschreibung der Werte, die invalid_list:
bzw.valid_list_ci:
spezifiziert sind. Falls definiert, mussvalid_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 Datentypenint
,pint
,float
,pfloat
,num
undscene
kann hier ein minimal Wert angegeben werdenvalid_max
Optional: Für die Datentypenint
,pint
,float
,pfloat
,num
undscene
kann hier ein maximal Wert angegeben werdenmandatory:
Optional: Falls aufTrue
gesetzt, muss dieser Wert konfiguriert werden, damit das Plugin/Modul geladen/initialisiert wird. Diese Einschränkung ist wirkungslos, falls ein Wert fürdefault:
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.
item_attributes
Der Abschnitt item_attributes:
hat für jedes definierte Item Attribut einen Unter-Abschnitt, der das Attribut genauer
beschreibt. Der Schlüssel des Unter-Abschnitts ist der Name des Attributes. Attributnamen sollten keine
Großbuchstaben und Sonderzeichen enthalten. Sie dürfen nicht mit einer Ziffer beginnen.
Die Definitionen im Abschnitt item_attributes:
werden für die Gültigkeitsprüfung der konfigurierten Werte in den
Konfigurationsdateien im Verzeichnis ../items
, sowie zur Dokumentation und in der Zukunft zur Konfiguration
in der Admin GUI benutzt.
item_attributes:
attribute1:
type: int
default: 1234
description:
de: 'Deutsche Beschreibung des Attributes'
en: 'English description of the attribute'
valid_list:
- 1234
- 2222
- 4321
attribute2:
type: ...
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 Wertint
- ein ganzzahliger Wertscene
- ein ganzzahliger Wert im Bereich von 0 bis 63, der eine Szenen Nummer repräsentiertfloat
- ein numerischer Wert der Nachkommastellen enthalten darfnum
- das Equivalent zum Typ`float
str
- ein String`ip
- ein String, der einen Hostnamen, eine ipv4-Adresse oder eine ipv6-Adresse repräsentiertipv4
- ein String, der eine ipv4-Adresse repräsentiertipv6
- ein String, der eine ipv6-Adresse repräsentiertmac
- ein String, der eine MAC Adresse repräsentiertknx_ga
- ein string, der eine KNX Gruppen Adresse (z.B..: 31/7/255) repräsentiertfoo
- der universelle Datatyp
- Komplexe Datentypen:
dict
- ein Dictionarylist
- eine Liste bei der jedes Element vom Datentypfoo
istlist(len)
- eine Liste fester Länge bei der jedes Element vom Datentypfoo
ist und deren Anzahl Elementelen
istlist(subtype)
- eine Liste bei der jedes Element vom Datentypsubtype
ist 1 (z.B.:list(int)
orlist(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 1, 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 1, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.
1 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 Parametertype
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
unden
müssen angegeben werden. Weitere Sprachen sind optionalvalid_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. Fallsvalid_list_ci
angegeben ist, wird eine evtl spezifiziertevalid_list
ignoriert.valid_list_description:
Optional: Beschreibung der Werte, die invalid_list:
bzw.valid_list_ci:
spezifiziert sind. Falls definiert, mussvalid_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 Datentypenint
,pint
,float
,pfloat
,num
undscene
kann hier ein minimal Wert angegeben werdenvalid_max
Optional: Für die Datentypenint
,pint
,float
,pfloat
,num
undscene
kann hier ein maximal Wert angegeben werdenmandatory:
Optional: Falls aufTrue
gesetzt, muss dieser Wert konfiguriert werden, damit das Plugin/Modul geladen/initialisiert wird. Diese Einschränkung ist wirkungslos, falls ein Wert fürdefault:
definiert ist.
Plugins ohne item-attributes
Falls ein Plugin keine Item Attribute hat, wird das durch den folgenden Eintrag in der
Datei plugin.yaml
angezeigt:
item_attributes: NONE
Hinweis
Bitte beachten, dass hier NONE
vollständig in Großbuchstaben geschrieben werden muss.
item_structs
Der Abschnitt item_structs:
erlaubt die Definition von Structure Templates, also von Sub-Trees von Items,
die an verschiedenen Stellen in den Item Tree eingefügt werden können.
Definitionen von item_structs:
haben das folgende Format:
item_structs:
struct1:
item1:
type: int
item2:
item3:
name: 'my item 3'
type: str
plg_attr1: 'plugin specific'
item4:
type: bool
initial_value: True
struct2:
... (sub-tree with item definitions)
Zur Konfiguration von SmartHomeNG werden diese structs durch die Angabe einer Referenz in den Item Tree eingefügt.
Das erfolgt in den Konfigurationsdateien für Items im Verzeichnis ../items
:
item_name_of_struct:
struct: <plugin name>.<struct name>
Falls struct1
des oben angegebenen Beispiels in einem Plugin mit dem Namen example_plugin
definiert wurde,
sieht die Konfiguration um die Structure einzufügen folgendermaßen aus:
item_name_of_struct:
struct: example_plugin.struct1
Geschachtelte Structuren
Beginnend mit SmartHomeNG v1.7 können Struktur Definitionen ineinander geschatelt werden.
Wie Items die eine Struktur mit dem struct
Attribut referenzieren, kann auch eine Struktur Definition eine
eine andere Struktur referenzieren. SmartHomeNG löst alle Struktur Referenzen in Strukturen auf, bevor der
Item Tree geladen wird.
Bemerkung
Bitte beachten: Wenn Sub-Struktur Referenzen aufgelöst werden, gibt es zwei Unterschiede in der Art wie Item Definitionen geladen werden. Diese Unterschiede werden nur sichtbar, falls Strukturen Item Attribute redefinieren.
Redefininieren von Attributen
Wenn Items definiert werden ist es möglich, das selbe Attribut eines Items in mehreren YAML Dateien zu definieren. Beim Einlesen der Item Definitionen „gewinnt“ die Attribut Definition die zuletzt eingelesen wurde.
In struct/sub-struct Definitionen hingegen, „gewinnt“ die erste Definition eines Attributes.
Beim auflösen von sub-structs soll normalerweise der übergeordnete Level gewinnen. Das ermöglicht es zm Beispiel
in einer Item Definition eine Attribut Definition zu überschreiben, welche in einer Structure bereits festgelegt wurde.
Damit das so erfolgt, muss das betreffende Attribut im Item in der Reihenfolge vor dem struct
Attribut definiert
werden. Falls das Attribut im Item erst nach dem struct
Attribut definiert wird, „gewinnt“ die Definition in der
Structure. Dieses Verhalten gilt analog beim verschachteln von Strukturen.
Redefininieren von list-Attributen
Wenn Attribute die redefiniert werden Listen sind, findet kein überschreiben der Definition statt. Stattdessen werden die Listen aneinander gehängt. Das geschieht in der Reihenfolge in der die Attribut Definitionen eingelesen werden.
Definitions for multi-instance plugins
Wenn ein Plugin Multi-Instance fähig ist, ist es wahrscheinlich, dass Item Strukturen Instanz-spezifische Attribute enthalten. In Item Definitionen wird bei solchen Attributen ‚@<instance-name>` an den Attribut Namen angefügt.
Um in Strukturen zu kennzeichnen, welche Attribute einen Instanz Namen hinzugefügt bekommen sollen, wird bei diesen
Attributen der konstante String @instance
hinzugefügt. Dieser String wird beim Aufbau des Item Trees durch den
realen Instanz Namen ersetzt.
item_structs:
struct1:
item1:
type: int
item2:
item3:
name: 'my item 3'
type: str
plg_attr1@instance: 'plugin specific'
item4:
type: bool
initial_value: True
In der Item Konfiguration in den Dateien im Verzeichnis ../items
wird der Instanz Name der Struktur mitgegeben.
Das sieht z.B. folgendermaßen aus:
item_name_of_struct:
struct: example_plugin.struct1
instance: plg_instance
Im geladenen Item (bei Verwendung der Admin GUI), wird item3
dann ein Attribut haben, das
plg_attr1@plg_instance
benannt ist.
Plugins ohne item-structs
Falls ein Plugin keine Item Attribute hat, wird das durch den folgenden Eintrag in der
Datei plugin.yaml
angezeigt:
item_structs: NONE
Hinweis
Bitte beachten, dass hier NONE
vollständig in Großbuchstaben geschrieben werden muss.
item_attribute_prefixes
Falls ein Plugin eine Reihe von Items definiert, deren vollständiger Name erst zur Konfigurationszeit bekannt ist,
werden diese Items durch ihren Namens-Anfang (Präfix) definiert. Diese Art von Item Definition (und damit auch dieser
Abschnitt der Metadaten) soll nur genutzt werden, wenn es unbedingt notwendig ist, wie zum Beispiel beim
stateengine
Plugin.
Der item_attribute_prefixes:
Abschnitt definiert die Items ansonsten analog zum Abschnitt item_attributes
.
Die Definitionen im Abschnitt item_attribute_prefixes:
werden für die Gültigkeitsprüfung der konfigurierten
Werte in den Konfigurationsdateien im Verzeichnis ../items
, sowie zur Dokumentation und in der Zukunft zur
Konfiguration in der Admin GUI benutzt.
item_attributes:
attribute1:
type: int
default: 1234
description:
de: 'Deutsche Beschreibung des Attributes'
en: 'English description of the attribute'
valid_list:
- 1234
- 2222
- 4321
attribute2:
type: ...
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 Wertint
- ein ganzzahliger Wertscene
- ein ganzzahliger Wert im Bereich von 0 bis 63, der eine Szenen Nummer repräsentiertfloat
- ein numerischer Wert der Nachkommastellen enthalten darfnum
- das Equivalent zum Typ`float
str
- ein String`ip
- ein String, der einen Hostnamen, eine ipv4-Adresse oder eine ipv6-Adresse repräsentiertipv4
- ein String, der eine ipv4-Adresse repräsentiertipv6
- ein String, der eine ipv6-Adresse repräsentiertmac
- ein String, der eine MAC Adresse repräsentiertknx_ga
- ein string, der eine KNX Gruppen Adresse (z.B..: 31/7/255) repräsentiertfoo
- der universelle Datatyp
- Komplexe Datentypen:
dict
- ein Dictionarylist
- eine Liste bei der jedes Element vom Datentypfoo
istlist(len)
- eine Liste fester Länge bei der jedes Element vom Datentypfoo
ist und deren Anzahl Elementelen
istlist(subtype)
- eine Liste bei der jedes Element vom Datentypsubtype
ist 1 (z.B.:list(int)
orlist(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 1, 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 1, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.
1 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 Parametertype
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
unden
müssen angegeben werden. Weitere Sprachen sind optionalvalid_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. Fallsvalid_list_ci
angegeben ist, wird eine evtl spezifiziertevalid_list
ignoriert.valid_list_description:
Optional: Beschreibung der Werte, die invalid_list:
bzw.valid_list_ci:
spezifiziert sind. Falls definiert, mussvalid_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 Datentypenint
,pint
,float
,pfloat
,num
undscene
kann hier ein minimal Wert angegeben werdenvalid_max
Optional: Für die Datentypenint
,pint
,float
,pfloat
,num
undscene
kann hier ein maximal Wert angegeben werdenmandatory:
Optional: Falls aufTrue
gesetzt, muss dieser Wert konfiguriert werden, damit das Plugin/Modul geladen/initialisiert wird. Diese Einschränkung ist wirkungslos, falls ein Wert fürdefault:
definiert ist.
Plugins ohne Attribut-Präfixe
Falls ein Plugin keine Item Attribut-Präfixe definiert, wird das durch den folgenden Eintrag in der
Datei plugin.yaml
angezeigt:
item_attribute_prefixes: NONE
Hinweis
Bitte beachten, dass hier NONE
vollständig in Großbuchstaben geschrieben werden muss.
logic_parameters
Die Daten der Logic Parameter werden für die Generierung der Dokumentation verwendet. Außerdem werden diese Parameter für die Konfiguration von Logiken in der Admin GUI verwendet. Falls die konfigurierten Daten nicht gültig sind, werden Warnungen in das Logfile von SmartHomeNG geschrieben.
Der Abschnitt logic_parameters:
enthält einen Abschnitt für jeden Parameter der für eine Logik verwendet
werden kann. Der Name dieses Unter-Abschnitts ist der Name des Parameters der Logik.
logic_parameters:
param1:
type: int
default: 1234
description:
de: 'Deutsche Beschreibung'
en: 'English description'
valid_list:
- 1234
- 2222
- 4321
param2:
type: ...
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 Wertint
- ein ganzzahliger Wertscene
- ein ganzzahliger Wert im Bereich von 0 bis 63, der eine Szenen Nummer repräsentiertfloat
- ein numerischer Wert der Nachkommastellen enthalten darfnum
- das Equivalent zum Typ`float
str
- ein String`ip
- ein String, der einen Hostnamen, eine ipv4-Adresse oder eine ipv6-Adresse repräsentiertipv4
- ein String, der eine ipv4-Adresse repräsentiertipv6
- ein String, der eine ipv6-Adresse repräsentiertmac
- ein String, der eine MAC Adresse repräsentiertknx_ga
- ein string, der eine KNX Gruppen Adresse (z.B..: 31/7/255) repräsentiertfoo
- der universelle Datatyp
- Komplexe Datentypen:
dict
- ein Dictionarylist
- eine Liste bei der jedes Element vom Datentypfoo
istlist(len)
- eine Liste fester Länge bei der jedes Element vom Datentypfoo
ist und deren Anzahl Elementelen
istlist(subtype)
- eine Liste bei der jedes Element vom Datentypsubtype
ist 1 (z.B.:list(int)
orlist(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 1, 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 1, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.
1 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 Parametertype
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
unden
müssen angegeben werden. Weitere Sprachen sind optionalvalid_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. Fallsvalid_list_ci
angegeben ist, wird eine evtl spezifiziertevalid_list
ignoriert.valid_list_description:
Optional: Beschreibung der Werte, die invalid_list:
bzw.valid_list_ci:
spezifiziert sind. Falls definiert, mussvalid_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 Datentypenint
,pint
,float
,pfloat
,num
undscene
kann hier ein minimal Wert angegeben werdenvalid_max
Optional: Für die Datentypenint
,pint
,float
,pfloat
,num
undscene
kann hier ein maximal Wert angegeben werdenmandatory:
Optional: Falls aufTrue
gesetzt, muss dieser Wert konfiguriert werden, damit das Plugin/Modul geladen/initialisiert wird. Diese Einschränkung ist wirkungslos, falls ein Wert fürdefault:
definiert ist.
Plugins ohne Logic Parameter
Falls ein Plugin keine Logik Parameter hat, wird das durch den folgenden Eintrag in der Datei plugin.yaml
angezeigt:
logic_parameters: NONE
Hinweis
Bitte beachten, dass hier NONE
vollständig in Großbuchstaben geschrieben werden muss.
plugin_functions
Dieser Abschnitt beschreibt die öffentlichen Funktionen, die in einem Plugin implementiert sind.
plugin_functions:
enthält einen Abschnitt für jede implementierte Funktion, die öffenlich (also von außerhalb
des Plugins aufrufbar) sein soll. Der Name des Abschnitts ist der Name der Funktion.
Jede Funktionsdefinition enhält einen Abschnitt parameters:
, welcher die Parameter der Funktion im Detail
beschreibt.
Die Definitionen im Abschnitt plugin_functions:
werden für die Erstellung der Dokumentation genutzt. In der
Zukunft sollen die Definitionen für die Konfiguration in der Admin GUI genutzt werden.
plugin_functions:
example_function:
type: str
description:
de: 'Deutsche Beschreibung der Funktion'
en: 'English description of the function'
parameters:
param1:
type: int
default: 1234
description:
de: 'Deutsche Beschreibung des Funktionsparameters'
en: 'English description of the function's parameter'
valid_list:
- 1234
- 2222
- 4321
param2:
type: ...
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 Wertint
- ein ganzzahliger Wertscene
- ein ganzzahliger Wert im Bereich von 0 bis 63, der eine Szenen Nummer repräsentiertfloat
- ein numerischer Wert der Nachkommastellen enthalten darfnum
- das Equivalent zum Typ`float
str
- ein String`ip
- ein String, der einen Hostnamen, eine ipv4-Adresse oder eine ipv6-Adresse repräsentiertipv4
- ein String, der eine ipv4-Adresse repräsentiertipv6
- ein String, der eine ipv6-Adresse repräsentiertmac
- ein String, der eine MAC Adresse repräsentiertknx_ga
- ein string, der eine KNX Gruppen Adresse (z.B..: 31/7/255) repräsentiertfoo
- der universelle Datatyp
- Komplexe Datentypen:
dict
- ein Dictionarylist
- eine Liste bei der jedes Element vom Datentypfoo
istlist(len)
- eine Liste fester Länge bei der jedes Element vom Datentypfoo
ist und deren Anzahl Elementelen
istlist(subtype)
- eine Liste bei der jedes Element vom Datentypsubtype
ist 1 (z.B.:list(int)
orlist(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 1, 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 1, wird der letzte angegebene subtype für alle weiteren Elemente verwendet.
1 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 Parametertype
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
unden
müssen angegeben werden. Weitere Sprachen sind optionalvalid_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. Fallsvalid_list_ci
angegeben ist, wird eine evtl spezifiziertevalid_list
ignoriert.valid_list_description:
Optional: Beschreibung der Werte, die invalid_list:
bzw.valid_list_ci:
spezifiziert sind. Falls definiert, mussvalid_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 Datentypenint
,pint
,float
,pfloat
,num
undscene
kann hier ein minimal Wert angegeben werdenvalid_max
Optional: Für die Datentypenint
,pint
,float
,pfloat
,num
undscene
kann hier ein maximal Wert angegeben werdenmandatory:
Optional: Falls aufTrue
gesetzt, muss dieser Wert konfiguriert werden, damit das Plugin/Modul geladen/initialisiert wird. Diese Einschränkung ist wirkungslos, falls ein Wert fürdefault:
definiert ist.
Plugins ohne Plugin Funktionen
Falls ein Plugin keine öffentlichen Plugin Funktionen definiert, wird das durch den folgenden Eintrag in
der Datei plugin.yaml
angezeigt:
plugin_functions: NONE
Hinweis
Bitte beachten, dass hier NONE
vollständig in Großbuchstaben geschrieben werden muss.
Funktionen ohne Parameter
Falls eine Plugin-Funktion keine Parameter hat, darf der Eintrag parameters:
nicht in die plugin.yaml aufgenommen werden. Er entfällt ohne weitere Angaben.
Aufruf von Funktionen
Wenn Plugin-Funktionen in einer Logik verwendet werden sollen, kann dies in der folgenden Form erfolgen:
result = sh.plugins.return_plugin("<Plugin-Name>").<Funktionsname>(<Argumente>)