openhab-docs/addons/actions.md

layout	title
documentation	Actions

{% include base.html %}

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:

{::options toc_levels="2..4"/}

• TOC {:toc}

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.

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.

{% for action in site.actions %} {% endfor %}

Name	Description
{% if action.logo %}{% else %}{{ action.label }}{% endif %}	{{ action.description | markdownify }}