core.triggers

This module includes function decorators and Trigger subclasses to simplify Jython rule definitions.

If using a build of openHAB prior to S1566 or 2.5M2, see System Started for a System started workaround. For everyone, see System Shuts Down for a method of executing a function when a script is unloaded, simulating a System shuts down trigger. Along with the when decorator, this module includes the following Trigger subclasses (see Extensions for more details):

  • CronTrigger - fires based on cron expression

  • ItemStateChangeTrigger - fires when the specified Item’s state changes

  • ItemStateUpdateTrigger - fires when the specified Item’s state is updated

  • ItemCommandTrigger - fires when the specified Item receives a Command

  • GenericEventTrigger - fires when the specified occurs

  • ItemEventTrigger - fires when am Item reports an event (based on GenericEventTrigger)

  • ThingEventTrigger - fires when a Thing reports an event (based on GenericEventTrigger)

  • ThingStatusChangeTrigger - fires when the specified Thing’s status changes (requires S1636, 2.5M2 or newer)

  • ThingStatusUpdateTrigger - fires when the specified Thing’s status is updated (requires S1636, 2.5M2 or newer)

  • ChannelEventTrigger - fires when a Channel reports an event

  • DirectoryEventTrigger - fires when a directory’s contents changes

  • ItemRegistryTrigger - fires when the specified Item registry event occurs

  • ItemAddedTrigger - fires when an Item is added (based on ItemRegistryTrigger)

  • ItemRemovedTrigger - fires when an Item is removed (based on ItemRegistryTrigger)

  • ItemUpdatedTrigger - fires when an Item is updated (based on ItemRegistryTrigger)

  • StartupTrigger - fires when the rule is activated (implemented in Jython and requires S1566, 2.5M2 or newer)

core.triggers.when(target)

This function decorator creates triggers attribute in the decorated function that is used by the rule decorator when creating a rule.

The when decorator simplifies the use of many of the triggers in this module and allows for them to be used with natural language similar to what is used in the rules DSL.

See Decorators for examples of how to use this decorator.

Examples

@when("Time cron 55 55 5 * * ?")
@when("Item Test_String_1 changed from 'old test string' to 'new test string'")
@when("Item gMotion_Sensors changed")
@when("Member of gMotion_Sensors changed from ON to OFF")
@when("Descendent of gContact_Sensors changed from OPEN to CLOSED")
@when("Item Test_Switch_2 received update ON")
@when("Item Test_Switch_1 received command OFF")
@when("Thing kodi:kodi:familyroom changed")
@when("Thing kodi:kodi:familyroom changed from ONLINE to OFFLINE")# requires S1636, 2.5M2 or newer
@when("Thing kodi:kodi:familyroom received update ONLINE")# requires S1636, 2.5M2 or newer
@when("Channel astro:sun:local:eclipse#event triggered START")# must use a Channel of kind Trigger
@when("System started")# requires S1566, 2.5M2 or newer ('System shuts down' has not been implemented)
Parameters

target (string) – the rules DSL-like formatted trigger expression to parse

class core.triggers.ItemStateUpdateTrigger(itemName, state=None, triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class builds an ItemStateUpdateTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemStateUpdateTrigger("MyItem", "ON", "MyItem-received-update-ON").trigger]
MyRule.triggers.append(ItemStateUpdateTrigger("MyOtherItem", "OFF", "MyOtherItem-received-update-OFF").trigger)
Parameters
  • itemName (string) – name of item to watch for updates

  • state (string) – (optional) trigger only when updated TO this state

  • triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.ItemStateChangeTrigger(itemName, previousState=None, state=None, triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class builds an ItemStateChangeTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemStateChangeTrigger("MyItem", "OFF", "ON", "MyItem-changed-from-OFF-to-ON").trigger]
MyRule.triggers.append(ItemStateChangeTrigger("MyOtherItem", "ON", "OFF","MyOtherItem-changed-from-ON-to-OFF").trigger)
Parameters
  • itemName (string) – name of item to watch for changes

  • previousState (string) – (optional) trigger only when changing FROM this state

  • state (string) – (optional) trigger only when changing TO this state

  • triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.ItemCommandTrigger(itemName, command=None, triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class builds an ItemCommandTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemCommandTrigger("MyItem", "ON", "MyItem-received-command-ON").trigger]
MyRule.triggers.append(ItemCommandTrigger("MyOtherItem", "OFF", "MyOtherItem-received-command-OFF").trigger)
Parameters
  • itemName (string) – name of item to watch for commands

  • command (string) – (optional) trigger only when this command is received

  • triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.ThingStatusUpdateTrigger(thingUID, status=None, triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class builds a ThingStatusUpdateTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ThingStatusUpdateTrigger("kodi:kodi:familyroom", "ONLINE").trigger]
Parameters
  • thingUID (string) – name of the Thing to watch for status updates

  • status (string) – (optional) trigger only when Thing is updated to this status

  • triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule.

Type

Trigger

