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

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

class HABApp.openhab.oh_interface.OpenhabItemDefinition(type, name, state, label='', category='', editable=True, tags=<factory>, groups=<factory>, members=<factory>)
Variables
  • type (str) – item type

  • name (str) – item name

  • state (str) – item state

  • state – item label

  • category (str) – item category

  • editable (bool) – item can changed through Rest API

  • tags (typing.List[str]) – item tags

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

  • members (typing.List[OpenhabItemDefinition]) – If the item is a group this contains the members

Openhab item types

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!

Openhab type

HABApp class

Contact

ContactItem

Switch

SwitchItem

Dimmer

DimmerItem

Rollershutter

RollershutterItem

Color

ColorItem

class HABApp.openhab.items.ContactItem(name, initial_value=None)
classmethod get_create_item(name, initial_value=None)

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

Parameters
  • name (str) – item name

  • initial_value – state the item will have if it gets created

Returns

item

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

Returns

the item

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

is_closed()

Test value against closed-value

Return type

bool

is_open()

Test value against open-value

Return type

bool

post_value(new_value)

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

Parameters

new_value – new value of the item

class HABApp.openhab.items.SwitchItem(name, initial_value=None)
classmethod get_create_item(name, initial_value=None)

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

Parameters
  • name (str) – item name

  • initial_value – state the item will have if it gets created

Returns

item

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

Returns

the item

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

is_off()

Test value against off-value

Return type

bool

is_on()

Test value against on-value

Return type

bool

off()

Command item off

on()

Command item on

post_value(new_value)

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

Parameters

new_value – new value of the item

class HABApp.openhab.items.DimmerItem(name, initial_value=None)
classmethod get_create_item(name, initial_value=None)

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

Parameters
  • name (str) – item name

  • initial_value – state the item will have if it gets created

Returns

item

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

Returns

the item

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

is_off()

Test value against off-value

Return type

bool

is_on()

Test value against on-value

Return type

bool

off()

Command item off

on()

Command item on

percent(value)

Command to value (in percent)

post_value(new_value)

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

Parameters

new_value – new value of the item

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

Command down

classmethod get_create_item(name, initial_value=None)

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

Parameters
  • name (str) – item name

  • initial_value – state the item will have if it gets created

Returns

item

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

Returns

the item

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

percent(value)

Command to value (in percent)

post_value(new_value)

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

Parameters

new_value – new value of the item

up()

Command up

class HABApp.openhab.items.ColorItem(name, h=0.0, s=0.0, b=0.0)
classmethod get_create_item(name, initial_value=None)

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

Parameters
  • name (str) – item name

  • initial_value – state the item will have if it gets created

Returns

item

classmethod get_item(name)

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

Parameters

name (str) – Name of the item

Returns

the item

get_rgb(max_rgb_value=255)

Return a rgb equivalent of the color

Parameters

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

Return type

Tuple[int, int, int]

Returns

rgb tuple

get_value(default_value=None)

Return the value of the item.

Parameters

default_value – Return this value if the item value is None

Return type

Any

Returns

value of the item

is_off()

Return true if item is off

Return type

bool

is_on()

Return true if item is on

Return type

bool

off()

Command item off

on()

Command item on

percent(value)

Command to value (in percent)

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

Set a new value and post appropriate events on the 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 %)

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