util - helpers and utilities¶
The util package contains useful classes which make rule creation easier.
Functions¶
min¶
This function is very useful together with the all possible functions of ValueMode
for the
MultiModeItem
.
For example it can be used to automatically disable or calculate the new value of the ValueMode
It behaves like the standard python function except that it will ignore None
values which are sometimes set as the item state.
from HABApp.util.functions import min
print(min(1, 2, None))
- HABApp.util.functions.min(*args, default=None)¶
Behaves like the built in min function but ignores any
None
values. e.g.min([1, None, 2]) == 1
. If the iterable is emptydefault
will be returned.- Parameters
args – Single iterable or 1..n arguments
default – Value that will be returned if the iterable is empty
- Returns
min value
max¶
This function is very useful together with the all possible functions of ValueMode
for the
MultiModeItem
.
For example it can be used to automatically disable or calculate the new value of the ValueMode
It behaves like the standard python function except that it will ignore None
values which are sometimes set as the item state.
from HABApp.util.functions import max
print(max(1, 2, None))
- HABApp.util.functions.max(*args, default=None)¶
Behaves like the built in max function but ignores any
None
values. e.g.max([1, None, 2]) == 2
. If the iterable is emptydefault
will be returned.- Parameters
args – Single iterable or 1..n arguments
default – Value that will be returned if the iterable is empty
- Returns
max value
rgb_to_hsb¶
Converts a rgb value to hsb color space
from HABApp.util.functions import rgb_to_hsb
print(rgb_to_hsb(224, 201, 219))
- HABApp.util.functions.rgb_to_hsb(r, g, b, max_rgb_value=255, ndigits=2)¶
Convert from rgb to hsb/hsv
- Parameters
r (
Union
[int
,float
]) – red valueg (
Union
[int
,float
]) – green valueb (
Union
[int
,float
]) – blue valuemax_rgb_value (
int
) – maximal possible rgb value (e.g. 255 for 8 bit or 65.535 for 16bit values)ndigits (
Optional
[int
]) – Round the hsb values to the specified digits, None to disable rounding
- Return type
Tuple
[float
,float
,float
]- Returns
Values for hue, saturation and brightness / value
hsb_to_rgb¶
Converts a hsb value to the rgb color space
from HABApp.util.functions import hsb_to_rgb
print(hsb_to_rgb(150, 40, 100))
- HABApp.util.functions.hsb_to_rgb(h, s, b, max_rgb_value=255)¶
Convert from rgb to hsv/hsb
- Parameters
h – hue
s – saturation
b – brightness / value
max_rgb_value – maximal value for the returned rgb values (e.g. 255 for 8 bit or 65.535 16bit values)
- Return type
Tuple
[int
,int
,int
]- Returns
Values for red, green and blue
CounterItem¶
Example¶
from HABApp.util import CounterItem
c = CounterItem.get_create_item('MyCounter', initial_value=5)
print(c.increase())
print(c.decrease())
print(c.reset())
6
5
5
Documentation¶
- class HABApp.util.CounterItem(name, initial_value=0)¶
Implements a simple thread safe counter
- Parameters
initial_value (
int
) – Initial value of the counter
- __init__(name, initial_value=0)¶
- Parameters
initial_value (
int
) – Initial value of the counter
- set_value(new_value)¶
Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
- post_value(new_value)¶
Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Returns
True if state has changed
- reset()¶
Reset value to initial value
- increase(step=1)¶
Increase value
- Parameters
step – increase by this value, default = 1
- Return type
int
- Returns
value of the counter
- decrease(step=1)¶
Decrease value
- Parameters
step – decrease by this value, default = 1
- Return type
int
- Returns
value of the counter
Statistics¶
Example¶
s = Statistics(max_samples=4)
for i in range(1,4):
s.add_value(i)
print(s)
<Statistics sum: 1.0, min: 1.00, max: 1.00, mean: 1.00, median: 1.00>
<Statistics sum: 3.0, min: 1.00, max: 2.00, mean: 1.50, median: 1.50>
<Statistics sum: 6.0, min: 1.00, max: 3.00, mean: 2.00, median: 2.00>
Documentation¶
- class HABApp.util.Statistics(max_age=None, max_samples=None)¶
Calculate mathematical statistics of numerical values.
- Variables
sum – sum of all values
min – minimum of all values
max – maximum of all values
mean – mean of all values
median – median of all values
last_value – last added value
last_change – timestamp the last time a value was added
- Parameters
max_age – Maximum age of values in seconds
max_samples – Maximum amount of samples which will be kept
- update()¶
update values without adding a new value
- add_value(value)¶
Add a new value and recalculate statistical values
- Parameters
value – new value
MultiModeItem¶
Prioritizer item which automatically switches between values with different priorities. Very useful when different states or modes overlap, e.g. automatic and manual mode. etc.
Basic Example¶
import HABApp
from HABApp.core.events import ValueUpdateEvent
from HABApp.util.multimode import MultiModeItem, ValueMode
class MyMultiModeItemTestRule(HABApp.Rule):
def __init__(self):
super().__init__()
# create a new MultiModeItem
item = MultiModeItem.get_create_item('MultiModeTestItem')
item.listen_event(self.item_update, ValueUpdateEvent)
# create two different modes which we will use and add them to the item
auto = ValueMode('Automatic', initial_value=5)
manu = ValueMode('Manual', initial_value=0)
item.add_mode(0, auto).add_mode(10, manu)
# This shows how to enable/disable a mode and how to get a mode from the item
print('disable/enable the higher priority mode')
item.get_mode('manual').set_enabled(False) # disable mode
item.get_mode('manual').set_value(11) # setting a value will enable it again
# This shows that changes of the lower priority is only show when
# the mode with the higher priority gets disabled
print('')
print('Set value of lower priority')
auto.set_value(55)
print('Disable higher priority')
manu.set_enabled(False)
def item_update(self, event):
print(f'State: {event.value}')
MyMultiModeItemTestRule()
disable/enable the higher priority mode
State: 5
State: 11
Set value of lower priority
State: 11
Disable higher priority
State: 55
Advanced Example¶
import logging
import HABApp
from HABApp.core.events import ValueUpdateEvent
from HABApp.util.multimode import MultiModeItem, ValueMode
class MyMultiModeItemTestRule(HABApp.Rule):
def __init__(self):
super().__init__()
# create a new MultiModeItem
item = MultiModeItem.get_create_item('MultiModeTestItem')
item.listen_event(self.item_update, ValueUpdateEvent)
# helper to print the heading so we have a nice outpt
def print_heading(_heading):
print('')
print('-' * 80)
print(_heading)
print('-' * 80)
for p, m in item.all_modes():
print(f'Prio {p:2d}: {m}')
print('')
log = logging.getLogger('AdvancedMultiMode')
# create modes and add them
auto = ValueMode('Automatic', initial_value=5, logger=log)
manu = ValueMode('Manual', initial_value=10, logger=log)
item.add_mode(0, auto).add_mode(10, manu)
# it is possible to automatically disable a mode
# this will disable the manual mode if the automatic mode
# sets a value greater equal manual mode
print_heading('Automatically disable mode')
# A custom function can also disable the mode:
manu.auto_disable_func = lambda low, own: low >= own
auto.set_value(11) # <-- manual now gets disabled because
auto.set_value(4) # the lower priority value is >= itself
# It is possible to use functions to calculate the new value for a mode.
# E.g. shutter control and the manual mode moves the shades. If it's dark the automatic
# mode closes the shutter again. This could be achievied by automatically disable the
# manual mode or if the state should be remembered then the max function should be used
# create a move and use the max function for output calculation
manu = ValueMode('Manual', initial_value=5, logger=log, calc_value_func=max)
item.add_mode(10, manu) # overwrite the earlier added mode
print_heading('Use of functions')
auto.set_value(7) # manu uses max, so the value from auto is used
auto.set_value(3)
def item_update(self, event):
print(f'Item value: {event.value}')
MyMultiModeItemTestRule()
--------------------------------------------------------------------------------
Automatically disable mode
--------------------------------------------------------------------------------
Prio 0: <ValueMode Automatic enabled: True, value: 5>
Prio 10: <ValueMode Manual enabled: True, value: 10>
[AdvancedMultiMode] INFO | [x] Automatic: 11
[AdvancedMultiMode] INFO | [ ] Manual (function)
Item value: 11
[AdvancedMultiMode] INFO | [x] Automatic: 4
Item value: 4
--------------------------------------------------------------------------------
Use of functions
--------------------------------------------------------------------------------
Prio 0: <ValueMode Automatic enabled: True, value: 4>
Prio 10: <ValueMode Manual enabled: True, value: 5>
[AdvancedMultiMode] INFO | [x] Automatic: 7
Item value: 7
[AdvancedMultiMode] INFO | [x] Automatic: 3
Item value: 5
Example SwitchItemValueMode¶
The SwitchItemMode is same as ValueMode but enabled/disabled of the mode is controlled by a OpenHAB
SwitchItem
. This is very useful if the mode shall be deactivated from the OpenHAB sitemaps.
import HABApp
from HABApp.core.events import ValueUpdateEvent
from HABApp.openhab.items import SwitchItem
from HABApp.util.multimode import MultiModeItem, SwitchItemValueMode, ValueMode
class MyMultiModeItemTestRule(HABApp.Rule):
def __init__(self):
super().__init__()
# create a new MultiModeItem
item = MultiModeItem.get_create_item('MultiModeTestItem')
# this switch allows to enable/disable the mode
switch = SwitchItem.get_item('Automatic_Enabled')
print(f'Switch is {switch}')
# this is how the switch gets linked to the mode
# if the switch is on, the mode is on, too
mode = SwitchItemValueMode('Automatic', switch)
print(mode)
# Use invert_switch if the desired behaviour is
# if the switch is off, the mode is on
mode = SwitchItemValueMode('AutomaticOff', switch, invert_switch=True)
print(mode)
# This shows how the SwitchItemValueMode can be used to disable any logic except for the manual mode.
# Now everything can be enabled/disabled from the openhab sitemap
item.add_mode(100, mode)
item.add_mode(101, ValueMode('Manual'))
MyMultiModeItemTestRule()
Switch is ON
<SwitchItemValueMode Automatic enabled: True, value: None>
<SwitchItemValueMode AutomaticOff enabled: False, value: None>
Documentation¶
MultiModeItem¶
- class HABApp.util.multimode.MultiModeItem(name, initial_value=None)¶
Prioritizer
Item
- Variables
logger – Assign a logger to get log messages about the different modes
- remove_mode(name)¶
Remove mode if it exists
- Parameters
name (
str
) – name of the mode (case insensitive)- Return type
bool
- Returns
True if something was removed, False if nothign was found
- add_mode(priority, mode)¶
Add a new mode to the item, if it already exists it will be overwritten
- Parameters
priority (
int
) – priority of the modemode (
BaseMode
) – instance of the MultiMode class
- Return type
- all_modes()¶
Returns a sorted list containing tuples with the priority and the mode
- Return type
List
[Tuple
[int
,BaseMode
]]- Returns
List with priorities and modes
- get_mode(name)¶
Returns a created mode
- Parameters
name (
str
) – name of the mode (case insensitive)- Return type
BaseMode
- Returns
The requested MultiModeValue
- calculate_value()¶
Recalculate the output value and post the state to the event bus (if it is not None)
- Return type
Any
- Returns
new value
ValueMode¶
- class HABApp.util.multimode.ValueMode(name, initial_value=None, enabled=None, enable_on_value=True, logger=None, auto_disable_after=None, auto_disable_func=None, calc_value_func=None)¶
- Variables
last_update (datetime.datetime) – Timestamp of the last update/enable of this value
auto_disable_after (typing.Optional[datetime.timedelta]) – Automatically disable this mode after a given timedelta on the next recalculation
auto_disable_func (typing.Optional[typing.Callable[[typing.Any, typing.Any], bool]]) – Function which can be used to disable this mode. Any function that accepts two Arguments can be used. First arg is value with lower priority, second argument is own value. Return
True
to disable this mode.calc_value_func (typing.Optional[typing.Callable[[typing.Any, typing.Any], typing.Any]]) – Function to calculate the new value (e.g.
min
ormax
). Any function that accepts two Arguments can be used. First arg is value with lower priority, second argument is own value.
- Parameters
name (
str
) – Name of the modeinitial_value – initial value of the mode
enabled (
Optional
[bool
]) – initial enabled state of the modeenable_on_value (
bool
) – IfTrue
(default) setting a value (that is notNone
) will also enable the modelogger (
Optional
[Logger
]) – logger to log eventsauto_disable_after – see variables
auto_disable_func – see variables
calc_value_func – see variables
- property value¶
Returns the current value
- property enabled: bool¶
Returns if the value is enabled
- Return type
bool
- set_value(value, only_on_change=False)¶
Set new value and recalculate overall value. If
enable_on_value
is set, setting a value will also enable the mode.- Parameters
value – new value
only_on_change (
bool
) – will set/enable the mode only if value differs or the mode is disabled
- set_enabled(value, only_on_change=False)¶
Enable or disable this value and recalculate overall value
- Parameters
value (
bool
) – True/Falseonly_on_change (
bool
) – enable only on change
- Returns
- cancel()¶
Remove the mode from the parent
MultiModeItem
and stop processing it
SwitchItemValueMode¶
- class HABApp.util.multimode.SwitchItemValueMode(name, switch_item, invert_switch=False, initial_value=None, logger=None, auto_disable_after=None, auto_disable_func=None, calc_value_func=None)¶
SwitchItemMode, same as ValueMode but enabled/disabled of the mode is controlled by a OpenHAB
SwitchItem
- Variables
last_update (datetime.datetime) – Timestamp of the last update/enable of this value
auto_disable_after (typing.Optional[datetime.timedelta]) – Automatically disable this mode after a given timedelta on the next recalculation
auto_disable_func (typing.Optional[typing.Callable[[typing.Any, typing.Any], bool]]) – Function which can be used to disable this mode. Any function that accepts two Arguments can be used. First arg is value with lower priority, second argument is own value. Return
True
to disable this mode.calc_value_func (typing.Optional[typing.Callable[[typing.Any, typing.Any], typing.Any]]) – Function to calculate the new value (e.g.
min
ormax
). Any function that accepts two Arguments can be used. First arg is value with lower priority, second argument is own value.
- Parameters
name (
str
) – Name of the modeswitch_item (
SwitchItem
) –SwitchItem
that will enable/disable the modeinvert_switch (
bool
) – invert switch state (e.g. OFF -> enabled, default isFalse
)initial_value – initial value of the mode
logger (
Optional
[Logger
]) – logger to log eventsauto_disable_after – see variables
auto_disable_func – see variables
calc_value_func – see variables
- cancel()¶
Remove the mode from the parent
MultiModeItem
and stop processing it
- property enabled: bool¶
Returns if the value is enabled
- Return type
bool
- set_value(value, only_on_change=False)¶
Set new value and recalculate overall value. If
enable_on_value
is set, setting a value will also enable the mode.- Parameters
value – new value
only_on_change (
bool
) – will set/enable the mode only if value differs or the mode is disabled
- property value¶
Returns the current value