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

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‘]

delete_logic(name)

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

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