class core.triggers.ThingStatusChangeTrigger(thingUID, previousStatus=None, status=None, triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class builds a ThingStatusChangeTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ThingStatusChangeTrigger("kodi:kodi:familyroom", "ONLINE", "OFFLINE).trigger]
Parameters
  • thingUID (string) – name of the Thing to watch for status changes

  • previousStatus (string) – (optional) trigger only when Thing is changed from this status

  • status (string) – (optional) trigger only when Thing is changed to this status

  • triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.ChannelEventTrigger(channelUID, event=None, triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class builds a ChannelEventTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ChannelEventTrigger("astro:sun:local:eclipse#event", "START", "solar-eclipse-event-start").trigger]
Parameters
  • channelUID (string) – name of the Channel to watch for trigger events

  • event (string) – (optional) trigger only when Channel triggers this event

  • triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.GenericEventTrigger(eventSource, eventTypes, eventTopic='smarthome/*', triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class builds a GenericEventTrigger Module to be used when creating a Rule. It allows you to trigger on any event that comes through the Event Bus. It’s one of the the most powerful triggers, but it is also the most complicated to configure.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [GenericEventTrigger("smarthome/items/Test_Switch_1/", "ItemStateEvent", "smarthome/items/*", "Test_Switch_1-received-update").trigger]
Parameters
  • eventSource (string) – source to watch for trigger events

  • eventTypes (string or list) – types of events to watch

  • eventTopic (string) – (optional) topic to watch

  • triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.ItemEventTrigger(eventSource, eventTypes, eventTopic='smarthome/items/*', triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class is the same as the GenericEventTrigger, but simplifies it a bit for use with Items. The available Item eventTypes are:

"ItemStateEvent" (Item state update)
"ItemCommandEvent" (Item received Command)
"ItemStateChangedEvent" (Item state changed)
"GroupItemStateChangedEvent" (GroupItem state changed)

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemEventTrigger("Test_Switch_1", "ItemStateEvent", "smarthome/items/*").trigger]
Parameters
  • eventSource (string) – source to watch for trigger events

  • eventTypes (string or list) – types of events to watch

  • eventTopic (string) – (optional) topic to watch (no need to change default)

  • triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.ThingEventTrigger(thingUID, eventTypes, eventTopic='smarthome/things/*', triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class is the same as the GenericEventTrigger, but simplifies it a bit for use with Things. The available Thing eventTypes are:

"ThingAddedEvent"
"ThingRemovedEvent"
"ThingStatusInfoChangedEvent"
"ThingStatusInfoEvent"
"ThingUpdatedEvent"

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ThingEventTrigger("kodi:kodi:familyroom", "ThingStatusInfoEvent").trigger]
Parameters
  • eventSource (string) – source to watch for trigger events

  • eventTypes (string or list) – types of events to watch

  • eventTopic (string) – (optional) topic to watch (no need to change default)

  • triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.CronTrigger(cronExpression, triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class builds a CronTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [CronTrigger("0 55 17 * * ?").trigger]
Parameters
  • cronExpression (string) – a valid cron expression

  • triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.StartupTrigger(triggerName=None)

Bases: org.openhab.core.automation.Trigger

This class builds a StartupTrigger Module to be used when creating a Rule.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [StartupTrigger().trigger]
Parameters

triggerName (string) – (optional) name of this trigger

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.ItemRegistryTrigger(event_name)

Bases: core_mock.osgi.events.OsgiEventTrigger

This class builds an OsgiEventTrigger Module to be used when creating a Rule. Requires the 100_OsgiEventTrigger.py component script. The available Item registry event_names are:

"ItemAddedEvent"
"ItemRemovedEvent"
"ItemUpdatedEvent"

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemRegistryTrigger("ItemAddedEvent").trigger]
Parameters

event_name (string) – name of the event to watch

trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.ItemAddedTrigger

Bases: core.triggers.ItemRegistryTrigger

This class is the same as the ItemRegistryTrigger, but limited to when an Item is added. This trigger will fire when any Item is added.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemAddedTrigger().trigger]
trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.ItemRemovedTrigger

Bases: core.triggers.ItemRegistryTrigger

This class is the same as the ItemRegistryTrigger, but limited to when an Item is removed. This trigger will fire when any Item is removed.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemRemovedTrigger().trigger]
trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.ItemUpdatedTrigger

Bases: core.triggers.ItemRegistryTrigger

This class is the same as the ItemRegistryTrigger, but limited to when an Item is updated. This trigger will fire when any Item is updated.

See Extensions for examples of how to use these extensions.

Examples

MyRule.triggers = [ItemUpdatedTrigger().trigger]
trigger

Trigger object to be added to a Rule

Type

Trigger

class core.triggers.DirectoryEventTrigger(path, event_kinds=[java.nio.file.StandardWatchEventKinds.ENTRY_CREATE, java.nio.file.StandardWatchEventKinds.ENTRY_DELETE, java.nio.file.StandardWatchEventKinds.ENTRY_MODIFY], watch_subdirectories=False)

Bases: org.openhab.core.automation.Trigger

This class builds a DirectoryEventTrigger Module to be used when creating a Rule. Requires the 100_DirectoryTrigger.py component script.

See Extensions for examples of how to use these extensions.

Parameters
  • path (string) – path of the directory to watch

  • event_kinds (list) – (optional) list of the events to watch for

  • watch_subdirectories (Boolean) – (optional) True will watch subdirectories

trigger

Trigger object to be added to a Rule

Type

Trigger