Plugin Metadata update

Plugins are configured in etc/plugin.yaml. The parameters are described in the README.md files of the plugins.

A plugin is made up of three files:

  • The program code: __init__.py
  • The metadata: plugin.yaml
  • A short documentation: README.md

All three files reside in a folder within the /plugins folder. The name of the folder reflects the name of the plugin.

The metadata file is named /plugins/<name of the plugin>/plugin.yaml. It has three main sections:

  • plugin: - Global metadata of the plugin The data defined in this section is used to check if the plugin works with the running version of SmartHomeNG, and defines how the plugin is loaded. The description: data is used to generate the plugin documentation pages within this documentation. Since this documentation is in english, the english description is read. If no english description is found, the german description is used.
  • parameters: - Definition of the parameters that can bei used in /etc/plugin.yaml to configure the plugin The data defined in this section is used to check if configured parameters are valid. The description:` data is going to be used in the future: - for generating documentation pages (that way the parameter descriptions will not be needed in the README.md file) - for guiding users in a graphical configuration utility
  • item_attributes: - In the future: Definition of the additional attributes for items, defined by this plugin The data defined in this section is used to check if configured item attributes are valid. The description:` data is going to be used in the future: - for generating documentation pages (that way the item attribute descriptions will not be needed in the README.md file) - for guiding users in a graphical configuration utility
Note:

After the completion of the implementation of metadata for plugins, the following variables in the Python code of SmartPlugins need not be set anymore. They are read from the global metadata and are automatically set in the instance of the plugin:

  • ALLOW_MULTIINSTANCE
  • PLUGIN_VERSION

The variable PLUGIN_VERSION should be set (even if it is not needed). If it is set, the version numbers defined in __init__.py and plugin.yaml are compared to ensure they match. If they don’t match, an error is logged and the plugin is not loaded.

Metadata section plugin:

The global metadata section plugin: has the following keys:

# 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?
    keywords: weather           # keywords, where applicable
    documentation: https://github.com/smarthomeNG/...        # url of additional wiki page (in addition to README.md 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.3a
#    sh_maxversion:              # maximum shNG version to use this plugin (leave empty if latest)
    multi_instance: true        # plugin supports multi instance (if not specified, False is assumed)

    classname: <plugin_class>   # Name of the class that implements the plugin

