openHAB

Additional configuration

For optimal performance it is recommended to use Basic Auth (available from openHAB 3.1 M3 on). It can be enabled through GUI or through textual configuration.

Textual configuration

The settings are in the runtime.cfg. Remove the # before the entry to activate it.

################ REST API ###################
org.openhab.restauth:allowBasicAuth=true

GUI

It can be enabled through the gui in settings -> API Security -> Allow Basic Authentication.

_images/openhab_api_config.png

openHAB item types

Description and example

Items that are created from openHAB inherit all from OpenhabItem and provide convenience functions which simplify many things.

Example:

from HABApp.openhab.items import ContactItem, SwitchItem

my_contact = ContactItem.get_item('MyContact')
if my_contact.is_open():
    print('Contact is open!')

my_switch = SwitchItem.get_item('MySwitch')
if my_switch.is_on():
    my_switch.off()
Contact is open!

NumberItem

Inheritance diagram of HABApp.openhab.items.NumberItem
class NumberItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

NumberItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (Union[int, float]) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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)

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

ContactItem

Inheritance diagram of HABApp.openhab.items.ContactItem
class ContactItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))
Variables
  • name (str) –

  • value (str) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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_closed()

Test value against closed-value

Return type

bool

is_open()

Test value against open-value

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)

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

SwitchItem

Inheritance diagram of HABApp.openhab.items.SwitchItem
class SwitchItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

SwitchItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (Tuple[str, ...]) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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

Test value against off-value

Return type

bool

is_on()

Test value against on-value

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)

off()

Command item off

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

on()

Command item on

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

DimmerItem

Inheritance diagram of HABApp.openhab.items.DimmerItem
class DimmerItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

DimmerItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (Union[int, float]) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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

Test value against off-value

Return type

bool

is_on()

Test value against on-value

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)

off()

Command item off

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

on()

Command item on

percent(value)

Command to value (in percent)

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

DatetimeItem

Inheritance diagram of HABApp.openhab.items.DatetimeItem
class DatetimeItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

DateTimeItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (datetime) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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)

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

RollershutterItem

Inheritance diagram of HABApp.openhab.items.RollershutterItem
class RollershutterItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

RollershutterItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (Union[int, float]) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

down()

Command down

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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_down()

Test value against off-value

Return type

bool

is_up()

Test value against on-value

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)

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

percent(value)

Command to value (in percent)

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

up()

Command up

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
Return type

DateTime

Returns

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

property last_update: 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

Inheritance diagram of HABApp.openhab.items.ColorItem
class ColorItem(name, h=0.0, s=0.0, b=0.0, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

ColorItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (Tuple[float, float, float]) –

  • hue (float) –

  • saturation (float) –

  • brightness (float) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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)

off()

Command item off

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

on()

Command item on

percent(value)

Command to value (in percent)

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

StringItem

Inheritance diagram of HABApp.openhab.items.StringItem
class StringItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

StringItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (str) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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)

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

LocationItem

Inheritance diagram of HABApp.openhab.items.LocationItem
class LocationItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

LocationItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (str) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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)

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

PlayerItem

Inheritance diagram of HABApp.openhab.items.PlayerItem
class PlayerItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

PlayerItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (str) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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)

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

GroupItem

Inheritance diagram of HABApp.openhab.items.GroupItem
class GroupItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

GroupItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (str) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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)

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: DateTime
Return type

DateTime

Returns

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

property members: Tuple[OpenhabItem, ...]

Resolves and then returns all group members

Return type

Tuple[OpenhabItem, ...]

property name: str
Return type

str

Returns

Name of the item (read only)

ImageItem

Inheritance diagram of HABApp.openhab.items.ImageItem
class ImageItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

ImageItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (bytes) –

  • image_type (Optional[str]) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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)

oh_post_update(data, img_type=None)

Post an update to an openHAB image with new image data. Image type is automatically detected, in rare cases when this does not work it can be set manually.

Parameters
  • data (bytes) – image data

  • img_type (Optional[str]) – (optional) what kind of image, jpeg or png

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(data, img_type=None)

Send a command to an openHAB image with new image data. Image type is automatically detected, in rare cases when this does not work it can be set manually.

Parameters
  • data (bytes) – image data

  • img_type (Optional[str]) – (optional) what kind of image, jpeg or png

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

CallItem

Inheritance diagram of HABApp.openhab.items.CallItem
class CallItem(name, initial_value=None, label=None, tags=frozenset({}), groups=frozenset({}), metadata=immutables.Map({}))

CallItem which accepts and converts the data types from OpenHAB

Variables
  • name (str) –

  • value (Tuple[str, ...]) –

  • label (Optional[str]) –

  • tags (FrozenSet[str]) –

  • groups (FrozenSet[str]) –

  • metadata (Mapping[str, MetaData]) –

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_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters
  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

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)

