Class SmartPlugin

Die Klasse SmartPlugin implementiert die Basisklasse aller SmartPlugins. Die vorhandenen Methoden sind im Folgenden beschrieben.

Zusätzlich werden die Methoden der Klasse lib.utils.Utils vererbt.

class lib.model.smartplugin.SmartPlugin(*args, **kargs)

Bases: SmartObject, Utils

The class SmartPlugin implements the base class of all smart-plugins. The implemented methods are described below.

In addition the methods implemented in lib.utils.Utils are inherited.

PLUGIN_VERSION = ''

ALLOW_MULTIINSTANCE = None

shtime = None

Variable containing a pointer to the SmartHomeNG time handling object; is initialized during loading of the plugin; :Warning: Don’t change it

logger = <Logger lib.model.smartplugin (WARNING)>

alive = False

suspended = False

suspend(by=None)

sets plugin into suspended mode, no network/serial activity and no item changed

resume(by=None)

disabled suspended mode, network/serial connections are resumed

deinit(items=[])

If the Plugin needs special code to be executed before it is unloaded, this method has to be overwritten with the code needed for de-initialization

If called without parameters, all registered items are unregistered. items is a list of items (or a single Item() object).

add_item(item, config_data_dict={}, mapping=None, updating=False)

For items that are used/handled by a plugin, this method stores the configuration information that is individual for the plugin. The configuration information is/has to be stored in a dictionary

The configuration information can be retrieved later by a call to the method get_item_configdata(<item_path>)

If data is being received by the plugin, a mapping ( a ‚device-command‘ or matchstring) has to be specified as an optional 3rd parameter. This allows a reverse lookup. The method get_itemlist_for_mapping(<mapping>) returns a list of items for the items that have defined the <mapping>. In most cases, the list will have only one entry, but if multiple items should receive data from the same device (or command), the list can have more than one entry.

Calling this method for an item already stored in self._plg_item_dict can be used to change the „is_updating“ key to True, if it was False before and the updating parameter is True. Otherwise, nothing happens.

This method should be called from parse_item to register the item. If parse_item returns a reference to update_item, this method is called again by the Item instance itself to change the is_updating key.

Only available in SmartHomeNG versions v1.9.4 and up.

Parameter:

• item (Item) – item

• config_data_dict (dict) – Dictionary with the plugin-specific configuration information for the item

• mapping (str) – String identifing the origin (source/kind) of received data (e.g. the address on a bus)

• updating (bool) – Show if item updates from shng should be sent to the plugin

Rückgabe:

True, if the information has been added

Rückgabetyp:

bool

remove_item(item)

