Skip to content

Latest commit

 

History

History
382 lines (266 loc) · 13.3 KB

rule.rst

File metadata and controls

382 lines (266 loc) · 13.3 KB
Raw

Rule

Interacting with items

Items are like variables. They have a name and a value (which can be anything). Items from openHAB use the item name from openHAB and get created when HABApp successfully connects to openHAB or when the openHAB configuration changes. Items from MQTT use the topic as item name and get created as soon as a message gets processed.

Some item types provide convenience functions, so it is advised to always set the correct item type.

The preferred way to get and create items is through the class factories ~HABApp.core.items.Item.get_item and ~HABApp.core.items.Item.get_create_item since this ensures the proper item class and provides type hints when using an IDE!

If an item value gets set there will be a ~HABApp.core.ValueUpdateEvent on the event bus. If it changes there will be additionally a ~HABApp.core.ValueChangeEvent, too.

It is possible to check the item value by comparing it

An overview over the item types can be found on the HABApp item section <HABAPP_ITEM_TYPES>, the openHAB item section <OPENHAB_ITEM_TYPES> and the the mqtt item section <MQTT_ITEM_TYPES>

Interacting with events

It is possible to listen to events through the ~HABApp.Rule.listen_event function. The passed function will be called as soon as an event occurs and the event will pe passed as an argument into the function.

There is the possibility to reduce the function calls to a certain event type with an additional event filter (typically ~HABApp.core.ValueUpdateEventFilter or ~HABApp.core.ValueChangeEventFilter).

An overview over the events can be found on the HABApp event section <HABAPP_EVENT_TYPES>, the openHAB event section <OPENHAB_EVENT_TYPES> and the the MQTT event section <MQTT_EVENT_TYPES>

Additionally there is the possibility to filter not only on the event type but on the event values, too. This can be achieved by passing the value to the event filter. There are convenience Filters (e.g. ~HABApp.core.events.ValueUpdateEventFilter and ~HABApp.core.events.ValueChangeEventFilter) for the most used event types that provide type hints.

NoEventFilter

HABApp.core.events.NoEventFilter

EventFilter

HABApp.core.events.EventFilter

ValueUpdateEventFilter

HABApp.core.events.ValueUpdateEventFilter

ValueChangeEventFilter

HABApp.core.events.ValueChangeEventFilter

AndFilterGroup

HABApp.core.events.AndFilterGroup

OrFilterGroup

HABApp.core.events.OrFilterGroup

Example

Scheduler

With the scheduler it is easy to call functions in the future or periodically. Do not use time.sleep but rather self.run.at. Another very useful function is self.run.countdown as it can simplify many rules!

Function Description
~HABApp.rule.scheduler.HABAppSchedulerView.soon Run the callback as soon as possible (typically in the next second).
~HABApp.rule.scheduler.HABAppSchedulerView.at Run the callback in x seconds or at a specified time.
~HABApp.rule.scheduler.HABAppSchedulerView.countdown Run a function after a time has run down
~HABApp.rule.scheduler.HABAppSchedulerView.every Run a function periodically
~HABApp.rule.scheduler.HABAppSchedulerView.every_minute Run a function every minute
~HABApp.rule.scheduler.HABAppSchedulerView.every_hour Run a function every hour
~HABApp.rule.scheduler.HABAppSchedulerView.on_every_day Run a function at a specific time every day
~HABApp.rule.scheduler.HABAppSchedulerView.on_workdays Run a function at a specific time on workdays
~HABApp.rule.scheduler.HABAppSchedulerView.on_weekends Run a function at a specific time on weekends
~HABApp.rule.scheduler.HABAppSchedulerView.on_day_of_week Run a function at a specific time on specific days of the week
~HABApp.rule.scheduler.HABAppSchedulerView.on_sun_dawn Run a function on dawn
~HABApp.rule.scheduler.HABAppSchedulerView.on_sunrise Run a function on sunrise
~HABApp.rule.scheduler.HABAppSchedulerView.on_sunset Run a function on sunset
~HABApp.rule.scheduler.HABAppSchedulerView.on_sun_dusk Run a function on dusk

All functions return an instance of ScheduledCallbackBase

HABApp.rule.scheduler.HABAppSchedulerView

Other tools and scripts

HABApp provides convenience functions to run other tools and scripts. The working directory for the new process is by default the folder of the HABApp configuration file.

Running tools

External tools can be run with the ~HABApp.Rule.execute_subprocess function. Once the process has finished the callback will be called with the captured output of the process. Example:

import HABApp

class MyExecutionRule(HABApp.Rule):

    def __init__(self):
        super().__init__()

        self.execute_subprocess( self.func_when_finished, 'path_to_program', 'arg1_for_program')

    def func_when_finished(self, process_output: str):
        print(process_output)

MyExecutionRule()

Running python scripts or modules

Python scripts can be run with the ~HABApp.Rule.execute_python function. The working directory for a script is by default the folder of the script. Once the script or module has finished the callback will be called with the captured output of the module/script. Example:

import HABApp

class MyExecutionRule(HABApp.Rule):

    def __init__(self):
        super().__init__()

        self.execute_python( self.func_when_finished, '/path/to/python/script.py', 'arg1_for_script')

    def func_when_finished(self, module_output: str):
        print(module_output)

MyExecutionRule()

FinishedProcessInfo

It's possible to get the raw process output instead of just the captured string. See ~HABApp.Rule.execute_subprocess or ~HABApp.Rule.execute_python on how to enable it.

HABApp.rule.FinishedProcessInfo

How to properly use rules from other rule files

This example shows how to properly get a rule during runtime and execute one of its function. With the proper import and type hint this method provides syntax checks and auto complete.

Rule instances can be accessed by their name (typically the class name). In the HABApp.log you can see the name when the rule is loaded. If you want to assign a custom name, you can change the rule name easily by assigning it to self.rule_name in __init__.

Important

Always look up rule every time, never assign to a class member! The rule might get reloaded and then the class member will still point to the old unloaded instance.

rule_a.py:

import HABApp

class ClassA(HABApp.Rule):
    ...

    def function_a(self):
      ...

ClassA()

rule_b.py:

import HABApp
import typing

if typing.TYPE_CHECKING:            # This is only here to allow
    from .rule_a import ClassA      # type hints for the IDE

class ClassB(HABApp.Rule):
    ...

    def function_b(self):

        r = self.get_rule('ClassA')  # type: ClassA
        # The comment "# type: ClassA" will signal the IDE that the value returned from the
        # function is an instance of ClassA and thus provide checks and auto complete.

        # this calls the function on the instance
        r.function_a()

All available functions

HABApp.Rule

var async_http

Async http connections <ref_async_io>

var mqtt

MQTT interaction <ref_mqtt>

var openhab

openhab interaction <ref_openhab>

var oh

short alias for openhab <ref_openhab>