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)[source]

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()[source]

Returns a list with the names of all loaded logics

Returns:list of logic names
Return type:list
static get_instance()[source]

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)
Returns:logics instance
Return type:object or None
scheduler_add(name, obj, prio=3, cron=None, cycle=None, value=None, offset=None, next=None)[source]

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)[source]

This methods changes a scheduler entry of a logic-scheduler

scheduler_remove(name)[source]

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()[source]

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

Returns:path to logics directory
Return type:str
reload_logics()[source]

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)[source]

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

Parameters:name (str) – logic name (name of the configuration section section)
Returns:True: Logic is loaded
Return type:bool
return_logic(name)[source]

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

Parameters:name (str) – name of the logic to get
Returns:object of the logic
Return type:object
get_logic_info(name, ordered=False)[source]

Returns a dict with information about the logic

Parameters:name (str) – name of the logic to get info for
Returns:information about the logic
Return type:dict
visu_access(name)[source]

Return if visu may access the logic

is_logic_enabled(name)[source]

Returns True, if the logic is enabled

enable_logic(name)[source]

Enable a logic

disable_logic(name)[source]

Disable a logic

toggle_logic(name)[source]

Toggle a logic (Invert the enabled/disabled state)

trigger_logic(name, by='unknown')[source]

Trigger a logic

is_userlogic(name)[source]

Returns True if userlogic and False if systemlogic or unknown

load_logic(name)[source]

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.

Parameters:name (str) – Name of the logic (name of the configuration section)
Returns:Success
Return type:bool
unload_logic(name)[source]

Unload a specified logic

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

Parameters:name (str) – Name of the section that defines the logic in the configuration file
return_logictype(name)[source]

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

Parameters:name (str) – Name of the logic (name of the configuration section)
Returns:Logic type (‘Python’, ‘Blockly’ or None)
Return type:str or None
return_defined_logics(withtype=False)[source]

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

Parameters:withtype (bool) – If specified and set to True, the function will additionally return the logic types
Returns:list of defined logics or dict of defined logics with type
Return type:list or dict
return_loaded_logics()[source]

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

Returns:list of logic names
Return type:list
return_config_type()[source]

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.

Returns:‘.yaml’, ‘.conf’ or None
Return type:str or None
read_config_section(section)[source]

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)

Parameters:section (str) – Name of the logic (section)
Returns:config_list: list of configuration entries. Each entry of this list is a list with three string entries: [‘key’, ‘value’, ‘comment’]
Return type:list of lists
set_config_section_key(section, key, value)[source]

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

Parameters:
  • 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)[source]

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

Parameters:
  • 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)[source]

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.

Parameters:name (str) – name of the logic
Returns:True, if deletion fas successful
Return type:bool
class lib.logic.Logic(smarthome, name, attributes, logics)[source]

Bases: object

Class for the representation of a loaded logic

id()[source]

Returns the id of the loaded logic

enable()[source]

Enables the loaded logic

disable()[source]

Disables the loaded logic

is_enabled()[source]

Is the loaded logic enabled?

last_run()[source]

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

Returns:timestamp of last run
Return type:datetime timestamp
set_last_run()[source]

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)[source]
add_method_trigger(method)[source]
get_method_triggers()[source]