[Actions] Initial addition of core actions. (#397)
* Initial addition of documentation for core actions. Signed off by Richard Koshak <rlkoshak@gmail.com> Signed-off-by: Richard Koshak <rlkoshak@gmail.com> * Making Thom's requested changes. - fixed spelling of specified - added missing itemization * to logging section. - added missing itemization * to createTimer section Signed off by Richard Koshak <rlkoshak@gmail.com> Signed-off-by: Richard Koshak <rlkoshak@gmail.com> * Add toc Signed-off-by: Thomas Dietrich <thomas.dietrich@tu-ilmenau.de> (github: ThomDietrich)pull/420/head
Richard Koshak
Thomas Dietrich
parent
d322373711
commit
c6cc435ddd
|
|
@ -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<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]({{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
|
||||
|
||||
<table id="actions-select" class="striped">
|
||||
<tbody>
|
||||
|
|
@ -21,7 +108,7 @@ They are automatically imported and can be used to execute openHAB-specific oper
|
|||
</td>
|
||||
<td>
|
||||
<p>
|
||||
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 <a href="https://bintray.com/openhab/mvn/download_file?file_path=org%2Fopenhab%2Fdistro%2Fopenhab%2F1.9.0%2Fopenhab-1.9.0-addons.zip">zip file</a>.
|
||||
We need your help testing them so that they may be easily installed in a future distribution.
|
||||
Please see the <a href="{{base}}/developers/development/compatibilitylayer.html#how-to-use-openhab-1x-add-ons-that-are-not-part-of-the-distribution">compatibility layer documentation</a> and
|
||||
|
|
|
|||
Loading…
Reference in New Issue