openHAB

Additional configuration

For optimal performance it is recommended to use Basic Auth. 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.

OpenHAB user

In case an additional openHAB user or token is created for HABApp it has to have admin rights.

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!
/home/docs/.asdf/installs/python/3.13.14/lib/python3.13/asyncio/base_events.py:569: ResourceWarning: asynchronous generator <async_generator object HabAppObjProvider._reentrant_lock at 0x769a073ba890> was scheduled after loop.shutdown_asyncgens() call

NumberItem

class NumberItem()

NumberItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (int | float) – Current item value (or state in openHAB wording)

• last_value (int | float) – Last item value (or state in openHAB wording) before the current value one

• dimension (str | None) – Dimension if it’s a UoM item

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

oh_post_update(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value (float | None) – 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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

property unit: str | None

Return the item unit if it is a “Unit of Measurement” item else None

ContactItem

class ContactItem()

Variables:

• name (str) – Item name

• value (Literal['OPEN', 'CLOSED']) – Current item value (or state in openHAB wording)

• last_value (Literal['OPEN', 'CLOSED']) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

closed()

Post an update to the item with the closed value

Return type:

None

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

oh_post_update(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

open()

Post an update to the item with the open value

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value – new value of the item

Return type:

bool

Returns:

True if state has changed

watch_change(secs)

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

Parameters:

secs (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

SwitchItem

class SwitchItem()

SwitchItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (Literal['ON', 'OFF']) – Current item value (or state in openHAB wording)

• last_value (Literal['ON', 'OFF']) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

off()

Command item off

Return type:

None

oh_post_update(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

on()

Command item on

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value (str | None) – new value of the item

Return type:

bool

Returns:

True if state has changed

toggle()

Toggle the switch. Turns the switch on when off or off when currently on.

Return type:

None

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

DimmerItem

class DimmerItem()

DimmerItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (int | float) – Current item value (or state in openHAB wording)

• last_value (int | float) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

off()

Command item off

Return type:

None

oh_post_update(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

on()

Command item on

Return type:

None

percent(value)

Command to value (in percent)

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value (float | None) – 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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

DatetimeItem

class DatetimeItem()

DateTimeItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (datetime) – Current item value (or state in openHAB wording)

• last_value (datetime) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

oh_post_update(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value (Any) – 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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

RollershutterItem

class RollershutterItem()

RollershutterItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (int | float) – Current item value (or state in openHAB wording)

• last_value (int | float) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

down()

Command down

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

oh_post_update(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

percent(value)

Command to value (in percent)

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value – new value of the item

Return type:

bool

Returns:

True if state has changed

up()

Command up

Return type:

None

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

ColorItem

class ColorItem()

ColorItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (HSB) – Current item value (or state in openHAB wording)

• last_value (HSB) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – return only items which are older than this

get_rgb()

Return a rgb equivalent of the color

Return type:

RGB

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 (EventFilterBase | None) – 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:

EventBusListener

off()

Command item off

Return type:

None

oh_post_update(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

on()

Command item on

Return type:

None

percent(value)

Command to value (in percent)

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new color value without creating events on the event bus

Parameters:

new_value (RGB | HSB | tuple[float, float, float]) – 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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property brightness: float

Brightness part of the value

property hsb: HSB

HSB value

property hue: float

Hue part of the value

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

property saturation: float

Saturation part of the value

StringItem

class StringItem()

StringItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (str) – Current item value (or state in openHAB wording)

• last_value (str) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

oh_post_update(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value (Any) – 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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

LocationItem

class LocationItem()

LocationItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (Point) – Current item value (or state in openHAB wording)

• last_value (Point) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

oh_post_update(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value – new value of the item

Return type:

bool

Returns:

True if state has changed

watch_change(secs)

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

Parameters:

secs (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

PlayerItem

class PlayerItem()

PlayerItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (str) – Current item value (or state in openHAB wording)

• last_value (str) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

oh_post_update(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value (Any) – 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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

GroupItem

class GroupItem()

GroupItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (Any) – Current item value (or state in openHAB wording)

• last_value (Any) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

oh_post_update(value=<Missing>, source=None)

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.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value (Any) – 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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

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

property name: str

Returns:

Name of the item (read only)

ImageItem

class ImageItem()

ImageItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (RawType) – Current item value (or state in openHAB wording)

• last_value (RawType) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

oh_post_update(value=<Missing>, *, image_type=None, source=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:

• value (bytes | None) – image data

• image_type (str | None) – (optional) what kind of image, jpeg or png

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, image_type=None, source=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:

• value (bytes | None) – image data

• image_type (str | None) – (optional) what kind of image, jpeg or png

• source (str | None) – (optional) source where this command comes from

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value (RawType | tuple[str, bytes] | None) – 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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property image_bytes: bytes

Image bytes

property image_type: str

Image type (e.g. jpg or png)

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

CallItem

class CallItem()

CallItem which accepts and converts the data types from OpenHAB

Variables:

• name (str) – Item name

• value (StringList) – Current item value (or state in openHAB wording)

• last_value (StringList) – Last item value (or state in openHAB wording) before the current value one

• label (str | None) – Item label or None if not configured

• tags (frozenset[str]) – Item tags

• groups (frozenset[str]) – The groups the item is in

• metadata (Mapping[str, MetaData]) – Item 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

Return type:

Self

command_value(value)

Send a command to the openHAB item, the same as oh_send_command

Parameters:

value (Any) – value to be sent

Return type:

None

get_persistence_data(persistence=None, start_time=None, end_time=None)

Query historical data from the OpenHAB persistence service

Parameters:

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – 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 (EventFilterBase | None) – 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:

EventBusListener

oh_post_update(value=<Missing>, *, source=None)

Post an update to the openHAB item

Parameters:

• value (tuple[str, ...] | list[str] | StringList | _MissingType | None) – (optional) value to be posted. If not specified the current item value will be used.

• source (str | None) – (optional) source where this update comes from

Return type:

None

oh_post_update_if(new_value, *, equal=<Missing>, eq=<Missing>, not_equal=<Missing>, ne=<Missing>, lower_than=<Missing>, lt=<Missing>, lower_equal=<Missing>, le=<Missing>, greater_than=<Missing>, gt=<Missing>, greater_equal=<Missing>, ge=<Missing>, is_=<Missing>, is_not=<Missing>, source=None)

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

• source (str | None) – (optional) source where this update comes from

Return type:

bool

Returns:

True if the new value was posted else False

oh_send_command(value=<Missing>, *, source=None)

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.

• source (str | None) – (optional) source where this command comes from

Return type:

None

post_value(new_value)

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

Parameters:

new_value (Any) – new value of the item

Return type:

bool

Returns:

True if state has changed

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

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

Parameters:

• new_value – new value to post

• equal – item state has to be equal to the passed value

• eq – item state has to be equal to the passed value

• not_equal – item state has to be not equal to the passed value

• ne – item state has to be not equal to the passed value

• lower_than – item state has to be lower than the passed value

• lt – item state has to be lower than the passed value

• lower_equal – item state has to be lower equal the passed value

• le – item state has to be lower equal the passed value

• greater_than – item state has to be greater than the passed value

• gt – item state has to be greater than the passed value

• greater_equal – item state has to be greater equal the passed value

• ge – item state has to be greater equal the passed value

• is_ – item state has to be the same object as the passt value (e.g. None)

• is_not – item state has to be not the same object as the passt value (e.g. None)

Return type:

bool

Returns:

True if the new value was posted else False

set_value(new_value)

Set a new value without creating events on the event bus

Parameters:

new_value (tuple[str, ...] | list[str] | StringList | None) – 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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: str

Returns:

Name of the item (read only)

Thing

class Thing(name, *, interface)

Base class for Things

Variables:

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

• status_detail (ThingStatusDetailEnum) – Additional detail for the status

• status_description (str) – Additional description for the status

• label (str) – Thing label

• location (str) – Thing location

• 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

Return type:

Self

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 (EventFilterBase | None) – 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:

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

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 (timedelta | TimeDelta | int | float | str) – secs after which the event will occur

Return type:

ItemTimeWatch

Returns:

The watch obj which can be used to cancel the watch

property last_change: InstantView

Returns:

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

property last_update: InstantView

Returns:

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

property name: 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.

Interface

class OpenHabSyncInterface()

post_update(item, state, *, source=None, transport='websocket')

Post an update to the item

Parameters:

• item (str | ItemRegistryItem) – item name or item

• state (Any) – new item state

• source (str | None) – (optional) source of the update

• transport (Literal['http', 'websocket']) – transport to use. Websocket is much faster but stricter concerning which types are accepted

Return type:

None

send_command(item, command, *, source=None, transport='websocket')

Send the specified command to the item

Parameters:

• item (str | ItemRegistryItem) – item name or item

• command (Any) – command

• source (str | None) – (optional) source of the command

• transport (Literal['http', 'websocket']) – transport to use. Websocket is much faster but stricter concerning which types are accepted

Return type:

None

get_item(item)

Return the complete openHAB item definition

Parameters:

item (str | ItemRegistryItem) – name of the item or item

Return type:

ItemResp | None

Returns:

openHAB item

item_exists(item)

Check if an item exists in the openHAB item registry

Parameters:

item (str | ItemRegistryItem) – name of the item or item

Return type:

bool

Returns:

True if item was found

remove_item(item)

Removes an item from the openHAB item registry

Parameters:

item (str | ItemRegistryItem) – name

Return type:

bool | None

Returns:

True if item was found and removed

create_item(item_type, name, label=None, category=None, tags=None, groups=None, group_type=None, group_function=None, group_function_params=None)

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 (str | None) – item label

• category (str | None) – item category

• tags (list[str] | None) – item tags

• groups (list[str] | None) – in which groups is the item

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

• group_function (str | None) – group state aggregation function

• group_function_params (list[str] | None) – params for group state aggregation

Return type:

bool

Returns:

True if item was created/updated

remove_metadata(item, namespace)

Remove metadata from an item

Parameters:

• item (str | ItemRegistryItem) – name of the item or item

• namespace (str) – namespace

Return type:

bool

Returns:

True if metadata was successfully removed

set_metadata(item, namespace, value, config)

Add/set metadata to an item

Parameters:

• item (str | ItemRegistryItem) – name of the item or item

• namespace (str) – namespace, e.g. stateDescription

• value (str) – value

• config (dict) – configuration e.g. {"options": "A,B,C"}

Return type:

bool

Returns:

True if metadata was successfully created/updated

get_thing(thing)

Return the complete openHAB thing definition

Parameters:

thing (str | ItemRegistryItem) – name of the thing or the item

Return type:

ThingResp

Returns:

openHAB thing

set_thing_enabled(thing, enabled)

Enable/disable a thing

Parameters:

• thing (str | ItemRegistryItem) – name of the thing or the thing object

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

Return type:

int | None

remove_obj_links(name)

Remove links from an item or a thing

Parameters:

name (str | ItemRegistryItem) – name of thing or item

Return type:

bool

get_link(item, channel)

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

Parameters:

• item (str | ItemRegistryItem) – name of the item or item

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

Return type:

ItemChannelLinkResp

create_link(item, channel, configuration=None)

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

Parameters:

• item (str | ItemRegistryItem) – name of the item or item

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

• configuration (dict[str, Any] | None) – optional configuration for the channel

Return type:

bool

Returns:

True on successful creation, otherwise False

remove_link(item, channel)

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

Parameters:

• item (str | ItemRegistryItem) – name of the item or item

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

Return type:

None

Returns:

True on successful removal, otherwise False

get_persistence_services()

Return all available persistence services

Return type:

tuple[PersistenceServiceResp, ...]

get_persistence_data(item, persistence, start_time, end_time)

Query historical data from the openHAB persistence service

Parameters:

• item (str | ItemRegistryItem) – name of the persistent item

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

• start_time (datetime | None) – return only items which are newer than this

• end_time (datetime | None) – return only items which are older than this

Return type:

OpenhabPersistenceData

Returns:

last stored data from persistency service

set_persistence_data(item, persistence, time, state)

Set a measurement for a item in the persistence serivce

Parameters:

• item_name – name of the persistent item

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

• time (datetime) – time of measurement

• state (Any) – state which will be set

Returns:

True if data was stored in persistency service

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.

class ItemStateEvent(name, value)

ItemStateChangedEvent

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

class ItemStateChangedEvent(name, value, old_value, *, last_state_update, last_state_change, source=None)

Variables:

• last_state_update (Instant | None) – Optional timestamp of the state update

• last_state_change (Instant | None) – Optional timestamp of the state change

• source (str | None) – Optional source of the update

ItemCommandEvent

class ItemCommandEvent(name, value, *, source=None)

Variables:

source (str | None) – Optional source of the update

ItemAddedEvent

class ItemAddedEvent(name, type, label, tags, group_names)

Variables:

• name (str)

• type (str)

• label (str | None)

• tags (frozenset[str])

• groups (frozenset[str])

ItemUpdatedEvent

class ItemUpdatedEvent(name, type, label, tags, group_names)

Variables:

• name (str)

• type (str)

• label (str | None)

• tags (frozenset[str])

• groups (frozenset[str])

ItemRemovedEvent

class ItemRemovedEvent(name, type, label, tags, groups)

Variables:

• name (str)

• type (str)

• label (str | None)

• tags (frozenset[str])

• groups (frozenset[str])

ItemStatePredictedEvent

class ItemStatePredictedEvent(name, value, is_confirmation)

Variables:

• name (str)

• value (Any)

• is_confirmation (bool)

GroupStateChangedEvent

class GroupStateChangedEvent(name, item, value, old_value)

Variables:

• name (str)

• item (str)

• value (Any)

• old_value (Any)

Channel events

ChannelTriggeredEvent

class ChannelTriggeredEvent(name='', event='', channel='')

Variables:

• name (str)

• event (str)

• channel (str)

Thing events

ThingAddedEvent

class ThingAddedEvent(name, thing_type, label, location, channels, configuration, properties)

ThingUpdatedEvent

class ThingUpdatedEvent(name, thing_type, label, location, channels, configuration, properties)

ThingRemovedEvent

class ThingRemovedEvent(name, thing_type, label, location, channels, configuration, properties)

ThingStatusInfoEvent

class ThingStatusInfoEvent(name='', status=ThingStatusEnum.UNINITIALIZED, detail=ThingStatusDetailEnum.NONE, description='')

Variables:

• name (str)

• status (ThingStatusEnum)

• detail (ThingStatusDetailEnum)

• description (str)

ThingStatusInfoChangedEvent

class ThingStatusInfoChangedEvent(name='', status=ThingStatusEnum.UNINITIALIZED, detail=ThingStatusDetailEnum.NONE, description='', old_status=ThingStatusEnum.UNINITIALIZED, old_detail=ThingStatusDetailEnum.NONE, old_description='')

Variables:

• name (str)

• status (ThingStatusEnum)

• detail (ThingStatusDetailEnum)

• description (str)

• old_status (ThingStatusEnum)

• old_detail (ThingStatusDetailEnum)

• old_description (str)

ThingFirmwareStatusInfoEvent

class ThingFirmwareStatusInfoEvent(name='', status='')

Variables:

• name (str)

• status (str)

Event filters

ItemStateUpdatedEventFilter

class ItemStateUpdatedEventFilter(value=<Missing>)

ItemStateChangedEventFilter

class ItemStateChangedEventFilter(value=<Missing>, old_value=<Missing>)

ItemCommandEventFilter

class ItemCommandEventFilter(value=<Missing>)

Transformations

From openHAB 4 on it’s possible to use the existing transformations in HABApp. Transformations are loaded every time when HABApp connects to openHAB. OpenHAB does not issue an event when the transformations change so in order for HABApp to pick up the changes either HABApp or openHAB has to be restarted. Available transformations are logged on connect.

map

The map transformation is returned as a dict. If the map transformation is defined with a default the default is used accordingly.

Example:

from HABApp.openhab import transformations

TEST_MAP = transformations.map['test.map']  # load the transformation, can be used anywhere
print(TEST_MAP['test_key'])                 # It's a normal dict with keys as str and values as str

# if all keys or values are numbers they are automatically casted to an int
NUMBERS = transformations.map['numbers.map']
print(NUMBERS[1])   # Note that the key is an int

test_value
test number meaning

Example openHAB rules

Example 1

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


class MyOpenhabRule(HABApp.Rule):

    def __init__(self) -> None:
        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) -> None:
        assert isinstance(event, ValueUpdateEvent)
        print(f'{event}')

    def item_state_change(self, event) -> None:
        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) -> None:
        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.core.events import EventFilter
from HABApp.openhab.events import ThingStatusInfoChangedEvent
from HABApp.openhab.items import Thing


class CheckAllThings(Rule):
    def __init__(self) -> None:
        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) -> None:
        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
/home/docs/.asdf/installs/python/3.13.14/lib/python3.13/asyncio/base_events.py:569: ResourceWarning: asynchronous generator <async_generator object HabAppObjProvider._reentrant_lock at 0x73da6c43e890> was scheduled after loop.shutdown_asyncgens() call