openHAB

Interaction with a openHAB

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

_images/openhab.gif

Function parameters

class HABApp.openhab.oh_interface.OpenhabInterface(connection)
post_update(item_name, state)

Post an update to the item

Parameters
  • item_name (str) – item name or item

  • state – new item state

send_command(item_name, command)

Send the specified command to the item

Parameters
  • item_name (str) – item name or item

  • command – command

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

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

Parameters
  • item_type (str) – item type

  • name (str) – item name

  • label – item label

  • category – item category

  • tags (List[str]) – item tags

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

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

  • group_function (str) – group state aggregation function

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

Returns

True if item was created/updated

get_item(item_name)

Return the complete OpenHAB item definition

Parameters

item_name (str) – name of the item or item

Return type

OpenhabItemDefinition

get_thing(thing_name)

Return the complete OpenHAB thing definition

Parameters

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

Return type

OpenhabThingDefinition

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

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

  • item_name (str) – name of the item

Return type

ItemChannelLinkDefinition

Returns

an instance of ItemChannelLinkDefinition or None on error

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

Parameters

link_def – an instance of ItemChannelLinkDefinition with at least channel_uid and item_name set

Return type

bool

Returns

true on successful creation, otherwise false

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

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

  • item_name (str) – name of the item

Return type

bool

Returns

true on successful removal, otherwise false

check if a things channel is linked to an item

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

  • item_name (str) – name of the linked item

Return type

bool

Returns

true when the link exists, otherwise false

remove_item(item_name)

Removes an item from the openHAB item registry

Parameters

item_name (str) – name

item_exists(item_name)

Check if an item exists in the OpenHAB item registry

Parameters

item_name (str) – name

set_metadata(item_name, namespace, value, config)

Add/set metadata to an item

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

  • namespace (str) – namespace

  • value (str) – value

  • config (dict) – configuration

Returns

remove_metadata(item_name, namespace)

Remove metadata from an item

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

  • namespace (str) – namespace

Returns

get_persistence_data(item_name, persistence, start_time, end_time)

Query historical data from the OpenHAB persistence service

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

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

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

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

Return type

OpenhabPersistenceData

class HABApp.openhab.oh_interface.OpenhabItemDefinition(**data)

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Openhab item types

Description and example

Openhab items are mapped to special classes and provide convenience functions.

Example:

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

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

NumberItem

Inheritance diagram of HABApp.openhab.items.NumberItem
class HABApp.openhab.items.NumberItem(name, initial_value=None)

NumberItem which accepts and converts the data types from OpenHAB

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

listen_event(callback, event_type)

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

oh_post_update(value=<Missing>)

Post an update to the openHAB item

Parameters

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

oh_send_command(value=<Missing>)

Send a command to the openHAB item

Parameters

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

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

ContactItem

Inheritance diagram of HABApp.openhab.items.ContactItem
class HABApp.openhab.items.ContactItem(name, initial_value=None)
classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_value(default_value=None)

Return the value of the item.

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

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

oh_post_update(value=<Missing>)

Post an update to the openHAB item

Parameters

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

oh_send_command(value=<Missing>)

Send a command to the openHAB item

Parameters

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

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

SwitchItem

Inheritance diagram of HABApp.openhab.items.SwitchItem
class HABApp.openhab.items.SwitchItem(name, initial_value=None)
classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_value(default_value=None)

Return the value of the item.

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

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

off()

Command item off

oh_post_update(value=<Missing>)

Post an update to the openHAB item

Parameters

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

oh_send_command(value=<Missing>)

Send a command to the openHAB item

Parameters

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

on()

Command item on

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

DimmerItem

Inheritance diagram of HABApp.openhab.items.DimmerItem
class HABApp.openhab.items.DimmerItem(name, initial_value=None)
classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_value(default_value=None)

Return the value of the item.

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

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

off()

Command item off

oh_post_update(value=<Missing>)

Post an update to the openHAB item

Parameters

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

oh_send_command(value=<Missing>)

Send a command to the openHAB item

Parameters

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

on()

Command item on

percent(value)

Command to value (in percent)

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

RollershutterItem

Inheritance diagram of HABApp.openhab.items.RollershutterItem
class HABApp.openhab.items.RollershutterItem(name, initial_value=None)
down()

Command down

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_value(default_value=None)

Return the value of the item.

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

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

oh_post_update(value=<Missing>)

Post an update to the openHAB item

Parameters

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

oh_send_command(value=<Missing>)

Send a command to the openHAB item

Parameters

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

percent(value)

Command to value (in percent)

up()

Command up

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

ColorItem

Inheritance diagram of HABApp.openhab.items.ColorItem
class HABApp.openhab.items.ColorItem(name, h=0.0, s=0.0, b=0.0)
classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_rgb(max_rgb_value=255)