oh_post_update(value=_MissingType.MISSING)

Post an update to the openHAB item

Parameters

value (Any) – (optional) value to be posted. If not specified the current item value will be used.

oh_post_update_if(new_value, *, equal=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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

oh_send_command(value=_MissingType.MISSING)

Send a command to the openHAB item

Parameters

value (Any) – (optional) value to be sent. If not specified the current item value will be used.

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=_MissingType.MISSING, eq=_MissingType.MISSING, not_equal=_MissingType.MISSING, ne=_MissingType.MISSING, lower_than=_MissingType.MISSING, lt=_MissingType.MISSING, lower_equal=_MissingType.MISSING, le=_MissingType.MISSING, greater_than=_MissingType.MISSING, gt=_MissingType.MISSING, greater_equal=_MissingType.MISSING, ge=_MissingType.MISSING, is_=_MissingType.MISSING, is_not=_MissingType.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 – tem 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
Return type

DateTime

Returns

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

property last_update: 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)

Thing

Inheritance diagram of HABApp.openhab.items.Thing
class Thing(name)

Base class for Things

Variables
  • status (str) – Status of the thing (e.g. OFFLINE, ONLINE, …)

  • status_detail (str) – Additional detail for the status

  • label (str) – Thing label

  • configuration (Mapping[str, Any]) – Thing configuration

  • properties (Mapping[str, Any]) – Thing properties

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

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)

set_enabled(enable=True)

Enable/disable the thing

Parameters

enable (bool) – True to enable, False to disable the thing

Returns

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
Return type

DateTime

Returns

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

property last_update: 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)

Interaction with a openHAB

All interaction with the openHAB is done through the self.oh or self.openhab object in the rule or through an OpenhabItem.

_images/openhab.gif

Function parameters

post_update(item_name, state)

Post an update to the item

Parameters
  • item_name (str) – item name or item

  • state (Any) – new item state

send_command(item_name, command)

Send the specified command to the item

Parameters
  • item_name (str) – item name or item

  • command – command

get_item(item_name, metadata=None, all_metadata=False)

Return the complete openHAB item definition

Parameters
  • item_name (str) – name of the item or item

  • metadata (Optional[str]) – metadata to include (optional, comma separated or search expression)

  • all_metadata – if true the result will include all item metadata

Return type

OpenhabItemDefinition

Returns

openHAB item

item_exists(item_name)

Check if an item exists in the openHAB item registry

Parameters

item_name (str) – name

Returns

True if item was found

remove_item(item_name)

Removes an item from the openHAB item registry

Parameters

item_name (str) – name

Returns

True if item was found and removed

create_item(item_type, name, label='', category='', tags=[], groups=[], group_type='', group_function='', group_function_params=[])

Creates a new item in the openHAB item registry or updates an existing one

Parameters
  • item_type (str) – item type

  • name (str) – item name

  • label – item label

  • category – item category

  • tags (List[str]) – item tags

  • groups (List[str]) – in which groups is the item

  • group_type (str) – what kind of group is it

  • group_function (str) – group state aggregation function

  • group_function_params (List[str]) – params for group state aggregation

Returns

True if item was created/updated

get_thing(thing_name)

Return the complete openHAB thing definition

Parameters

thing_name (str) – name of the thing or the item

Return type

OpenhabThingDefinition

Returns

openHAB thing

set_thing_enabled(thing_name, enabled=True)

Enable/disable a thing

Parameters
  • thing_name (str) – name of the thing or the thing object

  • enabled (bool) – True to enable thing, False to disable thing

get_persistence_data(item_name, persistence, start_time, end_time)

Query historical data from the openHAB persistence service

Parameters
  • item_name (str) – name of the persistent item

  • persistence (Optional[str]) – name of the persistence service (e.g. rrd4j, mapdb). If not set default will be used

  • start_time (Optional[datetime]) – return only items which are newer than this

  • end_time (Optional[datetime]) – return only items which are older than this

Return type

OpenhabPersistenceData

Returns

last stored data from persistency service

remove_metadata(item_name, namespace)

Remove metadata from an item

Parameters
  • item_name (str) – name of the item or item

  • namespace (str) – namespace

Returns

True if metadata was successfully removed

set_metadata(item_name, namespace, value, config)

Add/set metadata to an item

Parameters
  • item_name (str) – name of the item or item

  • namespace (str) – namespace

  • value (str) – value

  • config (dict) – configuration

Returns

True if metadata was successfully created/updated

returns the ItemChannelLinkDefinition for a link between a (things) channel and an item

