Core modules

Theare are loadable modules (SmartHomeNG modules) that can be used when developping plugins. They implement additional functionality that is not implemented in the core itself.

Modules are configured in etc/modules.yaml. The parameters are described in the README.md files of the modules.

At the moment, the following modules exist:

A module is made up of two files:

  • The program code: __init__.py
  • The metadata: module.yaml

Both files reside in a folder within the /modules folder. The name of the folder reflects the name of the module.

The metadata file is named /modules/<name of the module>/module.yaml. It has two main sections:

  • module: - Global metadata of the module
  • parameters: - Definition of the parameters that can bei used in /etc/module.yaml to configure the module

Metadata section module:

The global metadata section module: has the following keys:

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

Description of the keys in the section module:

  • classname: Name of the Python class to initialize
  • version: Version number of the module. It is checked against the version number defined in the Python source code
  • sh_minversion: Minimum SmartHomeNG version this module is compatible with. If sh_minversion is left empty, SmartHomeNG assumes that the module is compatible with every version of SmartHomeNG [Test not yet implemented]
  • sh_maxversion: Maximum SmartHomeNG version this module is compatible with (or empty, if compatible with the actual version of SmartHomeNG) [Test not yet implemented]
  • description: Multilanguage Text describing what the module does. - 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, ..)
  • classpath: Usually not specified. Only needed, if the module resides outside the /modules 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.

xxxxxx