Actions

Actions are predefined methods that are called from openHAB rules and scripts. They are automatically imported and can be used to execute openHAB-specific operations or to send commands or data to external hardware or services. There are a set of built in core Actions and optional installable Actions.

The page is structured as follows:

Core Actions

The following Actions are a core part of openHAB and do not need to be separately installed.

Event Bus Actions

  • sendCommand(String itemName, String commandString): Sends the given command to the specified Item to the event bus.
  • postUpdate(String itemName, String commandString): Sends the given status update to the specified Item to the event bus.

When the result of the commandString is to cause some action (e.g. turn on a light, change a thermostat to a new temperature, etc.) then use sendCommand. When interacting with widgets on the user interfaces commands are sent to the Items.

When the result of the commandString is to change the state of an Item without causing some action (i.e. to make the state of an Item match the state of a device without commanding the device to change).

As a general rule, is better to call MyItem.sendCommand(command) and MyItem.postUpdate(command) where possible because the Item methods are able to handle a wider variety of commands appropriately. The Actions are best reserved for use in cases where the Item’s name is determined at runtime.

  • Map<Item, State> storeStates(Item item1, Item item2, ... Item itemn): Returns a Map<Item, State> with the current state of each Item. All members of Groups are put into the Map but not the Group’s state itself.
  • restoreStates(Map<Item, State> statesMap): Restores the items’ states from the map. If the saved state can be interpreted as a command (ON/OFF/etc.), a command is sent to the Item. Otherwise an update is sent to the Item.

Audio Actions

  • setMasterVolume(float volume): Sets the volume of the host machine (volume in range 0-1)
  • increaseMasterVolume(float percent): Increases the volume by the given percent
  • decreaseMasterVolume(float percent): Decreases the volume by the given percent
  • float getMasterVolume(): Returns the current volume as a float between 0 and 1
  • playSound(String filename): Plays the given sound file. The file must be an mp3 or wav and located in ${openhab.home}/sounds
  • playStream(String url): Plays the audio stream at the given url
  • say(String text): Says the given text through Text-to-Speech
  • say(String text, String voice): Says the given text through the given voice (depends on the TTS engine and voices installed)
  • say(String text, String voice, String device): Says the given text through the given voice to the given output device (Mac OSX only).

To get a list of available voices use say -v ? and to get a list of devices uses say -a ?.

Logging Actions

  • logDebug(String loggername, String logText): Logs logText on level DEBUG to openhab.log
  • logInfo(String loggername, String logText): Logs logText on level INFO to openhab.log
  • logWarn(String loggername, String logText): Logs logText on level WARN to openhab.log
  • logError(String loggername, String logText): Logs logText on level ERROR to openhab.log

logText can be a compete String, constructed through concatination, or through arguments.

  • Complete String Example: logInfo("Garage", "This is a complete String")
  • Concatination Example: logDebug("Lighting", "This is a string concatination:" + Light.name)
  • Arguments Example: logWarn("Alarm", "The {} window has been open for {} hours!", Window.name, timeOpen)

One can configure whether specific log entries are logged out and where they get logged to (e.g. to a separate file) by editing the logger configuration.

HTTP Actions

  • sendHttpGetRequest(String url): Sends an GET-HTTP request and returns the result as a String
  • sendHttpPutRequest(String url): Sends a PUT-HTTP request and returns the result as a String
  • sendHttpPutRequest(String url, Sting contentType, String content): Sends a PUT-HTTP request with the given content and returns the result as a String
  • sendHttpPostRequest(String url): Sends a POST-HTTP request and returns the result as a String
  • sendHttpPostRequest(String url, String contentType, String content): Sends a POST-HTTP request with the given content and returns the result as a String
  • sendHttpDeleteRequest(String url): Sends a DELETE-HTTP request and returns the result as a String

Timers

createTimer(AbstractInstant instant, Procedure procedure): schedules a block of code to execute at a future time

  • instant is usually a DateTime calculated using the built in variable now.
  • procedure is the block of code and is defined using lambda notation (i.e. square brackets)

For example:

