HABApp

This page describes the HABApp internals

Datatypes

HABApp provides some datatypes that simplify e.g. the color handling.

RGB

Datatype for RGB (red, green, blue) color handling. RGB types can be sent directly to openHAB and will be converted accordingly. Additionally there are wider RGB types (e.g. RGB16, RGB32) available.

from HABApp.core.types import RGB

col = RGB(5, 15, 255)
print(col)

print(col.red)   # red value
print(col.r)     # short name for red value
print(col[0])    # access of red value through numeric index

new_col = col.replace(red=22)
print(new_col)
print(new_col.to_hsb())

RGB(5, 15, 255)
5
5
5
RGB(22, 15, 255)
HSB(241.75, 94.12, 100.00)

class RGB(r, g, b)

classmethod from_hsb(obj)

Return new Object from a HSB object for a hsb tuple

Parameters:: obj (Union[HSB, Tuple[float, float, float]]) – HSB object or tuple with HSB values
Return type:: Self
Returns:: new RGB object

replace(r=None, g=None, b=None, red=None, green=None, blue=None)

Create a new object with (optionally) replaced values.

Parameters:

r (Optional[int]) – new red value
red (Optional[int]) – new red value
g (Optional[int]) – new green value
green (Optional[int]) – new green value
b (Optional[int]) – new blue value
blue (Optional[int]) – new blue value

Return type:

Self

to_hsb()

Create a new HSB object from this object

Return type:: HSB
Returns:: New HSB object

property b: int: blue value

property blue: int: blue value

property g: int: green value

property green: int: green value

property r: int: red value

property red: int: red value

HSB

Datatype for HSB (hue, saturation, brightness) color handling. HSB types can be sent directly to openHAB and will be converted accordingly.

from HABApp.core.types import HSB

col = HSB(200, 25, 75)
print(col)

print(col.hue)   # hue value
print(col.h)     # short name for hue value
print(col[0])    # access of hue value through numeric index

new_col = col.replace(hue=22)
print(new_col)
print(new_col.to_rgb())

HSB(200.00, 25.00, 75.00)
200
200
200
HSB(22.00, 25.00, 75.00)
RGB(191, 161, 143)

class HSB(hue, saturation, brightness)

classmethod from_rgb(obj)

Create an HSB object from an RGB object or an RGB tuple

Parameters:: obj (Union[RGB, Tuple[int, int, int]]) – HSB object or RGB tuple
Return type:: Self
Returns:: New HSB object

replace(h=None, s=None, b=None, hue=None, saturation=None, brightness=None)

Create a new object with (optionally) replaced values.

Parameters:

h (Optional[float]) – New hue value
hue (Optional[float]) – New hue value
s (Optional[float]) – New saturation value
saturation (Optional[float]) – New saturation value
b (Optional[float]) – New brightness value
brightness (Optional[float]) – New brightness value

Return type:

Self

to_rgb()

Create an RGB object from this object

Return type:: RGB
Returns:: New RGB object

property b: float: brightness value

property brightness: float: brightness value

property h: float: hue value

property hue: float: hue value

property s: float: saturation value

property saturation: float: saturation value

Items

Item

class Item()

Simple item, used to store values in HABApp

classmethod get_create_item(name, initial_value=None)

Creates a new item in HABApp and returns it or returns the already existing one with the given name

Parameters:

name (str) – item name
initial_value – state the item will have if it gets created

Return type:

Item

Returns:

The item

classmethod get_item(name)

Returns an already existing item. If it does not exist or has a different item type an exception will occur.

Parameters:: name (str) – Name of the item

get_value(default_value=None)

Return the value of the item. This is a helper function that returns a default in case the item value is None.

Parameters:: default_value – Return this value if the item value is None
Return type:: Any
Returns:: value of the item

listen_event(callback, event_filter=None)

Register an event listener which listens to all event that the item receives

Parameters:

callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event
event_filter (Optional[TypeVar(HINT_EVENT_FILTER_OBJ, bound= EventFilterBase)]) – Event filter. This is typically ValueUpdateEventFilter or ValueChangeEventFilter which will also trigger on changes/update from openhab or mqtt. Additionally it can be an instance of EventFilter which additionally filters on the values of the event. It is also possible to group filters logically with, e.g. AndFilterGroup and OrFilterGroup

Return type:

TypeVar(HINT_EVENT_BUS_LISTENER, bound= EventBusListener)

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
Return type:: bool
Returns:: True if state has changed

post_value_if(new_value, *, equal=<MISSING>, eq=<MISSING>, not_equal=<MISSING>, ne=<MISSING>, lower_than=<MISSING>, lt=<MISSING>, lower_equal=<MISSING>, le=<MISSING>, greater_than=<MISSING>, gt=<MISSING>, greater_equal=<MISSING>, ge=<MISSING>, is_=<MISSING>, is_not=<MISSING>)

Post a value depending on the current state of the item. If one of the comparisons is true the new state will be posted.

Parameters:

new_value – new value to post
equal – item state has to be equal to the passed value
eq – item state has to be equal to the passed value
not_equal – item state has to be not equal to the passed value
ne – item state has to be not equal to the passed value
lower_than – item state has to be lower than the passed value
lt – item state has to be lower than the passed value
lower_equal – item state has to be lower equal the passed value
le – item state has to be lower equal the passed value
greater_than – item state has to be greater than the passed value
gt – item state has to be greater than the passed value
greater_equal – item state has to be greater equal the passed value
ge – item state has to be greater equal the passed value
is – item state has to be the same object as the passt value (e.g. None)
is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

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

watch_change(secs)

Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (Union[int, float, timedelta]) – secs after which the event will occur, max 1 decimal digit for floats
Return type:: ItemNoChangeWatch
Returns:: The watch obj which can be used to cancel the watch

watch_update(secs)

Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (Union[int, float, timedelta]) – secs after which the event will occur, max 1 decimal digit for floats
Return type:: ItemNoUpdateWatch
Returns:: The watch obj which can be used to cancel the watch

property last_change: DateTime

Returns:: Timestamp of the last time when the item has been changed (read only)

property last_update: DateTime

Returns:: Timestamp of the last time when the item has been updated (read only)

property name: str

Returns:: Name of the item (read only)

ColorItem

class ColorItem()

Item for dealing with color related values

classmethod get_create_item(name, hue=0.0, saturation=0.0, brightness=0.0)

Creates a new item in HABApp and returns it or returns the already existing one with the given name

Parameters:

name (str) – item name
initial_value – state the item will have if it gets created

Returns:

item

classmethod get_item(name)

Returns an already existing item. If it does not exist or has a different item type an exception will occur.

Parameters:: name (str) – Name of the item

get_rgb(max_rgb_value=255)

Return a rgb equivalent of the color

Parameters:: max_rgb_value – the max value for rgb, typically 255 (default) or 65.536
Return type:: Tuple[int, int, int]
Returns:: rgb tuple

get_value(default_value=None)

Return the value of the item. This is a helper function that returns a default in case the item value is None.

Parameters:: default_value – Return this value if the item value is None
Return type:: Any
Returns:: value of the item

is_off()

Return true if item is off

Return type:: bool

is_on()

Return true if item is on

Return type:: bool

listen_event(callback, event_filter=None)

Register an event listener which listens to all event that the item receives

Parameters:

callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event
event_filter (Optional[TypeVar(HINT_EVENT_FILTER_OBJ, bound= EventFilterBase)]) – Event filter. This is typically ValueUpdateEventFilter or ValueChangeEventFilter which will also trigger on changes/update from openhab or mqtt. Additionally it can be an instance of EventFilter which additionally filters on the values of the event. It is also possible to group filters logically with, e.g. AndFilterGroup and OrFilterGroup

Return type:

