OpenHAB
/
openhab-docs
mirror of https://github.com/openhab/openhab-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
openhab-docs/addons/actions.md

10 KiB
Raw Permalink Blame History

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) then use postUpdate.

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 & Voice Actions

The framework supports several multimedia actions. They can be found in the article about openHAB multimedia.

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.

Exec Actions

  • executeCommandLine(String commandLine): Executes a command on the command line without waiting for the command to complete
  • executeCommandLine(String commandLine, int timeout): Executes a command on the command and waits timeout milliseconds for the command to complete, returning the output from the command as a String

Note: The commandLine variable often has to use a special format where @@ needs to be used in place of spaces. For example the bash command touch somefile will have to be written as touch@@somefile.

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.")
}

openHAB Subsystem Actions

openHAB has several subsystems that can be accessed from Rules. These include persistence, see Persistence Extensions in Scripts and Rules, transformations, and scripts.

  • callScript(String scriptName): Calls a script which must be located in the $OPENHAB_CONF/scripts folder.

Scripts are small pieces of Rules DSL code that can be called from Rules. However, Scripts have limitations. Scripts cannot accept arguments. Scripts cannot return a value. Any reference to a class that would normally need to be imported in a .rules file, the class needs to be referred to by its full package as imports are not supported.

  • transform(String type, String function, String value): Applies a transformation of a given type with some function to a value and returns the transformed value as a String or the original value if the transformation failed.

See Transformations for available transformations and their usage.

Cloud Notification Actions

Notification actions may be placed in Rules to send alerts to mobile devices registered with an openHAB Cloud instance such as myopenHAB.org. Three different actions are available:

  • sendNotification("your myopenHAB user email address here","message"): Sends a notification containing 'message'
  • sendBroadcastNotification("message"): Sends a notification containing "message" to all devices of all users
  • sendLogNotification("message"): Sends a log notification containing "message" to the notifications list at your openHAB Cloud instance. Notifications are NOT sent to any registered devices

Example

rule "Front Door Notification"
when
  Item Apartment_FrontDoor changed to OPEN
then
  sendNotification("me@email.com", "Front door was opened!")
end

For information on making use of the openHAB Cloud service hosted by the openHAB Foundation e.V., visit the myopenhab.org website.

Installable Actions

The following actions are available as installable add-ons.

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.addons_actions %} {% endfor %}
Name Description

{% if action.logo %}{{ action.label }}{% else %}{{ action.label }}{% endif %}

 {{ action.description | markdownify }}