Logics-API

There are two ways to access the API

1. Directly

   Use it the following way to access the api, if you have no access to the sh object in your method or function:

   # to get access to the object instance:
   from lib.logic import Logics
   logics = Logics.get_instance()
   
   # to access a method (eg. enable_logic()):
   logics.enable_logic(name)
   

2. Through the main SmartHome object

   If you have access to the sh object in your method or function, you can use the following way:

   # to access a method (eg. enable_logic()):
   sh.logics.enable_logic(name)
   

The API is implemented through the following library:

lib.logic

This library implements logics in SmartHomeNG.

The main class Logics implements the handling for all logics. This class has a couple of static methods. These methods implement the API for handling logics from within SmartHomeNG and from plugins. This API enables plugins to configure new logics or change the configuration of existing plugins.

Each logic is represented by an instance of the class Logic.

The methods of the class Logics implement the API for logics. They can be used the following way: To call eg. enable_logic(name), use the following syntax:

from lib.logic import Logics
logics = Logics.get_instance()

# to access a method (eg. enable_logic()):
logics.enable_logic(name)

Note:

Do not use the functions or variables of the main smarthome object any more. They are deprecated. Use the methods of the class Logics instead.

Note:

This library is part of the core of SmartHomeNG. Regular plugins should not need to use this API. It is manily implemented for plugins near to the core like backend or blockly!

class lib.logic.Logics(smarthome, userlogicconf, envlogicconf)

Bases: object

This is the main class for the implementation og logics in SmartHomeNG. It implements the API for the handling of those logics.

plugins = None

scheduler = None

return_logics()

Returns a list with the names of all loaded logics

Rückgabe:

list of logic names

Rückgabetyp:

list

get_loaded_logics()

Returns a list with the names of all loaded logics

Rückgabe:

list of logic names

Rückgabetyp:

list

static get_instance()

Returns the instance of the Logics class, to be used to access the logics-api

Use it the following way to access the api:

from lib.logic import Logics
logics = Logics.get_instance()

# to access a method (eg. enable_logic()):
logics.enable_logic(name)

Rückgabe:

logics instance

Rückgabetyp:

object or 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 logic-scheduler

A plugin identifiction 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 logic-scheduler

scheduler_remove(name)

This methods rmoves a scheduler entry of a logic-scheduler

A plugin identifiction is added to the scheduler name

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

get_logics_dir()

Returns the path of the dirctory, where the user-logics are stored

Rückgabe:

path to logics directory

Rückgabetyp:

str

reload_logics()

Function to reload all logics

It generates new bytecode for every logic that is loaded. The configured triggers are not loaded from the configuration, so the triggers that where active before the reload remain active.

is_logic_loaded(name)

Test if a logic is loaded. Given is the name of the section in /etc/logic.yaml

Parameter:

name (str) – logic name (name of the configuration section section)

Rückgabe:

True: Logic is loaded

Rückgabetyp:

bool

return_logic(name)

Returns (the object of) one loaded logic with given name

Parameter:

name (str) – name of the logic to get

Rückgabe:

object of the logic

Rückgabetyp:

object

get_logic_info(name, ordered=False)

Returns a dict with information about the logic

Parameter:

name (str) – name of the logic to get info for

Rückgabe:

information about the logic

Rückgabetyp:

dict

visu_access(name)

Return if visu may access the logic

is_logic_enabled(name)

Returns True, if the logic is enabled

enable_logic(name)

Enable a logic

disable_logic(name)

Disable a logic

toggle_logic(name)

Toggle a logic (Invert the enabled/disabled state)

trigger_logic(name, by='unknown', source=None, value=None)

Trigger a logic

is_userlogic(name)

Returns True if userlogic and False if systemlogic or unknown

load_logic(name)

Load a specified logic

Load a logic as defined in the configuration section. After loading the logic’s code, the defined schedules and/or triggers are set.

If a logic is already loaded, it is unloaded and then reloaded.

Parameter:

name (str) – Name of the logic (name of the configuration section)

Rückgabe:

Success

Rückgabetyp:

bool

unload_logic(name)

Unload a specified logic

This function unloads a logic. Before unloading, it remove defined schedules and triggers for watch_item s.

Parameter:

name (str) – Name of the section that defines the logic in the configuration file

get_logiccrontab(name)

Return the crontab string of a logic

return_logictype(name)

Returns the type of a specified logic (Python, Blockly, None)

Parameter:

name (str) – Name of the logic (name of the configuration section)

Rückgabe:

Logic type (‚Python‘, ‚Blockly‘ or None)

Rückgabetyp:

str or None

return_defined_logics(withtype=False)

Returns the names of defined logics from file /etc/logic.yaml as a list