TypeVar(HINT_EVENT_BUS_LISTENER, bound= EventBusListener)

post_rgb(r, g, b, max_rgb_value=255)

Set a new rgb value and post appropriate events on the HABApp event bus (ValueUpdateEvent, ValueChangeEvent)

Parameters:

r – red value
g – green value
b – blue value
max_rgb_value – the max value for rgb, typically 255 (default) or 65.536

Return type:

ColorItem

Returns:

self

post_value(hue=0.0, saturation=0.0, brightness=0.0)

Set a new value and post appropriate events on the HABApp event bus (ValueUpdateEvent, ValueChangeEvent)

Parameters:

hue – hue (in °)
saturation – saturation (in %)
brightness – brightness (in %)

post_value_if(new_value, *, equal=<MISSING>, eq=<MISSING>, not_equal=<MISSING>, ne=<MISSING>, lower_than=<MISSING>, lt=<MISSING>, lower_equal=<MISSING>, le=<MISSING>, greater_than=<MISSING>, gt=<MISSING>, greater_equal=<MISSING>, ge=<MISSING>, is_=<MISSING>, is_not=<MISSING>)

Post a value depending on the current state of the item. If one of the comparisons is true the new state will be posted.

Parameters:

new_value – new value to post
equal – item state has to be equal to the passed value
eq – item state has to be equal to the passed value
not_equal – item state has to be not equal to the passed value
ne – item state has to be not equal to the passed value
lower_than – item state has to be lower than the passed value
lt – item state has to be lower than the passed value
lower_equal – item state has to be lower equal the passed value
le – item state has to be lower equal the passed value
greater_than – item state has to be greater than the passed value
gt – item state has to be greater than the passed value
greater_equal – item state has to be greater equal the passed value
ge – item state has to be greater equal the passed value
is – item state has to be the same object as the passt value (e.g. None)
is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_rgb(r, g, b, max_rgb_value=255, ndigits=2)

Set a rgb value

Parameters:

r – red value
g – green value
b – blue value
max_rgb_value – the max value for rgb, typically 255 (default) or 65.536
ndigits (Optional[int]) – Round the hsb values to the specified digits, None to disable rounding

Return type:

ColorItem

Returns:

self

set_value(hue=0.0, saturation=0.0, brightness=0.0)

Set the color value

Parameters:

hue – hue (in °)
saturation – saturation (in %)
brightness – brightness (in %)

watch_change(secs)

Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (Union[int, float, timedelta]) – secs after which the event will occur, max 1 decimal digit for floats
Return type:: ItemNoChangeWatch
Returns:: The watch obj which can be used to cancel the watch

watch_update(secs)

Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (Union[int, float, timedelta]) – secs after which the event will occur, max 1 decimal digit for floats
Return type:: ItemNoUpdateWatch
Returns:: The watch obj which can be used to cancel the watch

property last_change: DateTime

Returns:: Timestamp of the last time when the item has been changed (read only)

property last_update: DateTime

Returns:: Timestamp of the last time when the item has been updated (read only)

property name: str

Returns:: Name of the item (read only)

AggregationItem

The aggregation item is an item which takes the values of another item in a time period as an input. It then allows to process these values and generate an aggregated output based on it. The item makes implementing time logic like “Has it been dark for the last hour?” or “Was there frost during the last six hours?” really easy. And since it is just like a normal item triggering on changes etc. is possible, too.

from HABApp.core.items import AggregationItem
my_agg = AggregationItem.get_create_item('MyAggregationItem')

# Connect the source item with the aggregation item
my_agg.aggregation_source('MyInputItem')

# Aggregate all changes in the last two hours
my_agg.aggregation_period(2 * 3600)

# Use max as an aggregation function
my_agg.aggregation_func = max

The value of my_agg in the example will now always be the maximum of MyInputItem in the last two hours. It will automatically update and always reflect the latest changes of MyInputItem.

