diff --git a/addons/actions.md b/addons/actions.md index 4fe826f8b..8624418fd 100644 --- a/addons/actions.md +++ b/addons/actions.md @@ -7,8 +7,95 @@ title: Actions # Actions -Actions are predefined methods for openHAB rules and scripts. -They are automatically imported and can be used to execute openHAB-specific operations or to send commands or data to hardware or services. +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 storeStates(Item item1, Item item2, ... Item itemn)`: Returns a `Map` 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 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]({{base}}/administration/logging.html). + +### 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: + +```java +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 @@ -21,7 +108,7 @@ They are automatically imported and can be used to execute openHAB-specific oper

- Some openHAB 1 actions have not yet completed validation for inclusion in the distribution; however, they may indeed work properly under openHAB 2. + 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