var Timer myTimer = createTimer(now.plusMinutes(5), [|
    logInfo("rules", "Timer activated")
])

The Timer object supports the following methods:

  • cancel: prevents the scheduled timer from executing
  • isRunning: returns true if the code is currently executing (i.e. the timer activated the code but it is not done running)
  • hasTerminated: returns true if the code has run and completed
  • reschedule(AbstractInstant instant): reschedules the timer to execute at the new time. If the Timer has terminated this method does nothing.

Thing Status Action

getThingStatusInfo(String thingUID): Gets status information of the given thing identified by thingUID.

The result is of type ThingStatusInfo. It contains Thing Status, Status Details and Status Description. Refer to Thing Status API for how to get those information. If you just want to know the status, you can use thingStatusInfo.getStatus().toString() and the result will be one of the values in Thing Status.

If the thing is removed or it’s not added yet, it’ll return null.

For example:

var thingStatusInfo = getThingStatusInfo("zwave:device:c5155aa4:node2")

if ((thingStatusInfo != null) && (thingStatusInfo.getStatus().toString() == "ONLINE")) {
    logInfo("ThingStatus", "The thing is online.")
} else {
    logError("ThingStatus", "The thing is offline or doesn't exist.")
}

Installable Actions

Some openHAB 1 actions have not yet completed validation for inclusion in the distribution; however, they may indeed work properly under openHAB 2. All openHAB 1 addons can be downloaded in a zip file. We need your help testing them so that they may be easily installed in a future distribution. Please see the compatibility layer documentation and also search the openHAB community forum for the latest information and steps for manual installation.

Name Description

Astro

With the Astro actions, you can calculate sunrise and sunset DataTime values in rules.

Cisco Spark

Cisco Spark can be used to message individuals are rooms when certain events take place in openHAB.

This bundle exposes openHAB rule extensions to be used with the DSC Alarm Binding (1.x binding). It allows the sending of DSC Alarm specific commands from within rules.

The Ecobee Action bundle provides actions such as setting and clearing program holds, sending a text message to the thermostat’s display, renaming a remote wireless sensor, and other functions that cannot be performed by setting object properties.

Logitech Harmony Hub

  • harmonyPressButton(<device>, <command>)

The Homematic action lets you send messages to a Homematic remote control with a display, currently the HM-RC-19-B (Radio remote control 19 button).

Mail

This add-on provides SMTP services so your rules and scripts can send e-mails. The to paremeter can contain a semicolon-separated list of email addresses.

MiOS

This bundle exposes openHAB Rule extensions to be used with the MiOS Binding (1.x).

Publish a message to a topic on an MQTT broker.

NotifyMyAndroid

Sends push messages to your Android devices.

OpenWebIf

The OpenWebIf action allows you to send a message to enigma2-based Linux satellite receivers (Dreambox, VU+, Clarke-Tech, …) with the installed OpenWebIf plugin.

Pebble

The Pebble action service allows you to send pins and notifications directly to your Pebble watch.

Prowl

Prowl lets you use push notifications on iOS devices (please check openhab.cfg for required configuration settings):

The Pushover action service allows you to notify mobile devices of a message using the Pushover API web service.

Pushsafer

The Pushsafer action allows you to notify iOS, Android & Windows 10 Phone & Desktop devices of a message using the Pushsafer API web service.

Satel

The Satel Action bundle provides actions to read the event log of the connected alarm system, check current connection status and override configured user code.

Interact directly with your Squeezebox devices from within rules and scripts.

Telegram

The Telegram Action service allows sending formatted messages to Telegram clients (https://telegram.org), by using the Telegram Bot API.

The TinkerForge Action service provides direct interaction with some of the TinkerForge devices.

Twitter can be used to ‘tweet’ notifications when certain events take place in openHAB.

Weather

The Weather Action service provides meteorological information to your scripts and rules.

Sends notifications to the Kodi open source home theater software (formerly known as XBMC).

This set of actions allows you to send a message to an XMPP user or multi-user chat, or send a message with an attachment to an XMPP user.

xPL

This add-on provides xPL message sending on the network.