Remove configuration data for an item (and remove the item from the mapping’s list

Parameter:

item (Item) – item to remove

Rückgabe:

True, if the information has been removed

Rückgabetyp:

bool

callerinfo(caller, source)

update_item(item, caller=None, source=None, dest=None)

Item has been updated

This method is called, if the value of an item has been updated by SmartHomeNG. It should write the changed value out to the device (hardware/interface) that is managed by this plugin.

Method must be overwritten to be functional.

Parameter:

• item – item to be updated towards the plugin

• caller – if given it represents the callers name

• source – if given it represents the source

• dest – if given it represents the dest

register_updating(item)

Mark item in self._plg_item_dict as registered in shng for updating (usually done by returning self.update_item from self.parse_item)

NOTE: Items are added to _plg_item_dict by the item class as updating

by default. This could only be used if items were added manually as non-updating first. Registering them as updating usually only occurs via parse_item(), which in turn makes the item class add the item as updating.

Parameter:

item (item) – item object

get_item_config(item)

Returns the plugin-specific configuration information (config_data_dict) for the given item

Parameter:

item (item object or str) – item or item_path (str) to get config info for

Rückgabe:

dict with the configuration information for the given item

Rückgabetyp:

dict

get_item_mapping(item)

Returns the plugin-specific mapping that was defined by add_item()

Only available in SmartHomeNG versions v1.9.4 and up.

Parameter:

item (item object or str) – item or item_path (str) to get config info for

Rückgabe:

mapping string for that item

Rückgabetyp:

str

get_item_mapping_list()

Returns the plugin-specific mapping that was defined by add_item()

This method is implemented to support plugin development to be used with the eval syntax checker or the executor plugin

Only available in SmartHomeNG versions v1.10.0 and up.

Rückgabe:

mapping string for that item

Rückgabetyp:

str

get_item_path_list(filter_key=None, filter_value=None, mode=None)

Return list of stored item paths used by this plugin

Only available in SmartHomeNG versions v1.9.4 and up. Parameter ‚mode‘ only available in SmartHomeNG versions v1.10.0 and up.

Parameter:

• filter_key (Optional[str]) – key of the configdata dict used to filter

• filter_value (Optional[str]) – value for filtering item_path_list

• mode (Optional[str]) – Compare mode (‚start‘, ‚end‘) for comparing strings of different length, None oder ommitting does a standard compare

Rückgabetyp:

list

Rückgabe:

List of item pathes

get_item_list(filter_key=None, filter_value=None, mode=None)

Return list of stored items used by this plugin

Only available in SmartHomeNG versions v1.9.4 and up. Parameter ‚mode‘ only available in SmartHomeNG versions v1.10.0 and up.

Parameter:

• filter_key (Optional[str]) – key of the configdata dict used to filter

• filter_value (Optional[str]) – value for filtering item_path_list

• mode (Optional[str]) – Compare mode (‚start‘, ‚end‘) for comparing strings of different length, None oder ommitting does a standard compare

Rückgabetyp:

list

Rückgabe:

List of item objects

get_trigger_items()

Return list of stored items which were marked as updating

Only available in SmartHomeNG versions v1.9.4 and up.

get_items_for_mapping(mapping)

Returns a list of items that should receive data for the given mapping

Only available in SmartHomeNG versions v1.9.4 and up.

Parameter:

mapping (str) – mapping, for which the receiving items should be returned

Rückgabe:

List of items

Rückgabetyp:

list

get_mappings()

Returns a list containing all mappings, which have items associated with it

Only available in SmartHomeNG versions v1.9.4 and up.

Rückgabe:

List of mappings

Rückgabetyp:

list

unparse_item(item)

Ensure that changes to <item> are no longer propagated to this plugin

Parameter:

item (class Item) – item to unparse

get_configname()

return the name of the plugin instance as defined in plugin.yaml (section name)

Rückgabe:

name of the plugin instance as defined in plugin.yaml

Rückgabetyp:

str

get_shortname()

return the shortname of the plugin (name of it’s directory)

Rückgabe:

shortname of the plugin

Rückgabetyp:

str

get_instance_name()

Returns the name of this instance of the plugin

Rückgabe:

instance name

Rückgabetyp:

str

get_fullname()

return the full name of the plugin (shortname & instancename)

Rückgabe:

full name of the plugin

Rückgabetyp:

str

get_classname()

return the classname of the plugin

Rückgabe:

classname of the plugin

Rückgabetyp:

str

get_version(extended=False)

Return plugin version

Parameter:

extended (bool) – If True, returned version string contains (pv) if not the latest version is loaded

Rückgabe:

plugin version

Rückgabetyp:

str

is_multi_instance_capable()

Returns information if plugin is capable of multi instance handling

Rückgabe:

True: If multiinstance capable

Rückgabetyp:

bool

get_plugin_dir()

return the directory where the pluing files are stored in

Rückgabe:

name of the directory

Rückgabetyp:

str

get_info()

Returns a small plugin info like: class, version and instance name

Rückgabe:

plugin Info

Rückgabetyp:

str

get_parameter_value(parameter_name)

Returns the configured value for the given parameter name

If the parameter is not defined, None is returned

Parameter:

parameter_name (str) – Name of the parameter for which the value should be retrieved

Rückgabe:

Configured value

Rückgabetyp:

depends on the type of the parameter definition

get_parameter_value_for_display(parameter_name)

Returns the configured value for the given parameter name

If the parameter is not defined, None is returned If the parameter is marked as ‚hide‘, only ‚*‘s are returned

Parameter:

parameter_name (str) – Name of the parameter for which the value should be retrieved

Rückgabe:

Configured value

Rückgabetyp:

depends on the type of the parameter definition

update_config_section(param_dict)

Update the config section of ../etc/plugin.yaml

Parameter:

param_dict – dict with the parameters that should be updated

Rückgabe:

get_loginstance()

Returns a prefix for logmessages of multi instance capable plugins.

The result is an empty string, if the instancename is empty. Otherwise the result is a string containing the instance name preseeded by a ‚@‘ and traild by ‚: ‚.

This way it is easy to show the instance name in log messages. Just write

self.logger.info(self.get_loginstance()+“Your text“)

and the logmessage is preseeded by the instance name, if needed.

Rückgabe:

instance name for logstring

Rückgabetyp:

str

has_iattr(conf, attr)

checks item configuration for an attribute

Parameter:

• conf (str) – item configuration

• attr (str) – attribute name

Rückgabetyp:

bool

Rückgabe:

True, if attribute is in item configuration

get_iattr_value(conf, attr, default=None)

Returns value for an attribute from item config

Parameter default is only available in SmartHomeNG versions v1.10.0 and up.

Parameter:

• conf (str) – item configuration

• attr (str) – attribute name

• default – Return-value, if attribute is not found

Rückgabetyp:

str

Rückgabe:

value of an attribute

set_attr_value(conf, attr, value)

Set value for an attribute in item configuration

Parameter:

• conf (str) – item configuration

• attr (str) – attribute name

• value (str) – value to set the atteibute to

get_sh()

Return the main object of smarthomeNG (usually refered to as smarthome or sh) You can reference the main object of SmartHomeNG by using self.get_sh() in your plugin

Rückgabe:

the main object of smarthomeNG (usually refered to as smarthome or sh)

Rückgabetyp:

object

get_module(modulename)

Test if module http is loaded and if loaded, return a handle to the module

path_join(path, dir)

Join an existing path and a directory

parse_logic(logic)

This method is used to parse the configuration of a logic for this plugin. It is called for all plugins before the plugins are started (calling all run methods).

Note:

This method should to be overwritten by the plugin implementation.

parse_item(item)

This method is used to parse the configuration of an item for this plugin. It is called for all plugins before the plugins are started (calling all run methods).

Note:

This method should be overwritten by the plugin implementation.

now()

Returns SmartHomeNGs current time (timezone aware)

scheduler_return_next(name)

scheduler_trigger(name, obj=None, by=None, source=None, value=None, dest=None, prio=3, dt=None)

This methods triggers the scheduler entry for a plugin-scheduler

A plugin identification is added to the scheduler name

The parameters are identical to the scheduler.trigger method from lib.scheduler

scheduler_add(name, obj, prio=3, cron=None, cycle=None, value=None, offset=None, next=None)

This methods adds a scheduler entry for a plugin-scheduler

A plugin identification is added to the scheduler name

The parameters are identical to the scheduler.add method from lib.scheduler

scheduler_change(name, **kwargs)

This methods changes a scheduler entry of a plugin-scheduler

A plugin identification is added to the scheduler name

The parameters are identical to the scheduler.change method from lib.scheduler

scheduler_remove(name)

This methods removes a scheduler entry of a plugin-scheduler

A plugin identifiction is added to the scheduler name

The parameters are identical to the scheduler.remove method from lib.scheduler

scheduler_get(name)

This methods gets a scheduler entry of a plugin-scheduler

A plugin identifiction is added to the scheduler name

The parameters are identical to the scheduler.get method from lib.scheduler

run_queue = None

start_asyncio(plugin_coro)

Start the thread for the asyncio loop

The started asyncio thread sets up the asyncio environment and starts the evemtloop. This routine is to be called from the plugin’s run() method

Parameter:

plugin_coro – The asyncio coroutine which implements the async part of the plugin

stop_asyncio()

stop the eventloop and the thread it is running in

This routine is to be called from the plugin’s stop() method

run_asyncio_coro(coro, return_exeption=False)

Run a coroutine in the eventloop of the plugin

When the asyncio eventloop of the plugin is running, this method can be used to add a coroutine to the eventloop from the part of the plugin which is thread operated. E.g.: This can be used in the plugins update_item() method to send data to the device through an asyncio package

Parameter:

coro – A coroutine that should be run in the eventloop of the asyncio-thread

async list_asyncio_tasks()

Log al list of the tasks that are in the eventloop

run()

This method of the plugin is called to start the plugin

Note:

This method needs to be overwritten by the plugin implementation. Otherwise an error will be raised

stop()

This method of the plugin is called to stop the plugin when SmartHomeNG shuts down

Note:

This method needs to be overwritten by the plugin implementation. Otherwise an error will be raised

translate(txt, vars=None, block=None)

Returns translated text for class SmartPlugin

init_webinterface(WebInterface=None)

“ Initialize the web interface for this plugin

This method is only needed if the plugin is implementing a web interface