If withtype is specified and set to True, the function returns a dict with names and logictypes (‚Python‘, ‚Blockly‘)

Parameter:

withtype (bool) – If specified and set to True, the function will additionally return the logic types

Rückgabe:

list of defined logics or dict of defined logics with type

Rückgabetyp:

list or dict

return_loaded_logics()

Returns a list with the names of all logics that are currently loaded

Rückgabe:

list of logic names

Rückgabetyp:

list

return_config_type()

Return the used config type

After initialization this function returns ‚.conf‘, if the used logic configuration file in /etc is in the old file format or ‚.yaml‘ if the used configuration file is in YAML format.

To use the following functions for reading and manipulating the logic configuration, the configuration file has to be in YAML format. Otherwise the functions will not work/return empty results.

Rückgabe:

‚.yaml‘, ‚.conf‘ or None

Rückgabetyp:

str or None

read_config_section(section)

Read a section from /etc/logic.yaml

This funtion returns the data from one section of the configuration file as a list of configuration entries. A configuration entry is a list with three items: - key configuration key - value configuration value (string or list) - comment comment for the value (string or list)

Parameter:

section (str) – Name of the logic (section)

Rückgabe:

config_list: list of configuration entries. Each entry of this list is a list with three string entries: [‚key‘, ‚value‘, ‚comment‘]

Rückgabetyp:

list of lists

set_config_section_key(section, key, value)

Sets the value of key for a given logic (section)

Parameter:

• section – logic to set the key for

• key – key for which the value should be set

• value – value to set

update_config_section(active, section, config_list)

Update file /etc/logic.yaml

This method creates/updates a section in /etc/logic.yaml. If the section exist, it is cleared before new configuration imformation is written to the section

Parameter:

• active (bool) – True: logic is/should be active, False: Triggers are not written to /etc/logic.yaml

• section (str) – name of section to configure in logics configurationfile

• config_list (list of lists) – list of configuration entries. Each entry of this list is a list with three string entries: [‚key‘, ‚value‘, ‚comment‘]

filename_used_count(filename)

delete_logic(name, with_code=False)

Deletes a complete logic

The python code and the section from the configuration file /etc/logic.yaml are removed. If it is a blockly logic, the blockly code is removed too.

If a code file is references by more than the logic that is being deleted, the code file will not be deleted. It will only be deleted when the last logic referencing this code file is being deleted.

Parameter:

name (str) – name of the logic

Rückgabe:

True, if deletion fas successful

Rückgabetyp:

bool

class lib.logic.Logic(smarthome, name, attributes, logics)

Bases: object

Class for the representation of a loaded logic

id()

Returns the id of the loaded logic

property name

Property: name

Parameter:

value (str) – name of the logic

Rückgabe:

name of the logic

Rückgabetyp:

str

property groupnames

Property: groupname

Parameter:

value (str) – groupname of the logic

Rückgabe:

groupname of the logic

Rückgabetyp:

str

property description

Property: groupname

Parameter:

value (str) – description of the logic

Rückgabe:

description of the logic

Rückgabetyp:

str

log_readonly_warning(prop, value)

property lname

Property: lname

Parameter:

value (str) – string with the name of the logic for information in value assignements to items

Rückgabe:

name of the item

Rückgabetyp:

str

property filename

Property: filename

Rückgabe:

filename of the logic

Rückgabetyp:

str

property pathname

Property: pathname

Rückgabe:

pathname of the logic

Rückgabetyp:

str

property conf

Property: conf

Rückgabe:

conf of the logic

Rückgabetyp:

collections.OrderedDict

property cycle

Property: cycle

Rückgabe:

cycle attribute of the logic

Rückgabetyp:

str

property crontab

Property: crontab

Rückgabe:

crontab attribute of the logic

Rückgabetyp:

str

property prio

Property: prio

Rückgabe:

prio attribute of the logic

Rückgabetyp:

str

property trigger_dict

Property: trigger_dict

Rückgabe:

trigger_dict attribute of the logic

Rückgabetyp:

dict

property watch_item

Property: watch_item

Rückgabe:

watch_item attribute of the logic

Rückgabetyp:

list

enable()

Enables the loaded logic

disable()

Disables the loaded logic

is_enabled()

Is the loaded logic enabled?

last_run()

Returns the timestamp of the last run of the logic or None (if the logic wasn’t triggered)

Rückgabe:

timestamp of last run

Rückgabetyp:

datetime timestamp

set_last_run()

Sets the timestamp of the last run of the logic to now

This method is called by the scheduler

trigger(by='Logic', source=None, value=None, dest=None, dt=None)

add_method_trigger(method)

get_method_triggers()