Description of the keys in the section plugin:

  • type: The plugin type (classification: gateway, interface, protocol, system, cloud, or empty for un-classified
  • description: Multilanguage Text describing what the plugin does. It is used for generating the plugin pages within this documentation - The texts in the different languages are specified in sub-entries in the form <language>: <text>. Use the standard two letter codes for specifying the language (de, en, fr, pl, ..)
  • maintainer: Who maintains the plugin?
  • tester: Optional: List of testers of the plugin
  • keywords: List of keywords (space separated)
  • documentation: url pointing to additional information/documentation (besides the README.md file)
  • support: url pointing to a support thread or forum
  • version: Version number of the plugin. It is checked against the version number defined in the Python source code
  • sh_minversion: Minimum SmartHomeNG version this plugin is compatible with. If sh_minversion is left empty, SmartHomeNG assumes that the plugin is compatible with every version of SmartHomeNG [Test not yet implemented]
  • sh_maxversion: Maximum SmartHomeNG version this plugin is compatible with (or empty, if compatible with the actual version of SmartHomeNG) [Test not yet implemented]
  • multi_instance: Is the plugin multi-instance capable?
  • classname: Name of the Python class to initialize (the class that implements the plugin)
  • classpath: Usually not specified. Only needed, if the plugin resides outside the /plugins folder

Metadata section parameters:

Parameter metadata is used to check if the configured parameters in /etc are valid. If the configured data is not valid, warnings are logged in the logfile of SmartHomeNG.

If the configuration is valid, the parameters are handed over to the plugin/module through a dict, that contains a value for each parameter (defined in the metadata file). The datatype of those values correspond to the type-definitions in the metadata.

Metadata is supported in SmartHomeNG v1.4 and up.

The parameters: section has a section for each parameter that is implemented. The name of that section is the name of the parameter.

The definitions in the parameters: section are used for validity checking of the plugin/module configuration. In the future the definitions will be used for a configuration tool for SmartHomeNG.

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

    param2:
        type: ...

Description of the keys in the section of a parameter/attribute:

  • type: specifies the datatype of the parameter/attribute. Valid datatypes are:

    Simple datatypes:
    • bool - a boolean value
    • int - an integer vaue
    • scene - an integer in the range between 0 and 255, representing a scene number
    • float - a float value
    • num - an equivalent to float
    • str - a string
    • ip - a string, representing a hostname, an ipv4-address or an ipv6-address
    • ipv4 - a string, representing strictly an ipv4-address
    • ipv6 - a string, representing strictly an ipv6-address
    • mac - a string, representing a mac-address
    • knx_ga - a string, representing a KNX group address (eg.: 31/7/255)
    • foo - the universal datatype
    Complex datatypes:
    • dict - a dictionary
    • list - a list with each entry of the datatype foo
    • list(len) - a list of a fixed length len must be an integer value > 0
    • list(subtype) - a list with each entry of the same specified subtype 1 (e.g: list(int) or list(ipv4))
    • list(subtype, subtype, …) - a list with each entry of a specified type. If the list is longer than the given list of subtypes 1, the last given subtype will be used for all subsequent list entries.
    • list(len,subtype, subtype, …) - a list of a fixed length with each entry of a specified type. If the list is longer than the given list of subtypes 1 the last given subtype will be used for all subsequent list entries.

    1 subtype can only be a simple datatype

  • default: Optional: Specifies the default value to be used, if no value is given in in the configuration file /etc/plugin.yaml or /etc/module.yaml

  • description: is a multilanguage text. - The texts in the different languages are specified in sub-entries in the form <language>: <text>. Use the standard two letter codes for specifying the language (de, en, fr, pl, ..)

  • valid_list: Optional: List of allowed values for the parameter

  • valid_min: Optional: For datatypes int, pint, float, pfloat, num and scene: minimum allowed value for the parameter

  • valid_max: Optional: For datatypes int, pint, float, pfloat, num and scene: maximum allowed value for the parameter

  • mandatory: Optional: If set to True, a value must be configured for the plugin/module to get loaded an initialized. If a value for a parameter that is marked as mandatory is missing, the plugin will not be loaded.

Metadata section item_attributes:

The item_attributes: section has a section for each attribute that is additionally implemented for am item. The name of that section is the name of the attribute.

For the configuration of SmartHomeNG these attributes are configured in the item configuration files in the /items folder.

The definitions in the item_attributes: section are used in the future for a configuration tool for SmartHomeNG.

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

Description of the keys in the section of a parameter/attribute:

  • type: specifies the datatype of the parameter/attribute. Valid datatypes are:

    Simple datatypes:
    • bool - a boolean value
    • int - an integer vaue
    • scene - an integer in the range between 0 and 255, representing a scene number
    • float - a float value
    • num - an equivalent to float
    • str - a string
    • ip - a string, representing a hostname, an ipv4-address or an ipv6-address
    • ipv4 - a string, representing strictly an ipv4-address
    • ipv6 - a string, representing strictly an ipv6-address
    • mac - a string, representing a mac-address
    • knx_ga - a string, representing a KNX group address (eg.: 31/7/255)
    • foo - the universal datatype
    Complex datatypes:
    • dict - a dictionary
    • list - a list with each entry of the datatype foo
    • list(len) - a list of a fixed length len must be an integer value > 0
    • list(subtype) - a list with each entry of the same specified subtype 1 (e.g: list(int) or list(ipv4))
    • list(subtype, subtype, …) - a list with each entry of a specified type. If the list is longer than the given list of subtypes 1, the last given subtype will be used for all subsequent list entries.
    • list(len,subtype, subtype, …) - a list of a fixed length with each entry of a specified type. If the list is longer than the given list of subtypes 1 the last given subtype will be used for all subsequent list entries.

    1 subtype can only be a simple datatype

  • default: Optional: Specifies the default value to be used, if no value is given in in the configuration file /etc/plugin.yaml or /etc/module.yaml

  • description: is a multilanguage text. - The texts in the different languages are specified in sub-entries in the form <language>: <text>. Use the standard two letter codes for specifying the language (de, en, fr, pl, ..)

  • valid_list: Optional: List of allowed values for the parameter

  • valid_min: Optional: For datatypes int, pint, float, pfloat, num and scene: minimum allowed value for the parameter

  • valid_max: Optional: For datatypes int, pint, float, pfloat, num and scene: maximum allowed value for the parameter

  • mandatory: Optional: If set to True, a value must be configured for the plugin/module to get loaded an initialized. If a value for a parameter that is marked as mandatory is missing, the plugin will not be loaded.