openHAB¶
Additional configuration¶
openHAB 2¶
For openHAB2 there is no additional configuration needed.
openHAB 3¶
For optimal performance it is recommended to use Basic Auth (available from openHAB 3.1 M3 on). It can be enabled through GUI or through textual configuration.
Textual configuration¶
The settings are in the runtime.cfg
.
Remove the #
before the entry to activate it.
################ REST API ###################
org.openhab.restauth:allowBasicAuth=true
GUI¶
It can be enabled through the gui in settings
-> API Security
-> Allow Basic Authentication
.
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
.
Function parameters¶
-
HABApp.openhab.interface.
post_update
(item_name, state)¶ Post an update to the item
- Parameters
item_name (
str
) – item name or itemstate (
Any
) – new item state
-
HABApp.openhab.interface.
send_command
(item_name, command)¶ Send the specified command to the item
- Parameters
item_name (
str
) – item name or itemcommand – command
-
HABApp.openhab.interface.
get_item
(item_name, metadata=None)¶ Return the complete OpenHAB item definition
- Parameters
item_name (
str
) – name of the item or itemmetadata (
Optional
[str
]) – metadata to include (optional, comma separated or search expression)
- Return type
OpenhabItemDefinition
- Returns
-
HABApp.openhab.interface.
item_exists
(item_name)¶ Check if an item exists in the OpenHAB item registry
- Parameters
item_name (
str
) – name
-
HABApp.openhab.interface.
remove_item
(item_name)¶ Removes an item from the openHAB item registry
- Parameters
item_name (
str
) – name
-
HABApp.openhab.interface.
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 typename (
str
) – item namelabel – item label
category – item category
tags (
List
[str
]) – item tagsgroups (
List
[str
]) – in which groups is the itemgroup_type (
str
) – what kind of group is itgroup_function (
str
) – group state aggregation functiongroup_function_params (
List
[str
]) – params for group state aggregation
- Returns
True if item was created/updated
-
HABApp.openhab.interface.
get_thing
(thing_name)¶ Return the complete OpenHAB thing definition
- Parameters
thing_name (
str
) – name of the thing or the item- Return type
OpenhabThingDefinition
-
HABApp.openhab.interface.
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 itempersistence (
Optional
[str
]) – name of the persistence service (e.g.rrd4j
,mapdb
). If not set default will be usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_time (
Optional
[datetime
]) – return only items which are older than this
- Return type
OpenhabPersistenceData
-
HABApp.openhab.interface.
remove_metadata
(item_name, namespace)¶ Remove metadata from an item
- Parameters
item_name (
str
) – name of the item or itemnamespace (
str
) – namespace
- Returns
-
HABApp.openhab.interface.
set_metadata
(item_name, namespace, value, config)¶ Add/set metadata to an item
- Parameters
item_name (
str
) – name of the item or itemnamespace (
str
) – namespacevalue (
str
) – valueconfig (
dict
) – configuration
- Returns
-
HABApp.openhab.interface.
get_channel_link
(channel_uid, item_name)¶ 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
-
HABApp.openhab.interface.
remove_channel_link
(channel_uid, item_name)¶ removes a link between a (things) channel and an item
- Parameters
channel_uid (
str
) – uid of the (thing) channel (usually something like AAAA:BBBBB:CCCCC:DDDD:0#SOME_NAME)item_name (
str
) – name of the item
- Return type
bool
- Returns
true on successful removal, otherwise false
-
HABApp.openhab.interface.
channel_link_exists
(channel_uid, item_name)¶ 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
-
HABApp.openhab.interface.
create_channel_link
(channel_uid, item_name, configuration=None)¶ creates a link between a (things) channel and an item
- Parameters
channel_uid (
str
) – uid of the (thing) channel (usually something like AAAA:BBBBB:CCCCC:DDDD:0#SOME_NAME)item_name (
str
) – name of the itemconfiguration (
Optional
[Dict
[str
,Any
]]) – optional configuration for the channel
- Return type
bool
- Returns
true on successful creation, otherwise false
Openhab item types¶
Description and example¶
Items that are created from openHAB inherit all from OpenhabItem
and
provide convenience functions which simplify many things.
Example:
from HABApp.openhab.items import ContactItem, SwitchItem
my_contact = ContactItem.get_item('MyContact')
if my_contact.is_open():
print('Contact is open!')
my_switch = SwitchItem.get_item('MySwitch')
if my_switch.is_on():
my_switch.off()
Contact is open!
NumberItem¶
-
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
oh_post_update
(value=<_MissingType.MISSING: <object object>>)¶ 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=<_MissingType.MISSING: <object object>>)¶ Send a command to the openHAB item
- Parameters
value (
Any
) – (optional) value to be sent. If not specified the item value will be used.
-
post_value
(new_value)¶ Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
set_value
(new_value)¶ Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
-
classmethod
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
oh_post_update
(value=<_MissingType.MISSING: <object object>>)¶ 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=<_MissingType.MISSING: <object object>>)¶ Send a command to the openHAB item
- Parameters
value (
Any
) – (optional) value to be sent. If not specified the item value will be used.
-
post_value
(new_value)¶ Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
set_value
(new_value)¶ Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
-
classmethod
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
off
()¶ Command item off
-
oh_post_update
(value=<_MissingType.MISSING: <object object>>)¶ 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=<_MissingType.MISSING: <object object>>)¶ 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
-
post_value
(new_value)¶ Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
set_value
(new_value)¶ Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
-
classmethod
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
off
()¶ Command item off
-
oh_post_update
(value=<_MissingType.MISSING: <object object>>)¶ 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=<_MissingType.MISSING: <object object>>)¶ 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_value
(new_value)¶ Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
set_value
(new_value)¶ Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
-
classmethod
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
oh_post_update
(value=<_MissingType.MISSING: <object object>>)¶ 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=<_MissingType.MISSING: <object object>>)¶ 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)
-
post_value
(new_value)¶ Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
set_value
(new_value)¶ Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
up
()¶ Command up
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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¶
-
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
off
()¶ Command item off
-
oh_post_update
(value=<_MissingType.MISSING: <object object>>)¶ 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=<_MissingType.MISSING: <object object>>)¶ 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, ndigits=2)¶ Set a rgb value
- Parameters
r – red value
g – green value
b – blue value
max_rgb_value – the max value for rgb, typically 255 (default) or 65.536
ndigits (
Optional
[int
]) – Round the hsb values to the specified digits, None to disable rounding
- Return type
ColorItem
- Returns
self
-
set_value
(hue=0.0, saturation=0.0, brightness=0.0)¶ Set the color value
- Parameters
hue – hue (in °)
saturation – saturation (in %)
brightness – brightness (in %)
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
-
classmethod
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
oh_post_update
(value=<_MissingType.MISSING: <object object>>)¶ 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=<_MissingType.MISSING: <object object>>)¶ Send a command to the openHAB item
- Parameters
value (
Any
) – (optional) value to be sent. If not specified the item value will be used.
-
post_value
(new_value)¶ Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
set_value
(new_value)¶ Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
-
classmethod
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
oh_post_update
(value=<_MissingType.MISSING: <object object>>)¶ 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=<_MissingType.MISSING: <object object>>)¶ Send a command to the openHAB item
- Parameters
value (
Any
) – (optional) value to be sent. If not specified the item value will be used.
-
post_value
(new_value)¶ Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
set_value
(new_value)¶ Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
-
classmethod
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
oh_post_update
(value=<_MissingType.MISSING: <object object>>)¶ 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=<_MissingType.MISSING: <object object>>)¶ Send a command to the openHAB item
- Parameters
value (
Any
) – (optional) value to be sent. If not specified the item value will be used.
-
post_value
(new_value)¶ Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
set_value
(new_value)¶ Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
-
classmethod
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
oh_post_update
(value=<_MissingType.MISSING: <object object>>)¶ 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=<_MissingType.MISSING: <object object>>)¶ Send a command to the openHAB item
- Parameters
value (
Any
) – (optional) value to be sent. If not specified the item value will be used.
-
post_value
(new_value)¶ Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
set_value
(new_value)¶ Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
-
classmethod
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 usedstart_time (
Optional
[datetime
]) – return only items which are newer than thisend_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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
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 dataimg_type (
Optional
[str
]) – (optional) what kind of image,jpeg
orpng
-
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 dataimg_type (
Optional
[str
]) – (optional) what kind of image,jpeg
orpng
-
post_value
(new_value)¶ Set a new value and post appropriate events on the HABApp event bus (
ValueUpdateEvent
,ValueChangeEvent
)- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
set_value
(new_value)¶ Set a new value without creating events on the event bus
- Parameters
new_value – new value of the item
- Return type
bool
- Returns
True if state has changed
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
-
classmethod
Thing¶
-
class
HABApp.openhab.items.
Thing
(name)¶ Base class for Things
- Variables
status (str) – Status of the thing (e.g. OFFLINE, ONLINE, …)
-
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 eventevent_type (
Union
[AllEvents
,EventFilter
,Any
]) – Event filter. This is typicallyValueUpdateEvent
orValueChangeEvent
which will also trigger on changes/update from openHAB or mqtt.
- Return type
EventBusListener
-
watch_change
(secs)¶ Generate an event if the item does not change for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
watch_update
(secs)¶ Generate an event if the item does not receive and update for a certain period of time. Has to be called from inside a rule function.
- Parameters
secs (
Union
[int
,float
,timedelta
]) – secs after which the event will occur, max 1 decimal digit for floats- Return type
- Returns
The watch obj which can be used to cancel the watch
-
property
last_change
¶ - 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)
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
HABApp.openhab.events.
ItemStateEvent
(name='', value=None)¶ - Variables
name (str) –
value –
ItemStateChangedEvent¶
Since this event inherits from ValueChangeEvent
you can listen to ValueChangeEvent
and it will also trigger for ItemStateChangedEvent
.
-
class
HABApp.openhab.events.
ItemStateChangedEvent
(name='', value=None, old_value=None)¶ - Variables
name (str) –
value –
old_value –
ItemCommandEvent¶
-
class
HABApp.openhab.events.
ItemCommandEvent
(name='', value=None)¶ - Variables
name (str) –
value –
ItemAddedEvent¶
-
class
HABApp.openhab.events.
ItemAddedEvent
(name='', type='')¶ - Variables
name (str) –
type (str) –
ItemUpdatedEvent¶
-
class
HABApp.openhab.events.
ItemUpdatedEvent
(name='', type='')¶ - Variables
name (str) –
type (str) –
Channel events¶
Thing events¶
ThingStatusInfoChangedEvent¶
-
class
HABApp.openhab.events.
ThingStatusInfoChangedEvent
(name='', status='', detail='', old_status='', old_detail='')¶ - Variables
name (str) –
status (str) –
detail (str) –
old_status (str) –
old_detail (str) –
ThingStatusInfoEvent¶
-
class
HABApp.openhab.events.
ThingStatusInfoEvent
(name='', status='', detail='')¶ - Variables
name (str) –
status (str) –
detail (str) –
Textual thing configuration¶
Description¶
HABApp offers a special mechanism to textually define thing configuration parameters and linked items for things which have been added through the gui. This combines the best of both worlds: auto discovery, easy and fast sharing of parameters and items across things.
Configuration is done in the thing_your_name.yml
file in the config
folder (see Configuration).
Every file that starts with thing_
has the .yml
ending will be loaded.
The Parameters and items will be checked/set when HABApp connects to openHAB or whenever the corresponding file gets changed.
Principle of operation¶
All existing things from openHAB can be filtered by different criteria. For each one of these remaining things it is then possible to
Set thing parameters
Create items with values taken from the thing fields
- Apply filters to the channels of the thingFor each matching channel it is possible to create and link items with values taken from the thing and the matching channel values
There is also a test mode which prints out all required information and does not make any changes.
A valid .items
file will automatically be created next to the .yml
file containing all created items.
It can be used to get a quick overview what items (would) have been created or copied into the items folder.
File Structure¶
Configuration is done through a .yml file.
Example¶
The following example will show how to set the Z-Wave Parameters 4, 5, 6 and 8 for a Philio PST02A
Z-Wave sensor
and how to automatically link items to it.
Tip
Integer values can be specified either as integer (20
) or hex (0x14
)
The entries thing config
, create items
and channels
are optional and can be combined as desired.
# Test mode: will not do anything but instead print out information
test: True
# Define filters which will reduce the number of things,
# all defined filters have to match for further processing
filter:
thing_type: zwave:philio_pst02a_00_000
# Set this configuration every matching thing. HABApp will automatically only
# change the values which are not already correct.
# Here it is the z-wave parameters which are responsible for the device behaviour
thing config:
4: 99 # Light Threshold
5: 8 # Operation Mode
6: 4 # MultiSensor Function Switch
7: 20 # Customer Function
# Create items for every matching thing
create items:
- type: Number
name: '{thing_label, :(.+)$}_MyNumber' # Use the label from the thing as an input for the name,
label: '{thing_label, :(.+)$} MyNumber [%d]' # the regex will take everything from the ':' on until the end
icon: battery
channels:
# reduce the channels of the thing with these filters
# and link items to it
- filter:
channel_type: zwave:alarm_motion
link items:
- type: Number
name: '{thing_label, :(.+)$}_Movement' # Use the label from the thing as an input for the name,
label: '{thing_label, :(.+)$} Movement [%d %%]' # the regex will take everything from the ':' on until the end
icon: battery
groups: ['group1', 'group2']
tags: ['tag1']
- filter:
channel_type: zwave:sensor_temperature
link items:
- type: Number
name: '{thing_label, :(.+)$}_Temperature'
label: '{thing_label, :(.+)$} Temperature [%d %%]'
icon: battery
Multiple filters and filter definitions in one file¶
It is possible to add multiple thing processors into one file. To achieve this the root entry is now a list.
Filters can also be lists e.g. if the have to be applied multiple times to the same filed.
- test: True
filter:
thing_type: zwave:philio_pst02a_00_000
...
- test: True
# multiple filters on the same field, all have to match
filter:
- thing_type: zwave:fibaro.+
- thing_type: zwave:fibaro_fgrgbw_00_000
...
Thing configuration¶
With the thing config
block it is possible to set a configuration for each matching thing.
If the parameters are already correct, they will not be set again.
Warning
The value of the configuration parameters will not be checked and will be written as specified. It is recommended to use HABmin or PaperUI to generate the initial configuration and use this mechanism to spread it to things of the same type.
Example¶
thing config:
4: 99 # Light Threshold
5: 8 # Operation Mode
6: 4 # MultiSensor Function Switch
7: 20 # Customer Function
References to other parameters¶
It is possible to use references to mathematically build parameters from other parameters.
Typically this would be fade duration and refresh interval.
References to other parameter values can be created with $
.
Example:
thing config:
5: 8
6: '$5 / 2' # Use value from parameter 5 and divide it by two.
7: 'int($5 / 2)' # it is possible to use normal python data conversions
Item configuration¶
Items can be configured under create items -> []
and channels -> [] -> link items -> []
.
Structure¶
Mandatory values are type
and name
, all other values are optional.
type: Number
name: my_name
label: my_label
icon: my_icon
groups: ['group1', 'group2']
tags: ['tag1', 'tag1']
Metadata¶
It is possible to add metadata to the created items through the optional metadata
entry in the item config.
There are two forms how metadata can be set. The implicit form for simple key-value pairs (e.g. autoupdate
) or
the explicit form where the entries are unter value
and config
(e.g. alexa
)
- type: Number
name: '{thing_label, :(.+)$}_Temperature'
label: '{thing_label, :(.+)$} Temperature [%d %%]'
icon: battery
metadata:
autoupdate: 'false'
homekit: 'TemperatureSensor'
alexa:
'value': 'Fan'
'config':
'type': 'oscillating'
'speedSteps': 3
The config is equivalent to the following item configuration:
Number MyLabel_Temperature "MyLabel Temperature [%d %%]" { autoupdate="false", homekit="TemperatureSensor", alexa="Fan" [ type="oscillating", speedSteps=3 ] }
Fields¶
Filtering things/channels¶
The filter value can be applied to any available field from the Thing/Channel. The filter value is a regex that has to fully match the value.
Syntax:
filter:
FIELD_NAME: REGULAR_EXPRESSION
e.g.
filter:
thing_uid: zwave:device:controller:node35
If multiple filters are specified all have to match to select the Thing or Channel.
# Multiple filters on different columns
filter:
thing_type: zwave:fibaro.+
thing_uid: zwave:device:controller:node35
# Multiple filters on the same columns (rarely needed)
filter:
- thing_type: zwave:fibaro.+
- thing_type: zwave:fibaro_fgrgbw_00_000
Field values as inputs¶
Filed values are available for item configuration and can be applied to all fields
in the item configuration except for type
and metadata
.
Syntax¶
Macros that select field values are framed with {}
so the containing string has to be put in annotation marks.
There are three modes of operation with wildcards:
- Just insert the value from the field:
{field}
- Insert a part of the value from the field. A regular expression is used to extract the part and therefore has to contain a capturing group.
{field, regex(with_group)}
- Do a regex replace on the value from the field and use the result
{field, regex, replace}
Available fields¶
Tip
Test mode will show a table with all available fields and their value
The following fields are available for things:
thing_uid
thing_type
thing_location
thing_label
bridge_uid
Additional available fields for channels:
channel_uid
channel_type
channel_label
channel_kind
Example¶
Log output¶
This will show the output for the example from File Structure
Loading /config/thing_philio.yml!
+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Thing overview |
+---------------------------------+----------------------------+----------------+----------------------------------------+----------------------------------------------+----------+
| thing_uid | thing_type | thing_location | thing_label | bridge_uid | editable |
+---------------------------------+----------------------------+----------------+----------------------------------------+----------------------------------------------+----------+
| zwave:device:controller:node32 | zwave:fibaro_fgrgbw_00_000 | Room1 | Fibaro RGBW (Node 32): Room1 RGBW | zwave:serial_zstick:controller | True |
| zwave:device:controller:node7 | zwave:fibaro_fgrgbw_00_000 | Room2 | Fibaro RGBW (Node 07): Room2 RGBW | zwave:serial_zstick:controller | True |
| zwave:device:controller:node23 | zwave:fibaro_fgrgbw_00_000 | Room3 | Fibaro RGBW (Node 23): Room3 RGBW | zwave:serial_zstick:controller | True |
| zwave:device:controller:node35 | zwave:philio_pst02a_00_000 | Room1 | Philio PST02A (Node 35): Room1 Door | zwave:serial_zstick:controller | True |
| zwave:device:controller:node15 | zwave:philio_pst02a_00_000 | Room2 | Philio PST02A (Node 15): Room2 Window | zwave:serial_zstick:controller | True |
| zwave:device:controller:node17 | zwave:philio_pst02a_00_000 | Room3 | Philio PST02A (Node 17): Room3 Window | zwave:serial_zstick:controller | True |
| zwave:device:controller:node3 | zwave:philio_pst02a_00_000 | Room1 | Philio PST02A (Node 03): Room1 Window | zwave:serial_zstick:controller | True |
| zwave:device:controller:node5 | zwave:philio_pst02a_00_000 | Room4 | Philio PST02A (Node 05): FrontDoor | zwave:serial_zstick:controller | True |
| zwave:serial_zstick:controller | zwave:serial_zstick | | ZWave Controller | | False |
+---------------------------------+----------------------------+----------------+----------------------------------------+----------------------------------------------+----------+
thing_type "zwave:philio_pst02a_00_000" matches for zwave:device:controller:node35!
thing_type "zwave:philio_pst02a_00_000" matches for zwave:device:controller:node15!
thing_type "zwave:philio_pst02a_00_000" matches for zwave:device:controller:node17!
thing_type "zwave:philio_pst02a_00_000" matches for zwave:device:controller:node3!
thing_type "zwave:philio_pst02a_00_000" matches for zwave:device:controller:node5!
+---------------------------------------------------------------------------------------------------------------------------+
| Current configuration |
+-------------------------+-------------------+-------------------+-------------------+------------------+------------------+
| Parameter | controller:node35 | controller:node15 | controller:node17 | controller:node3 | controller:node5 |
+-------------------------+-------------------+-------------------+-------------------+------------------+------------------+
| 2 | -1 | -1 | -1 | -1 | -1 |
| 3 | 80 | 80 | 80 | 80 | 80 |
| 4 | 99 | 99 | 99 | 99 | 99 |
| 5 | 0 | 8 | 8 | 8 | 8 |
| 6 | 4 | 0 | 0 | 0 | 0 |
| 7 | 22 | 20 | 20 | 20 | 20 |
| 8 | 3 | 3 | 3 | 3 | 3 |
| 9 | 4 | 0 | 4 | 4 | 4 |
| 10 | 12 | 12 | 12 | 12 | 12 |
| 11 | 12 | 12 | 12 | 12 | 12 |
| 12 | 12 | 12 | 2 | 12 | 4 |
| 13 | 12 | 12 | 2 | 12 | 4 |
| 20 | 30 | 30 | 30 | 30 | 30 |
| 21 | 1 | 0 | 0 | 0 | 0 |
| 22 | 0 | 0 | 0 | 0 | 0 |
| Group1 | ['controller'] | ['controller'] | ['controller'] | ['controller'] | ['controller'] |
| Group2 | [] | [] | [] | [] | [] |
| binding_cmdrepollperiod | 1500 | 1500 | 1500 | 1500 | 1500 |
| binding_pollperiod | 86400 | 86400 | 86400 | 86400 | 86400 |
| wakeup_interval | 86400 | 86400 | 86400 | 86400 | 86400 |
+-------------------------+-------------------+-------------------+-------------------+------------------+------------------+
Would set {5: 8, 7: 20} for zwave:device:controller:node35
Would set {6: 4} for zwave:device:controller:node15
Would set {6: 4} for zwave:device:controller:node17
Would set {6: 4} for zwave:device:controller:node3
Would set {6: 4} for zwave:device:controller:node5
+----------------------------------------------------------------------------------------------------------------------+
| Channels for zwave:philio_pst02a_00_000 |
+---------------------------------------------------+--------------------------+------------------------+--------------+
| channel_uid | channel_type | channel_label | channel_kind |
+---------------------------------------------------+--------------------------+------------------------+--------------+
| zwave:device:controller:node35:sensor_door | zwave:sensor_door | Door/Window Sensor | STATE |
| zwave:device:controller:node35:alarm_motion | zwave:alarm_motion | Motion Sensor | STATE |
| zwave:device:controller:node35:alarm_tamper | zwave:alarm_tamper | Tamper Alarm | STATE |
| zwave:device:controller:node35:sensor_luminance | zwave:sensor_luminance | Sensor (luminance) | STATE |
| zwave:device:controller:node35:sensor_temperature | zwave:sensor_temperature | Sensor (temperature) | STATE |
| zwave:device:controller:node35:alarm_access | zwave:alarm_access | Alarm (Access Control) | STATE |
| zwave:device:controller:node35:alarm_burglar | zwave:alarm_burglar | Alarm (Burglar) | STATE |
| zwave:device:controller:node35:battery-level | system:battery-level | Batterieladung | STATE |
+---------------------------------------------------+--------------------------+------------------------+--------------+
channel_type "zwave:alarm_motion" matches for zwave:device:controller:node35:alarm_motion!
channel_type "zwave:sensor_temperature" matches for zwave:device:controller:node35:sensor_temperature!
channel_type "zwave:alarm_motion" matches for zwave:device:controller:node15:alarm_motion!
channel_type "zwave:sensor_temperature" matches for zwave:device:controller:node15:sensor_temperature!
channel_type "zwave:alarm_motion" matches for zwave:device:controller:node17:alarm_motion!
channel_type "zwave:sensor_temperature" matches for zwave:device:controller:node17:sensor_temperature!
channel_type "zwave:alarm_motion" matches for zwave:device:controller:node3:alarm_motion!
channel_type "zwave:sensor_temperature" matches for zwave:device:controller:node3:sensor_temperature!
channel_type "zwave:alarm_motion" matches for zwave:device:controller:node5:alarm_motion!
channel_type "zwave:sensor_temperature" matches for zwave:device:controller:node5:sensor_temperature!
Would create Item(type='Number', name='Room1_Door_MyNumber', label='Room1 Door MyNumber [%d]', icon='battery', groups=[], tags=[], link=None)
Would create Item(type='Number', name='Room1_Door_Movement', label='Room1 Door Movement [%d %%]', icon='battery', groups=['group1', 'group2'], tags=['tag1'], link='zwave:device:controller:node35:alarm_motion')
Would create Item(type='Number', name='Room1_Door_Temperature', label='Room1 Door Temperature [%d %%]', icon='battery', groups=[], tags=[], link='zwave:device:controller:node35:sensor_temperature')
Would create Item(type='Number', name='Room2_Window_MyNumber', label='Room2 Window MyNumber [%d]', icon='battery', groups=[], tags=[], link=None)
Would create Item(type='Number', name='Room2_Window_Movement', label='Room2 Window Movement [%d %%]', icon='battery', groups=['group1', 'group2'], tags=['tag1'], link='zwave:device:controller:node15:alarm_motion')
Would create Item(type='Number', name='Room2_Window_Temperature', label='Room2 Window Temperature [%d %%]', icon='battery', groups=[], tags=[], link='zwave:device:controller:node15:sensor_temperature')
Would create Item(type='Number', name='Room3_Window_MyNumber', label='Room3 Window MyNumber [%d]', icon='battery', groups=[], tags=[], link=None)
Would create Item(type='Number', name='Room3_Window_Movement', label='Room3 Window Movement [%d %%]', icon='battery', groups=['group1', 'group2'], tags=['tag1'], link='zwave:device:controller:node17:alarm_motion')
Would create Item(type='Number', name='Room3_Window_Temperature', label='Room3 Window Temperature [%d %%]', icon='battery', groups=[], tags=[], link='zwave:device:controller:node17:sensor_temperature')
Would create Item(type='Number', name='Room1_Window_MyNumber', label='Room1 Window MyNumber [%d]', icon='battery', groups=[], tags=[], link=None)
Would create Item(type='Number', name='Room1_Window_Movement', label='Room1 Window Movement [%d %%]', icon='battery', groups=['group1', 'group2'], tags=['tag1'], link='zwave:device:controller:node3:alarm_motion')
Would create Item(type='Number', name='Room1_Window_Temperature', label='Room1 Window Temperature [%d %%]', icon='battery', groups=[], tags=[], link='zwave:device:controller:node3:sensor_temperature')
Would create Item(type='Number', name='FrontDoor_MyNumber', label='FrontDoor MyNumber [%d]', icon='battery', groups=[], tags=[], link=None)
Would create Item(type='Number', name='FrontDoor_Movement', label='FrontDoor Movement [%d %%]', icon='battery', groups=['group1', 'group2'], tags=['tag1'], link='zwave:device:controller:node5:alarm_motion')
Would create Item(type='Number', name='FrontDoor_Temperature', label='FrontDoor Temperature [%d %%]', icon='battery', groups=[], tags=[], link='zwave:device:controller:node5:sensor_temperature')
Created items file¶
Number Room1_Door_MyNumber "Room1 Door MyNumber [%d]" <battery>
Number Room1_Door_Movement "Room1 Door Movement [%d %%]" <battery> (group1, group2) [tag1] {channel = "zwave:device:controller:node35:alarm_motion"}
Number Room1_Door_Temperature "Room1 Door Temperature [%d %%]" <battery> {channel = "zwave:device:controller:node35:sensor_temperature"}
Number Room2_Window_MyNumber "Room2 Window MyNumber [%d]" <battery>
Number Room2_Window_Movement "Room2 Window Movement [%d %%]" <battery> (group1, group2) [tag1] {channel = "zwave:device:controller:node15:alarm_motion"}
Number Room2_Window_Temperature "Room2 Window Temperature [%d %%]" <battery> {channel = "zwave:device:controller:node15:sensor_temperature"}
Number Room3_Window_MyNumber "Room3 Window MyNumber [%d]" <battery>
Number Room3_Window_Movement "Room3 Window Movement [%d %%]" <battery> (group1, group2) [tag1] {channel = "zwave:device:controller:node17:alarm_motion"}
Number Room3_Window_Temperature "Room3 Window Temperature [%d %%]" <battery> {channel = "zwave:device:controller:node17:sensor_temperature"}
Number Room1_Window_MyNumber "Room1 Window MyNumber [%d]" <battery>
Number Room1_Window_Movement "Room1 Window Movement [%d %%]" <battery> (group1, group2) [tag1] {channel = "zwave:device:controller:node3:alarm_motion"}
Number Room1_Window_Temperature "Room1 Window Temperature [%d %%]" <battery> {channel = "zwave:device:controller:node3:sensor_temperature"}
Number FrontDoor_MyNumber "FrontDoor MyNumber [%d]" <battery>
Number FrontDoor_Movement "FrontDoor Movement [%d %%]" <battery> (group1, group2) [tag1] {channel = "zwave:device:controller:node5:alarm_motion"}
Number FrontDoor_Temperature "FrontDoor Temperature [%d %%]" <battery> {channel = "zwave:device:controller:node5:sensor_temperature"}
Example openHAB rules¶
Example 1¶
import HABApp
from HABApp.core.events import ValueUpdateEvent, ValueChangeEvent
from HABApp.openhab.events import ItemStateEvent, ItemCommandEvent, ItemStateChangedEvent
from HABApp.openhab.items import SwitchItem, ContactItem, DatetimeItem
class MyOpenhabRule(HABApp.Rule):
def __init__(self):
super().__init__()
# get items
test_contact = ContactItem.get_item('TestContact')
test_date_time = DatetimeItem.get_item('TestDateTime')
test_switch = SwitchItem.get_item('TestSwitch')
# Trigger on item updates
test_contact.listen_event(self.item_state_update, ItemStateEvent)
test_date_time.listen_event(self.item_state_update, ValueUpdateEvent)
# Trigger on item changes
test_contact.listen_event(self.item_state_change, ItemStateChangedEvent)
test_date_time.listen_event(self.item_state_change, ValueChangeEvent)
# Trigger on item commands
test_switch.listen_event(self.item_command, ItemCommandEvent)
def item_state_update(self, event):
assert isinstance(event, ValueUpdateEvent)
print( f'{event}')
def item_state_change(self, event):
assert isinstance(event, ValueChangeEvent)
print( f'{event}')
# interaction is available through self.openhab or self.oh
self.openhab.send_command('TestItemCommand', 'ON')
# example for interaction with openhab item type
switch_item = SwitchItem.get_item('TestSwitch')
if switch_item.is_on():
switch_item.off()
def item_command(self, event):
assert isinstance(event, ItemCommandEvent)
print( f'{event}')
# interaction is available through self.openhab or self.oh
self.oh.post_update('ReceivedCommand', str(event))
MyOpenhabRule()
Check status of things¶
This rule prints the status of all Things
and shows how to subscribe to events of the Thing
status
import HABApp
from HABApp import Rule
from HABApp.openhab.events import ThingStatusInfoChangedEvent
from HABApp.openhab.items import Thing
class CheckAllThings(Rule):
def __init__(self):
super().__init__()
for thing in HABApp.core.Items.get_all_items():
if isinstance(thing, Thing):
thing.listen_event(self.thing_status_changed, ThingStatusInfoChangedEvent)
print(f'{thing.name}: {thing.status}')
def thing_status_changed(self, event: ThingStatusInfoChangedEvent):
print(f'{event.name} changed from {event.old_status} to {event.status}')
CheckAllThings()
Check status if thing is constant¶
Sometimes Things
recover automatically from small outages. This rule only triggers then 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)
self.thing.listen_event(self.thing_no_change, watcher.EVENT)
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