Inheritance diagram of HABApp.core.items.AggregationItem

class AggregationItem()

aggregation_func(func)

Set the function which will be used to aggregate all values. E.g. min or max

Parameters:: func (Callable[[Iterable], Any]) – The function which takes an iterator an returns an aggregated value. Important: the function must be non blocking!
Return type:: AggregationItem

aggregation_period(period)

Set the period in which the items will be aggregated

Parameters:: period (Union[float, int, timedelta]) – period in seconds
Return type:: AggregationItem

aggregation_source(source, only_changes=False)

Set the source item which changes will be aggregated

Parameters:

source (Union[BaseValueItem, str]) – name or Item obj
only_changes (bool) – if true only value changes instead of value updates will be added

Return type:

AggregationItem

classmethod get_create_item(name)

Creates a new AggregationItem in HABApp and returns it or returns the already existing item with the given name

Parameters:: name (str) – item name
Returns:: item

classmethod get_item(name)

Returns an already existing item. If it does not exist or has a different item type an exception will occur.

Parameters:: name (str) – Name of the item

get_value(default_value=None)

Return the value of the item. This is a helper function that returns a default in case the item value is None.

Parameters:: default_value – Return this value if the item value is None
Return type:: Any
Returns:: value of the item

listen_event(callback, event_filter=None)

Register an event listener which listens to all event that the item receives

Parameters:

callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event
event_filter (Optional[TypeVar(HINT_EVENT_FILTER_OBJ, bound= EventFilterBase)]) – Event filter. This is typically ValueUpdateEventFilter or ValueChangeEventFilter which will also trigger on changes/update from openhab or mqtt. Additionally it can be an instance of EventFilter which additionally filters on the values of the event. It is also possible to group filters logically with, e.g. AndFilterGroup and OrFilterGroup

Return type:

TypeVar(HINT_EVENT_BUS_LISTENER, bound= EventBusListener)

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
Return type:: bool
Returns:: True if state has changed

post_value_if(new_value, *, equal=<MISSING>, eq=<MISSING>, not_equal=<MISSING>, ne=<MISSING>, lower_than=<MISSING>, lt=<MISSING>, lower_equal=<MISSING>, le=<MISSING>, greater_than=<MISSING>, gt=<MISSING>, greater_equal=<MISSING>, ge=<MISSING>, is_=<MISSING>, is_not=<MISSING>)

Post a value depending on the current state of the item. If one of the comparisons is true the new state will be posted.

Parameters:

new_value – new value to post
equal – item state has to be equal to the passed value
eq – item state has to be equal to the passed value
not_equal – item state has to be not equal to the passed value
ne – item state has to be not equal to the passed value
lower_than – item state has to be lower than the passed value
lt – item state has to be lower than the passed value
lower_equal – item state has to be lower equal the passed value
le – item state has to be lower equal the passed value
greater_than – item state has to be greater than the passed value
gt – item state has to be greater than the passed value
greater_equal – item state has to be greater equal the passed value
ge – item state has to be greater equal the passed value
is – item state has to be the same object as the passt value (e.g. None)
is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

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

watch_change(secs)

Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (Union[int, float, timedelta]) – secs after which the event will occur, max 1 decimal digit for floats
Return type:: ItemNoChangeWatch
Returns:: The watch obj which can be used to cancel the watch

watch_update(secs)

Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (Union[int, float, timedelta]) – secs after which the event will occur, max 1 decimal digit for floats
Return type:: ItemNoUpdateWatch
Returns:: The watch obj which can be used to cancel the watch

property last_change: DateTime

Returns:: Timestamp of the last time when the item has been changed (read only)

property last_update: DateTime

Returns:: Timestamp of the last time when the item has been updated (read only)

property name: str

Returns:: Name of the item (read only)

BaseValueItem

Base class for items with values. All items that have a value must inherit from BaseValueItem May not be instantiated directly.

class BaseValueItem()

Simple item

Variables:

name (str) – Name of the item (read only)
value – Value of the item, can be anything (read only)
last_change (datetime) – Timestamp of the last time when the item has changed the value (read only)
last_update (datetime) – Timestamp of the last time when the item has updated the value (read only)

classmethod get_item(name)

Returns an already existing item. If it does not exist or has a different item type an exception will occur.

Parameters:: name (str) – Name of the item

get_value(default_value=None)

Return the value of the item. This is a helper function that returns a default in case the item value is None.

Parameters:: default_value – Return this value if the item value is None
Return type:: Any
Returns:: value of the item

listen_event(callback, event_filter=None)

Register an event listener which listens to all event that the item receives

Parameters:

callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event
event_filter (Optional[TypeVar(HINT_EVENT_FILTER_OBJ, bound= EventFilterBase)]) – Event filter. This is typically ValueUpdateEventFilter or ValueChangeEventFilter which will also trigger on changes/update from openhab or mqtt. Additionally it can be an instance of EventFilter which additionally filters on the values of the event. It is also possible to group filters logically with, e.g. AndFilterGroup and OrFilterGroup

Return type:

TypeVar(HINT_EVENT_BUS_LISTENER, bound= EventBusListener)

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
Return type:: bool
Returns:: True if state has changed

post_value_if(new_value, *, equal=<MISSING>, eq=<MISSING>, not_equal=<MISSING>, ne=<MISSING>, lower_than=<MISSING>, lt=<MISSING>, lower_equal=<MISSING>, le=<MISSING>, greater_than=<MISSING>, gt=<MISSING>, greater_equal=<MISSING>, ge=<MISSING>, is_=<MISSING>, is_not=<MISSING>)

Post a value depending on the current state of the item. If one of the comparisons is true the new state will be posted.

Parameters:

new_value – new value to post
equal – item state has to be equal to the passed value
eq – item state has to be equal to the passed value
not_equal – item state has to be not equal to the passed value
ne – item state has to be not equal to the passed value
lower_than – item state has to be lower than the passed value
lt – item state has to be lower than the passed value
lower_equal – item state has to be lower equal the passed value
le – item state has to be lower equal the passed value
greater_than – item state has to be greater than the passed value
gt – item state has to be greater than the passed value
greater_equal – item state has to be greater equal the passed value
ge – item state has to be greater equal the passed value
is – item state has to be the same object as the passt value (e.g. None)
is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

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

watch_change(secs)

Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (Union[int, float, timedelta]) – secs after which the event will occur, max 1 decimal digit for floats
Return type:: ItemNoChangeWatch
Returns:: The watch obj which can be used to cancel the watch

watch_update(secs)

Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.

Parameters:: secs (Union[int, float, timedelta]) – secs after which the event will occur, max 1 decimal digit for floats
Return type:: ItemNoUpdateWatch
Returns:: The watch obj which can be used to cancel the watch

property last_change: DateTime

Returns:: Timestamp of the last time when the item has been changed (read only)

property last_update: DateTime

Returns:: Timestamp of the last time when the item has been updated (read only)

property name: str

Returns:: Name of the item (read only)

Events

ValueUpdateEvent

This event gets emitted every time a value of an item receives an update

class ValueUpdateEvent(name, value)

Variables:

name (str) –
value (Any) –

ValueChangeEvent

This event gets emitted every time a value of an item changes

class ValueChangeEvent(name, value, old_value)

Variables:

name (str) –
value (Any) –
old_value (Any) –

ItemNoUpdateEvent

This event gets emitted when an item is watched for updates and no update has been made in a certain amount of time.

class ItemNoUpdateEvent(name, seconds)

Variables:

name (str) –
seconds (Union[int, float]) –

ItemNoChangeEvent

This event gets emitted when an item is watched for changes and no change has been made in a certain amount of time.

class ItemNoChangeEvent(name, seconds)

Variables:

name (str) –
seconds (Union[int, float]) –