Return a rgb equivalent of the color

Parameters

max_rgb_value – the max value for rgb, typically 255 (default) or 65.536

Return type

Tuple[int, int, int]

Returns

rgb tuple

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

is_off()

Return true if item is off

Return type

bool

is_on()

Return true if item is on

Return type

bool

listen_event(callback, event_type)

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

off()

Command item off

oh_post_update(value=<Missing>)

Post an update to the openHAB item

Parameters

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

oh_send_command(value=<Missing>)

Send a command to the openHAB item

Parameters

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

on()

Command item on

percent(value)

Command to value (in percent)

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

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

Parameters
  • r – red value

  • g – green value

  • b – blue value

  • max_rgb_value – the max value for rgb, typically 255 (default) or 65.536

Return type

ColorItem

Returns

self

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

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

Parameters
  • hue – hue (in °)

  • saturation – saturation (in %)

  • brightness – brightness (in %)

set_rgb(r, g, b, max_rgb_value=255)

Set a rgb value

Parameters
  • r – red value

  • g – green value

  • b – blue value

  • max_rgb_value – the max value for rgb, typically 255 (default) or 65.536

Return type

ColorItem

Returns

self

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

Set the color value

Parameters
  • hue – hue (in °)

  • saturation – saturation (in %)

  • brightness – brightness (in %)

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

StringItem

Inheritance diagram of HABApp.openhab.items.StringItem
class HABApp.openhab.items.StringItem(name, initial_value=None)

StringItem which accepts and converts the data types from OpenHAB

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

listen_event(callback, event_type)

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

oh_post_update(value=<Missing>)

Post an update to the openHAB item

Parameters

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

oh_send_command(value=<Missing>)

Send a command to the openHAB item

Parameters

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

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

LocationItem

Inheritance diagram of HABApp.openhab.items.LocationItem
class HABApp.openhab.items.LocationItem(name, initial_value=None)

LocationItem which accepts and converts the data types from OpenHAB

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

listen_event(callback, event_type)

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

oh_post_update(value=<Missing>)

Post an update to the openHAB item

Parameters

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

oh_send_command(value=<Missing>)

Send a command to the openHAB item

Parameters

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

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

PlayerItem

Inheritance diagram of HABApp.openhab.items.PlayerItem
class HABApp.openhab.items.PlayerItem(name, initial_value=None)

PlayerItem which accepts and converts the data types from OpenHAB

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

listen_event(callback, event_type)

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

oh_post_update(value=<Missing>)

Post an update to the openHAB item

Parameters

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

oh_send_command(value=<Missing>)

Send a command to the openHAB item

Parameters

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

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

GroupItem

Inheritance diagram of HABApp.openhab.items.GroupItem
class HABApp.openhab.items.GroupItem(name, initial_value=None)

GroupItem which accepts and converts the data types from OpenHAB

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

listen_event(callback, event_type)

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

oh_post_update(value=<Missing>)

Post an update to the openHAB item

Parameters

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

oh_send_command(value=<Missing>)

Send a command to the openHAB item

Parameters

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

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

Thing

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

Base class for Things

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

listen_event(callback, event_type)

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

ImageItem

Inheritance diagram of HABApp.openhab.items.ImageItem
class HABApp.openhab.items.ImageItem(name, initial_value=None)

ImageItem which accepts and converts the data types from OpenHAB

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

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

Query historical data from the OpenHAB persistence service

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

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

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

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

listen_event(callback, event_type)

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

Parameters
  • callback (Callable[[Any], Any]) – callback that accepts one parameter which will contain the event

  • event_type (Union[AllEvents, Any]) – Event filter. This is typically ValueUpdateEvent or ValueChangeEvent which will also trigger on changes/update from openHAB or mqtt.

Return type

EventBusListener

oh_post_update(data, img_type=None)

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

Parameters
  • data (bytes) – image data

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

oh_send_command(data, img_type=None)

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

Parameters
  • data (bytes) – image data

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

