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(**kwargs)

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

STOP_ON_ITEM_CHANGE = True

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)>

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

alive = False

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 for the plugin to be able to react to item changes.

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

Rückgabetyp:

None

parse_item(item)

This method is used to parse the configuration of an item for this plugin. It is called for each item before the plugins are started (calling all run methods). Copy code to own function; calling via super() does not work without bending three arms…

Note:

This method should be overwritten by the plugin implementation.

Rückgabetyp:

Any

poll_device()

periodically poll device (or do other things periodically)

Note:

This method can be overwritten by plugin implementation.

Rückgabetyp:

None

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.

Rückgabetyp:

None

deinit(items=[])

This method „deinitializes“ the plugin, i.e. prepares for unloading. The plugin is stopped and all (or all provided) items are un-registered.

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. Keep the original code or call super().deinit()…

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

Rückgabetyp:

None

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)

Rückgabetyp:

str

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

Rückgabetyp:

None

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:

list

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

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 (str) – key of the configdata dict used to filter

• filter_value (str) – value for filtering item_path_list

• mode (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='', filter_value='', mode='')

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 (str) – key of the configdata dict used to filter

• filter_value (str) – value for filtering item_path_list

• mode (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.

Rückgabetyp:

list

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

Rückgabetyp:

bool

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) – dict with the parameters that should be updated

Rückgabetyp:

None

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

Rückgabetyp:

None

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

Rückgabetyp:

object

path_join(path, dir)

Join an existing path and a directory

now()

Returns SmartHomeNGs current time (timezone aware)

scheduler_return_next(name)

Rückgabetyp:

Any

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

Rückgabetyp:

None

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

Rückgabetyp:

None

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

Rückgabetyp:

None

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

Rückgabetyp:

None

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

Rückgabetyp:

dict

scheduler_get_all()

This method returns a list of all added schedulers

scheduler_remove_all()

This method removes all schedulers added by the plugin

asyncio_state()

Returns the state of asyncio for the plugin

• ‚unused‘ - If the plugin does not use asyncio (the start_asyncio method has not been successfully executed)

• ‚running‘ - An active eventloop is beeing processed

• ‚stopped‘ - There is no active eventloop

Rückgabetyp:

str

Rückgabe:

‚unused‘ | ‚running‘ | ‚stopped‘

start_asyncio(plugin_coro)

Start the thread for the asyncio loop

The started asyncio thread sets up the asyncio environment and starts the eventloop. The given plugin_coro is added as the main task to the eventloop.

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

Parameter:

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

Rückgabetyp:

None

stop_asyncio()

stop the eventloop and the thread it is running in

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

Rückgabetyp:

None

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.

This method waits for the coroutine to be finished, to be able to return the result of the coroutine.

Parameter:

• coro (Coroutine) – A coroutine that should be run in the eventloop of the asyncio-thread

• return_exeption (bool) – If set to True, run_asyncio_coro returns exceptions instead of handling (logging) them itself

Rückgabetyp:

Any

return: The result of the coroutine

async wait_for_asyncio_termination()

Wait for the command to stop the plugin_coro

This is used to block the plugin_coro until the plugin should be stopped.

When the plugin should be stopped, a string ‚STOP‘ is written into the queue

Rückgabetyp:

None

put_command_to_run_queue(command)

Put an entry to the run-queue (if implemented in the plugin_coro)

Parameter:

command (str) – command to be executed by the plugin_coro

Rückgabetyp:

None

async get_command_from_run_queue()

Get an entry from the run-queue

When the plugin should be stopped, a string ‚STOP‘ is written into the queue and the plugin_coro can check for the string ‚STOP‘ and terminate itself.

Rückgabetyp:

str

Rückgabe:

First command from the queue

async list_asyncio_tasks()

Log a list of the tasks that are in the eventloop

The intention of this method is to support the plugin development/debugging. It can be called from the executor plugin or from the eval-syntax-checker of the admin gui

Rückgabetyp:

None

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

Returns translated text for class SmartPlugin

init_webinterface(WebInterface=None)

“ :rtype: bool

Initialize the web interface for this plugin

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