HABApp¶
This page describes the HABApp internals
Items¶
Item¶
- class HABApp.core.items.Item(name, initial_value=None)¶
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 nameinitial_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_value(default_value=None)¶
Return the value of the item.
- Parameters
default_value – Return this value if the item value is None
- Return type
Any
- Returns
value of the item
- listen_event(callback, event_type)¶
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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
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
- 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
- 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
- Returns
The watch obj which can be used to cancel the watch
- property last_change: pendulum.datetime.DateTime¶
- Return type
DateTime
- Returns
Timestamp of the last time when the item has been changed (read only)
- property last_update: pendulum.datetime.DateTime¶
- Return type
DateTime
- Returns
Timestamp of the last time when the item has been updated (read only)
- property name: str¶
- Return type
str
- Returns
Name of the item (read only)
ColorItem¶
- class HABApp.core.items.ColorItem(name, hue=0.0, saturation=0.0, brightness=0.0)¶
Item for dealing with color related values
- 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.
- 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_type)¶
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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
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
- 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 %)
- 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
- 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
- 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
- Returns
The watch obj which can be used to cancel the watch
- property last_change: pendulum.datetime.DateTime¶
- Return type
DateTime
- Returns
Timestamp of the last time when the item has been changed (read only)
- property last_update: pendulum.datetime.DateTime¶
- Return type
DateTime
- Returns
Timestamp of the last time when the item has been updated (read only)
- property name: str¶
- Return type
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
.
- class HABApp.core.items.AggregationItem(name)¶
- aggregation_func(func)¶
Set the function which will be used to aggregate all values. E.g.
min
ormax
- 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
- aggregation_period(period)¶
Set the period in which the items will be aggregated
- Parameters
period (
Union
[float
,int
,timedelta
]) – period in seconds- Return type
- aggregation_source(source, only_changes=False)¶
Set the source item which changes will be aggregated
- Parameters
source (
Union
[BaseValueItem
,str
]) – name or Item objonly_changes (
bool
) – if true only value changes instead of value updates will be added
- Return type
- classmethod get_create_item(name)¶
Creates a new AggregationItem in HABApp and returns it or returns the already existing one 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.
- Parameters
default_value – Return this value if the item value is None
- Return type
Any
- Returns
value of the item
- listen_event(callback, event_type)¶
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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
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
- 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
- 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
- Returns
The watch obj which can be used to cancel the watch
- property last_change: pendulum.datetime.DateTime¶
- Return type
DateTime
- Returns
Timestamp of the last time when the item has been changed (read only)
- property last_update: pendulum.datetime.DateTime¶
- Return type
DateTime
- Returns
Timestamp of the last time when the item has been updated (read only)
- property name: str¶
- Return type
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 HABApp.core.items.BaseValueItem(name, initial_value=None)¶
Simple item
- Variables
name (str) – Name of the item (read only)
value – Value of the item, can be anything (read only)
last_change (datetime.datetime) – Timestamp of the last time when the item has changed the value (read only)
last_update (datetime.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.
- Parameters
default_value – Return this value if the item value is None
- Return type
Any
- Returns
value of the item
- listen_event(callback, event_type)¶
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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
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
- 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
- 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
- Returns
The watch obj which can be used to cancel the watch
- property last_change: pendulum.datetime.DateTime¶
- Return type
DateTime
- Returns
Timestamp of the last time when the item has been changed (read only)
- property last_update: pendulum.datetime.DateTime¶
- Return type
DateTime
- Returns
Timestamp of the last time when the item has been updated (read only)
- property name: str¶
- Return type
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 HABApp.core.events.ValueUpdateEvent(name=None, value=None)¶
- Variables
name (str) –
value –
ValueChangeEvent¶
This event gets emitted every time a value of an item changes
- class HABApp.core.events.ValueChangeEvent(name=None, value=None, old_value=None)¶
- Variables
name (str) –
value –
old_value –
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 HABApp.core.events.ItemNoUpdateEvent(name=None, seconds=None)¶
- 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 HABApp.core.events.ItemNoChangeEvent(name=None, seconds=None)¶
- Variables
name (str) –
seconds (Union[int, float]) –