watch_change(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

watch_update(secs)

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

Parameters

secs (Union[int, float]) – secs after which the event will occur, max 1 decimal digit for floats

Return type

BaseWatch

Returns

The watch obj which can be used to cancel the watch

property last_change
Return type

datetime

Returns

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

property last_update
Return type

datetime

Returns

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

property name
Return type

str

Returns

Name of the item (read only)

Textual thing configuration

Description

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

Warning

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

Configuration is typically done in the ThingConfig.yml file in the config folder (see Configuration), but can also be spread out to more files like ThingConfig_MyThing.yml. Every file that starts with ThingConfig has the .yml ending will be loaded.

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

File Structure

The configuration is a simple entry with the thing UID and the configuration parameters together with the target value.

ThingUID1:
    Parameter1:  Value1
    Parameter2:  Value2

ThingUID2:
    Parameter1:  Value3

Examples

Simple entry

The following example will show how to set the Z-Wave Parameters 4, 5 and 7 for a Philio PST02A Z-Wave sensor.

# Philio PST02A
zwave:device:controller:node5:
  4: 99     # Light Threshold
  5: 8      # Operation Mode
  7: 20     # Customer Function

Tip

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

Entry sharing

If the values should be checked for multiple sensors yml features anchors with & which then can be referenced with *. This allows to apply the defined parameters quickly to more sensors.

# Philio PST02A
zwave:device:controller:node3:  &PST02A  # <-- this creates the anchor node with the name PST02A
  4: 99     # Light Threshold
  5: 8      # Operation Mode
  7: 20     # Customer Function

zwave:device:controller:node5: *PST02A  # <-- this references the anchor node PST02A
zwave:device:controller:node6: *PST02A
zwave:device:controller:node7:
  <<: *PST02A   # <-- this references and inserts the content (!) of the anchor node
  4: 80         #     and then overwrites parameter 4

Log output

[HABApp.openhab.Config]     INFO | Checking zwave:device:controller:node3: PhilioPST02A (Node 03)
[HABApp.openhab.Config]     INFO |  - 4 is already 99
[HABApp.openhab.Config]     INFO |  - 5 is already 8
[HABApp.openhab.Config]     INFO |  - 7 is already 20
[HABApp.openhab.Config]     INFO | Checking zwave:device:controller:node5: PhilioPST02A (Node 05)
[HABApp.openhab.Config]     INFO |  - 4 is already 99
[HABApp.openhab.Config]     INFO |  - 5 is already 8
[HABApp.openhab.Config]     INFO |  - 7 is already 20
[HABApp.openhab.Config]     INFO | Checking zwave:device:controller:node6: PhilioPST02A (Node 06)
[HABApp.openhab.Config]     INFO |  - 4 is already 99
[HABApp.openhab.Config]     INFO |  - 5 is already 8
[HABApp.openhab.Config]     INFO |  - 7 is already 20
[HABApp.openhab.Config]     INFO | Checking zwave:device:controller:node7: PhilioPST02A (Node 07)
[HABApp.openhab.Config]     INFO |  - 4 is already 80
[HABApp.openhab.Config]     INFO |  - 5 is already 8
[HABApp.openhab.Config]     INFO |  - 7 is already 20

Parameter overview

It is possible to quickly generate a parameter overview (with current values) simply by specifying an invalid parameter name.

zwave:device:controller:node3:
  asdf: asdf

Log output

[HABApp.openhab.Config]     INFO | Checking zwave:device:controller:node3: PhilioPST02A (Node 03)
[HABApp.openhab.Config]    ERROR |  - Config value "asdf" does not exist!
[HABApp.openhab.Config]    ERROR |    Available:
[HABApp.openhab.Config]    ERROR |     - Group1: ['controller']
[HABApp.openhab.Config]    ERROR |     - Group2: []
[HABApp.openhab.Config]    ERROR |     - binding_cmdrepollperiod: 1500
[HABApp.openhab.Config]    ERROR |     - binding_pollperiod: 86400
[HABApp.openhab.Config]    ERROR |     - wakeup_interval: 86400
[HABApp.openhab.Config]    ERROR |     -   2: -1
[HABApp.openhab.Config]    ERROR |     -   3: 80
[HABApp.openhab.Config]    ERROR |     -   4: 99
[HABApp.openhab.Config]    ERROR |     -   5: 8
[HABApp.openhab.Config]    ERROR |     -   6: 0
[HABApp.openhab.Config]    ERROR |     -   7: 20
[HABApp.openhab.Config]    ERROR |     -   8: 3
[HABApp.openhab.Config]    ERROR |     -   9: 4
[HABApp.openhab.Config]    ERROR |     -  10: 12
[HABApp.openhab.Config]    ERROR |     -  11: 12
[HABApp.openhab.Config]    ERROR |     -  12: 12
[HABApp.openhab.Config]    ERROR |     -  13: 12
[HABApp.openhab.Config]    ERROR |     -  20: 30
[HABApp.openhab.Config]    ERROR |     -  21: 0
[HABApp.openhab.Config]    ERROR |     -  22: 0

Example openHAB rule

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

class MyOpenhabRule(HABApp.Rule):

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

        # Trigger on item updates
        self.listen_event('TestContact', self.item_state_update, ItemStateEvent)
        self.listen_event('TestDateTime', self.item_state_update, ValueUpdateEvent)

        # Trigger on item changes
        self.listen_event('TestDateTime', self.item_state_change, ItemStateChangedEvent)
        self.listen_event('TestSwitch', self.item_state_change, ValueChangeEvent)

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

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

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

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

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

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

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


MyOpenhabRule()