Parameters
  • channel_uid (str) – uid of the (things) channel (usually something like AAAA:BBBBB:CCCCC:DDDD:0#SOME_NAME)

  • item_name (str) – name of the item

Return type

ItemChannelLinkDefinition

Returns

an instance of ItemChannelLinkDefinition or None on error

removes a link between a (things) channel and an item

Parameters
  • channel_uid (str) – uid of the (thing) channel (usually something like AAAA:BBBBB:CCCCC:DDDD:0#SOME_NAME)

  • item_name (str) – name of the item

Return type

bool

Returns

True on successful removal, otherwise False

check if a things channel is linked to an item

Parameters
  • channel_uid (str) – uid of the linked channel (usually something like AAAA:BBBBB:CCCCC:DDDD:0#SOME_NAME)

  • item_name (str) – name of the linked item

Return type

bool

Returns

True when the link exists, otherwise False

creates a link between a (things) channel and an item

Parameters
  • channel_uid (str) – uid of the (thing) channel (usually something like AAAA:BBBBB:CCCCC:DDDD:0#SOME_NAME)

  • item_name (str) – name of the item

  • configuration (Optional[Dict[str, Any]]) – optional configuration for the channel

Return type

bool

Returns

True on successful creation, otherwise False

openHAB event types

openHAB produces various events that are mapped to the internal event bus. On the openHAB page there is an explanation for the various events.

Item events

ItemStateEvent

Since this event inherits from ValueUpdateEvent you can listen to ValueUpdateEvent and it will also trigger for ItemStateEvent.

Inheritance diagram of HABApp.openhab.events.ItemStateEvent
class ItemStateEvent(name='', value=None)
Variables
  • name (str) –

  • value

ItemStateChangedEvent

Since this event inherits from ValueChangeEvent you can listen to ValueChangeEvent and it will also trigger for ItemStateChangedEvent.

Inheritance diagram of HABApp.openhab.events.ItemStateChangedEvent
class ItemStateChangedEvent(name='', value=None, old_value=None)
Variables
  • name (str) –

  • value

  • old_value

ItemCommandEvent

Inheritance diagram of HABApp.openhab.events.ItemCommandEvent
class ItemCommandEvent(name='', value=None)
Variables
  • name (str) –

  • value

ItemAddedEvent

Inheritance diagram of HABApp.openhab.events.ItemAddedEvent
class ItemAddedEvent(name='', type='', label=None, tags=frozenset({}), group_names=frozenset({}))
Variables
  • name (str) –

  • type (str) –

  • label (Optional[str]) –

  • tags (Tuple[str,...]) –

  • group_names (Tuple[str,...]) –

ItemUpdatedEvent

Inheritance diagram of HABApp.openhab.events.ItemUpdatedEvent
class ItemUpdatedEvent(name='', type='', label=None, tags=frozenset({}), group_names=frozenset({}))
Variables
  • name (str) –

  • type (str) –

  • tags (Tuple[str,...]) –

  • group_names (Tuple[str,...]) –

ItemRemovedEvent

Inheritance diagram of HABApp.openhab.events.ItemRemovedEvent
class ItemRemovedEvent(name='')
Variables

name (str) –

ItemStatePredictedEvent

Inheritance diagram of HABApp.openhab.events.ItemStatePredictedEvent
class ItemStatePredictedEvent(name='', value=None)
Variables
  • name (str) –

  • value

GroupItemStateChangedEvent

Inheritance diagram of HABApp.openhab.events.GroupItemStateChangedEvent
class GroupItemStateChangedEvent(name='', item='', value=None, old_value=None)
Variables
  • name (str) –

  • item (str) –

  • value

  • old_value

Channel events

ChannelTriggeredEvent

Inheritance diagram of HABApp.openhab.events.ChannelTriggeredEvent
class ChannelTriggeredEvent(name='', event='', channel='')
Variables
  • name (str) –

  • event (str) –

  • channel (str) –

Thing events

ThingAddedEvent

Inheritance diagram of HABApp.openhab.events.ThingAddedEvent
class ThingAddedEvent(name='', thing_type='', label='', channels=None, configuration=None, properties=None)

ThingUpdatedEvent

Inheritance diagram of HABApp.openhab.events.ThingUpdatedEvent
class ThingUpdatedEvent(name='', thing_type='', label='', channels=None, configuration=None, properties=None)

ThingRemovedEvent

Inheritance diagram of HABApp.openhab.events.ThingRemovedEvent
class ThingRemovedEvent(name='', thing_type='', label='', channels=None, configuration=None, properties=None)

ThingStatusInfoEvent

Inheritance diagram of HABApp.openhab.events.ThingStatusInfoEvent
class ThingStatusInfoEvent(name='', status='', detail='')
Variables
  • name (str) –

  • status (str) –

  • detail (str) –

ThingStatusInfoChangedEvent

Inheritance diagram of HABApp.openhab.events.ThingStatusInfoChangedEvent
class ThingStatusInfoChangedEvent(name='', status='', detail='', old_status='', old_detail='')
Variables
  • name (str) –

  • status (str) –

  • detail (str) –

  • old_status (str) –

  • old_detail (str) –

ThingFirmwareStatusInfoEvent

Inheritance diagram of HABApp.openhab.events.ThingFirmwareStatusInfoEvent
class ThingFirmwareStatusInfoEvent(name='', status='')
Variables
  • name (str) –

  • status (str) –

Event filters

ItemStateEventFilter

Inheritance diagram of HABApp.openhab.events.ItemStateEventFilter
class ItemStateEventFilter(value=_MissingType.MISSING)

ItemStateChangedEventFilter

Inheritance diagram of HABApp.openhab.events.ItemStateChangedEventFilter
class ItemStateChangedEventFilter(value=_MissingType.MISSING, old_value=_MissingType.MISSING)

ItemCommandEventFilter

Inheritance diagram of HABApp.openhab.events.ItemCommandEventFilter
class ItemCommandEventFilter(value=_MissingType.MISSING)

Textual thing configuration

Description

HABApp offers a special mechanism to textually define thing configuration parameters and linked items for things which have been added through the gui. This combines the best of both worlds: auto discovery, easy and fast sharing of parameters and items across things.

Configuration is done in the thing_your_name.yml file in the config folder (see Configuration). Every file that starts with thing_ has the .yml ending will be loaded.

The Parameters and items will be checked/set when HABApp connects to openHAB or whenever the corresponding file gets changed.

Principle of operation

All existing things from openHAB can be filtered by different criteria. For each one of these remaining things it is then possible to

  • Set thing parameters

  • Create items with values taken from the thing fields

  • Apply filters to the channels of the thing
    For each matching channel it is possible to create and link items with values taken from the thing and the matching channel values

There is also a test mode which prints out all required information and does not make any changes.

A valid .items file will automatically be created next to the .yml file containing all created items. It can be used to get a quick overview what items (would) have been created or copied into the items folder.

File Structure

Configuration is done through a .yml file.

Example

The following example will show how to set the Z-Wave Parameters 4, 5, 6 and 8 for a Philio PST02A Z-Wave sensor and how to automatically link items to it.

Tip

Integer values can be specified either as integer (20) or hex (0x14)

The entries thing config, create items and channels are optional and can be combined as desired.

# Test mode: will not do anything but instead print out information
test: True

# Define filters which will reduce the number of things,
# all defined filters have to match for further processing
filter:
  thing_type: zwave:philio_pst02a_00_000

# Set this configuration every matching thing. HABApp will automatically only
# change the values which are not already correct.
# Here it is the z-wave parameters which are responsible for the device behaviour
thing config:
  4: 99     # Light Threshold
  5: 8      # Operation Mode
  6: 4      # MultiSensor Function Switch
  7: 20     # Customer Function

# Create items for every matching thing
create items:
 - type: Number
   name: '{thing_label, :(.+)$}_MyNumber'          # Use the label from the thing as an input for the name,
   label: '{thing_label, :(.+)$} MyNumber [%d]'    # the regex will take everything from the ':' on until the end
   icon: battery

channels:
  # reduce the channels of the thing with these filters
  # and link items to it
  - filter:
      channel_type: zwave:alarm_motion
    link items:
      - type: Number
        name: '{thing_label, :(.+)$}_Movement'           # Use the label from the thing as an input for the name,
        label: '{thing_label, :(.+)$} Movement [%d %%]'  # the regex will take everything from the ':' on until the end
        icon: battery
        groups: ['group1', 'group2']
        tags: ['tag1']

  - filter:
      channel_type: zwave:sensor_temperature
    link items:
      - type: Number
        name: '{thing_label, :(.+)$}_Temperature'
        label: '{thing_label, :(.+)$} Temperature [%d %%]'
        icon: battery

Multiple filters and filter definitions in one file

It is possible to add multiple thing processors into one file. To achieve this the root entry is now a list.

Filters can also be lists e.g. if the have to be applied multiple times to the same filed.

- test: True
  filter:
    thing_type: zwave:philio_pst02a_00_000
  ...

- test: True
  # multiple filters on the same field, all have to match
  filter:
  - thing_type: zwave:fibaro.+
  - thing_type: zwave:fibaro_fgrgbw_00_000
  ...

Thing configuration

With the thing config block it is possible to set a configuration for each matching thing. If the parameters are already correct, they will not be set again.

Warning

The value of the configuration parameters will not be checked and will be written as specified. It is recommended to use HABmin or PaperUI to generate the initial configuration and use this mechanism to spread it to things of the same type.

Example

thing config:
  4: 99     # Light Threshold
  5: 8      # Operation Mode
  6: 4      # MultiSensor Function Switch
  7: 20     # Customer Function

References to other parameters

It is possible to use references to mathematically build parameters from other parameters. Typically this would be fade duration and refresh interval. References to other parameter values can be created with $. Example:

thing config:
  5: 8
  6: '$5 / 2'       # Use value from parameter 5 and divide it by two.
  7: 'int($5 / 2)'  # it is possible to use normal python data conversions

Item configuration

Items can be configured under create items -> [] and channels -> [] -> link items -> [].

Structure

Mandatory values are type and name, all other values are optional.

type: Number
name: my_name
label: my_label
icon: my_icon
groups: ['group1', 'group2']
tags: ['tag1', 'tag1']

Metadata

It is possible to add metadata to the created items through the optional metadata entry in the item config.

There are two forms how metadata can be set. The implicit form for simple key-value pairs (e.g. autoupdate) or the explicit form where the entries are under value and config (e.g. alexa)

- type: Number
  name: '{thing_label, :(.+)$}_Temperature'
  label: '{thing_label, :(.+)$} Temperature [%d %%]'
  icon: battery
  metadata:
    autoupdate: 'false'
    homekit: 'TemperatureSensor'
    alexa:
      'value': 'Fan'
      'config':
        'type': 'oscillating'
        'speedSteps': 3

The config is equivalent to the following item configuration:

Number MyLabel_Temperature  "MyLabel Temperature [%d %%]" { autoupdate="false", homekit="TemperatureSensor", alexa="Fan" [ type="oscillating", speedSteps=3 ] }

Fields

Filtering things/channels

The filter value can be applied to any available field from the Thing/Channel. The filter value is a regex that has to fully match the value.

Syntax:

filter:
  FIELD_NAME: REGULAR_EXPRESSION

e.g.

filter:
  thing_uid: zwave:device:controller:node35

If multiple filters are specified all have to match to select the Thing or Channel.

# Multiple filters on different columns
filter:
  thing_type: zwave:fibaro.+
  thing_uid: zwave:device:controller:node35

# Multiple filters on the same columns (rarely needed)
filter:
- thing_type: zwave:fibaro.+
- thing_type: zwave:fibaro_fgrgbw_00_000

Field values as inputs

Filed values are available for item configuration and can be applied to all fields in the item configuration except for type and metadata.

Syntax

Macros that select field values are framed with {} so the containing string has to be put in annotation marks. There are three modes of operation with wildcards:

  1. Just insert the value from the field:
    {field}
  2. Insert a part of the value from the field. A regular expression is used to extract the part and therefore has to contain a capturing group.
    {field, regex(with_group)}
  3. Do a regex replace on the value from the field and use the result
    {field, regex, replace}

Available fields

Tip

Test mode will show a table with all available fields and their value

The following fields are available for things:

  • thing_uid

  • thing_type

  • thing_location

  • thing_label

  • bridge_uid

Additional available fields for channels:

  • channel_uid

  • channel_type

  • channel_label

  • channel_kind

Example

Log output

This will show the output for the example from File Structure

Loading /config/thing_philio.yml!
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|                                                                                   Thing overview                                                                                 |
+---------------------------------+----------------------------+----------------+----------------------------------------+----------------------------------------------+----------+
|           thing_uid             |         thing_type         | thing_location |            thing_label                 |                  bridge_uid                  | editable |
+---------------------------------+----------------------------+----------------+----------------------------------------+----------------------------------------------+----------+
| zwave:device:controller:node32  | zwave:fibaro_fgrgbw_00_000 | Room1          | Fibaro RGBW (Node 32): Room1 RGBW      | zwave:serial_zstick:controller               | True     |
| zwave:device:controller:node7   | zwave:fibaro_fgrgbw_00_000 | Room2          | Fibaro RGBW (Node 07): Room2 RGBW      | zwave:serial_zstick:controller               | True     |
| zwave:device:controller:node23  | zwave:fibaro_fgrgbw_00_000 | Room3          | Fibaro RGBW (Node 23): Room3 RGBW      | zwave:serial_zstick:controller               | True     |
| zwave:device:controller:node35  | zwave:philio_pst02a_00_000 | Room1          | Philio PST02A (Node 35): Room1 Door    | zwave:serial_zstick:controller               | True     |
| zwave:device:controller:node15  | zwave:philio_pst02a_00_000 | Room2          | Philio PST02A (Node 15): Room2 Window  | zwave:serial_zstick:controller               | True     |
| zwave:device:controller:node17  | zwave:philio_pst02a_00_000 | Room3          | Philio PST02A (Node 17): Room3 Window  | zwave:serial_zstick:controller               | True     |
| zwave:device:controller:node3   | zwave:philio_pst02a_00_000 | Room1          | Philio PST02A (Node 03): Room1 Window  | zwave:serial_zstick:controller               | True     |
| zwave:device:controller:node5   | zwave:philio_pst02a_00_000 | Room4          | Philio PST02A (Node 05): FrontDoor     | zwave:serial_zstick:controller               | True     |
| zwave:serial_zstick:controller  | zwave:serial_zstick        |                | ZWave Controller                       |                                              | False    |
+---------------------------------+----------------------------+----------------+----------------------------------------+----------------------------------------------+----------+
thing_type "zwave:philio_pst02a_00_000" matches for zwave:device:controller:node35!
thing_type "zwave:philio_pst02a_00_000" matches for zwave:device:controller:node15!
thing_type "zwave:philio_pst02a_00_000" matches for zwave:device:controller:node17!
thing_type "zwave:philio_pst02a_00_000" matches for zwave:device:controller:node3!
thing_type "zwave:philio_pst02a_00_000" matches for zwave:device:controller:node5!
+---------------------------------------------------------------------------------------------------------------------------+
|                                                   Current configuration                                                   |
+-------------------------+-------------------+-------------------+-------------------+------------------+------------------+
|        Parameter        | controller:node35 | controller:node15 | controller:node17 | controller:node3 | controller:node5 |
+-------------------------+-------------------+-------------------+-------------------+------------------+------------------+
| 2                       | -1                | -1                | -1                | -1               | -1               |
| 3                       | 80                | 80                | 80                | 80               | 80               |
| 4                       | 99                | 99                | 99                | 99               | 99               |
| 5                       | 0                 | 8                 | 8                 | 8                | 8                |
| 6                       | 4                 | 0                 | 0                 | 0                | 0                |
| 7                       | 22                | 20                | 20                | 20               | 20               |
| 8                       | 3                 | 3                 | 3                 | 3                | 3                |
| 9                       | 4                 | 0                 | 4                 | 4                | 4                |
| 10                      | 12                | 12                | 12                | 12               | 12               |
| 11                      | 12                | 12                | 12                | 12               | 12               |
| 12                      | 12                | 12                | 2                 | 12               | 4                |
| 13                      | 12                | 12                | 2                 | 12               | 4                |
| 20                      | 30                | 30                | 30                | 30               | 30               |
| 21                      | 1                 | 0                 | 0                 | 0                | 0                |
| 22                      | 0                 | 0                 | 0                 | 0                | 0                |
| Group1                  | ['controller']    | ['controller']    | ['controller']    | ['controller']   | ['controller']   |
| Group2                  | []                | []                | []                | []               | []               |
| binding_cmdrepollperiod | 1500              | 1500              | 1500              | 1500             | 1500             |
| binding_pollperiod      | 86400             | 86400             | 86400             | 86400            | 86400            |
| wakeup_interval         | 86400             | 86400             | 86400             | 86400            | 86400            |
+-------------------------+-------------------+-------------------+-------------------+------------------+------------------+
Would set {5: 8, 7: 20} for zwave:device:controller:node35
Would set {6: 4} for zwave:device:controller:node15
Would set {6: 4} for zwave:device:controller:node17
Would set {6: 4} for zwave:device:controller:node3
Would set {6: 4} for zwave:device:controller:node5
+----------------------------------------------------------------------------------------------------------------------+
|                                       Channels for zwave:philio_pst02a_00_000                                        |
+---------------------------------------------------+--------------------------+------------------------+--------------+
|                    channel_uid                    |       channel_type       |     channel_label      | channel_kind |
+---------------------------------------------------+--------------------------+------------------------+--------------+
| zwave:device:controller:node35:sensor_door        | zwave:sensor_door        | Door/Window Sensor     | STATE        |
| zwave:device:controller:node35:alarm_motion       | zwave:alarm_motion       | Motion Sensor          | STATE        |
| zwave:device:controller:node35:alarm_tamper       | zwave:alarm_tamper       | Tamper Alarm           | STATE        |
| zwave:device:controller:node35:sensor_luminance   | zwave:sensor_luminance   | Sensor (luminance)     | STATE        |
| zwave:device:controller:node35:sensor_temperature | zwave:sensor_temperature | Sensor (temperature)   | STATE        |
| zwave:device:controller:node35:alarm_access       | zwave:alarm_access       | Alarm (Access Control) | STATE        |
| zwave:device:controller:node35:alarm_burglar      | zwave:alarm_burglar      | Alarm (Burglar)        | STATE        |
| zwave:device:controller:node35:battery-level      | system:battery-level     | Batterieladung         | STATE        |
+---------------------------------------------------+--------------------------+------------------------+--------------+
channel_type "zwave:alarm_motion" matches for zwave:device:controller:node35:alarm_motion!
channel_type "zwave:sensor_temperature" matches for zwave:device:controller:node35:sensor_temperature!

channel_type "zwave:alarm_motion" matches for zwave:device:controller:node15:alarm_motion!
channel_type "zwave:sensor_temperature" matches for zwave:device:controller:node15:sensor_temperature!

channel_type "zwave:alarm_motion" matches for zwave:device:controller:node17:alarm_motion!
channel_type "zwave:sensor_temperature" matches for zwave:device:controller:node17:sensor_temperature!

channel_type "zwave:alarm_motion" matches for zwave:device:controller:node3:alarm_motion!
channel_type "zwave:sensor_temperature" matches for zwave:device:controller:node3:sensor_temperature!

channel_type "zwave:alarm_motion" matches for zwave:device:controller:node5:alarm_motion!
channel_type "zwave:sensor_temperature" matches for zwave:device:controller:node5:sensor_temperature!

Would create Item(type='Number', name='Room1_Door_MyNumber', label='Room1 Door MyNumber [%d]', icon='battery', groups=[], tags=[], link=None)
Would create Item(type='Number', name='Room1_Door_Movement', label='Room1 Door Movement [%d %%]', icon='battery', groups=['group1', 'group2'], tags=['tag1'], link='zwave:device:controller:node35:alarm_motion')
Would create Item(type='Number', name='Room1_Door_Temperature', label='Room1 Door Temperature [%d %%]', icon='battery', groups=[], tags=[], link='zwave:device:controller:node35:sensor_temperature')
Would create Item(type='Number', name='Room2_Window_MyNumber', label='Room2 Window MyNumber [%d]', icon='battery', groups=[], tags=[], link=None)
Would create Item(type='Number', name='Room2_Window_Movement', label='Room2 Window Movement [%d %%]', icon='battery', groups=['group1', 'group2'], tags=['tag1'], link='zwave:device:controller:node15:alarm_motion')
Would create Item(type='Number', name='Room2_Window_Temperature', label='Room2 Window Temperature [%d %%]', icon='battery', groups=[], tags=[], link='zwave:device:controller:node15:sensor_temperature')
Would create Item(type='Number', name='Room3_Window_MyNumber', label='Room3 Window MyNumber [%d]', icon='battery', groups=[], tags=[], link=None)
Would create Item(type='Number', name='Room3_Window_Movement', label='Room3 Window Movement [%d %%]', icon='battery', groups=['group1', 'group2'], tags=['tag1'], link='zwave:device:controller:node17:alarm_motion')
Would create Item(type='Number', name='Room3_Window_Temperature', label='Room3 Window Temperature [%d %%]', icon='battery', groups=[], tags=[], link='zwave:device:controller:node17:sensor_temperature')
Would create Item(type='Number', name='Room1_Window_MyNumber', label='Room1 Window MyNumber [%d]', icon='battery', groups=[], tags=[], link=None)
Would create Item(type='Number', name='Room1_Window_Movement', label='Room1 Window Movement [%d %%]', icon='battery', groups=['group1', 'group2'], tags=['tag1'], link='zwave:device:controller:node3:alarm_motion')
Would create Item(type='Number', name='Room1_Window_Temperature', label='Room1 Window Temperature [%d %%]', icon='battery', groups=[], tags=[], link='zwave:device:controller:node3:sensor_temperature')
Would create Item(type='Number', name='FrontDoor_MyNumber', label='FrontDoor MyNumber [%d]', icon='battery', groups=[], tags=[], link=None)
Would create Item(type='Number', name='FrontDoor_Movement', label='FrontDoor Movement [%d %%]', icon='battery', groups=['group1', 'group2'], tags=['tag1'], link='zwave:device:controller:node5:alarm_motion')
Would create Item(type='Number', name='FrontDoor_Temperature', label='FrontDoor Temperature [%d %%]', icon='battery', groups=[], tags=[], link='zwave:device:controller:node5:sensor_temperature')

Created items file

Number   Room1_Door_MyNumber         "Room1 Door MyNumber [%d]"             <battery>
Number   Room1_Door_Movement         "Room1 Door Movement [%d %%]"          <battery>    (group1, group2)     [tag1]   {channel = "zwave:device:controller:node35:alarm_motion"}
Number   Room1_Door_Temperature      "Room1 Door Temperature [%d %%]"       <battery>                                  {channel = "zwave:device:controller:node35:sensor_temperature"}
Number   Room2_Window_MyNumber       "Room2 Window MyNumber [%d]"           <battery>
Number   Room2_Window_Movement       "Room2 Window Movement [%d %%]"        <battery>    (group1, group2)     [tag1]   {channel = "zwave:device:controller:node15:alarm_motion"}
Number   Room2_Window_Temperature    "Room2 Window Temperature [%d %%]"     <battery>                                  {channel = "zwave:device:controller:node15:sensor_temperature"}
Number   Room3_Window_MyNumber       "Room3 Window MyNumber [%d]"           <battery>
Number   Room3_Window_Movement       "Room3 Window Movement [%d %%]"        <battery>    (group1, group2)     [tag1]   {channel = "zwave:device:controller:node17:alarm_motion"}
Number   Room3_Window_Temperature    "Room3 Window Temperature [%d %%]"     <battery>                                  {channel = "zwave:device:controller:node17:sensor_temperature"}
Number   Room1_Window_MyNumber       "Room1 Window MyNumber [%d]"           <battery>
Number   Room1_Window_Movement       "Room1 Window Movement [%d %%]"        <battery>    (group1, group2)     [tag1]   {channel = "zwave:device:controller:node3:alarm_motion"}
Number   Room1_Window_Temperature    "Room1 Window Temperature [%d %%]"     <battery>                                  {channel = "zwave:device:controller:node3:sensor_temperature"}
Number   FrontDoor_MyNumber          "FrontDoor MyNumber [%d]"              <battery>
Number   FrontDoor_Movement          "FrontDoor Movement [%d %%]"           <battery>    (group1, group2)     [tag1]   {channel = "zwave:device:controller:node5:alarm_motion"}
Number   FrontDoor_Temperature       "FrontDoor Temperature [%d %%]"        <battery>                                  {channel = "zwave:device:controller:node5:sensor_temperature"}

Example openHAB rules

Example 1

import HABApp
from HABApp.core.events import ValueUpdateEvent, ValueChangeEvent
from HABApp.openhab.events import ItemStateEvent, ItemCommandEvent, ItemStateChangedEvent
from HABApp.openhab.items import SwitchItem, ContactItem, DatetimeItem


class MyOpenhabRule(HABApp.Rule):

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

        # get items
        test_contact = ContactItem.get_item('TestContact')
        test_date_time = DatetimeItem.get_item('TestDateTime')
        test_switch = SwitchItem.get_item('TestSwitch')

        # Trigger on item updates
        test_contact.listen_event(self.item_state_update, ItemStateEvent)
        test_date_time.listen_event(self.item_state_update, ValueUpdateEvent)

        # Trigger on item changes
        test_contact.listen_event(self.item_state_change, ItemStateChangedEvent)
        test_date_time.listen_event(self.item_state_change, ValueChangeEvent)

        # Trigger on item commands
        test_switch.listen_event(self.item_command, ItemCommandEvent)

    def item_state_update(self, event):
        assert isinstance(event, ValueUpdateEvent)
        print(f'{event}')

    def item_state_change(self, event):
        assert isinstance(event, ValueChangeEvent)
        print(f'{event}')

        # interaction is available through self.openhab or self.oh
        self.openhab.send_command('TestItemCommand', 'ON')

        # example for interaction with openhab item type
        switch_item = SwitchItem.get_item('TestSwitch')
        if switch_item.is_on():
            switch_item.off()

    def item_command(self, event):
        assert isinstance(event, ItemCommandEvent)
        print( f'{event}')

        # interaction is available through self.openhab or self.oh
        self.oh.post_update('ReceivedCommand', str(event))


MyOpenhabRule()

Check status of things

This rule prints the status of all Things and shows how to subscribe to events of the Thing status

from HABApp import Rule
from HABApp.openhab.events import ThingStatusInfoChangedEvent
from HABApp.openhab.items import Thing
from HABApp.core.events import EventFilter


class CheckAllThings(Rule):
    def __init__(self):
        super().__init__()

        for thing in self.get_items(Thing):
            thing.listen_event(self.thing_status_changed, EventFilter(ThingStatusInfoChangedEvent))
            print(f'{thing.name}: {thing.status}')

    def thing_status_changed(self, event: ThingStatusInfoChangedEvent):
        print(f'{event.name} changed from {event.old_status} to {event.status}')


CheckAllThings()

Check status if thing is constant

Sometimes Things recover automatically from small outages. This rule only triggers when the Thing is constant for 60 seconds.

from HABApp import Rule
from HABApp.core.events import ItemNoChangeEvent
from HABApp.openhab.items import Thing


class CheckThing(Rule):
    def __init__(self, name: str):
        super().__init__()

        self.thing = Thing.get_item(name)
        watcher = self.thing.watch_change(60)
        watcher.listen_event(self.thing_no_change)

    def thing_no_change(self, event: ItemNoChangeEvent):
        print(f'Thing {event.name} constant for {event.seconds}')
        print(f'Status: {self.thing.status}')


CheckThing('my:thing:uid')
Thing test_watch constant for 60
Status: ONLINE