10 KiB

Raw Blame History

layout	title
documentation	JSR223 Scripting

{% include base.html %}

JSR223 Scripting

Note: This feature is for users who have or are willing to learn some programming skills and are comfortable working with the command line prompt of the operating system hosting openHAB. The Experimental Rule Engine add-on must be installed to define rules.

Overview

JSR223 (spec) is a standard scripting API for Java Virtual Machine (JVM) languages. The JVM languages provide varying levels of support for the JSR223 API and interoperability with the Java runtime. Currently the following languages are known to work well for openHAB scripting: Oracle Nashorn (Javascript bundled with Java), Jython (Python on the JVM) and Apache Groovy (JVM scripting language).

Although JSR223 scripts can be used as a general-purpose extension language for openHAB, the most common usage will be for defining openHAB rules.

Language-Specific Documentation

Javascript
Jython
Groovy (TODO)

Script Locations

Scripts should be placed in the 'USERDATA/automation/jsr223' directory. For example, in Linux installations created with a package installer, the directory would be /etc/openhab2/automation/jsr223.

At system start time the scripts will be loaded in an order based on their name and then top-down through the directory hierarchy. Note that while scripts may be placed in subdirectories of jsr223, they should not have the same names as scripts in other directories (this may be changed in the future). For example, with the following directory structure...

automation/jsr223
  01/
    script1.py
    scriptx.py
  00script.py
  script2.py

the load order will be: 00script.py, 01/script1.py, script2.py, 01/scriptx.py.

Trigger Types (all JSR223 languages)

The following trigger types are defined by openHAB (custom triggers can also be defined) and take the specified configuration parameters.

Trigger: `core.ItemCommandTrigger`
`itemName`
`command`

Trigger: `core.ItemStateUpdateTrigger`
`itemName`
`state`

Trigger: `core.ItemStateChangeTrigger`
`itemName`
`previousState`
`state`

Trigger: `timer.GenericCronTrigger`
`cronExpression`

Trigger: `timer.TimeOfDayTrigger`
`time`

Trigger: `core.GenericEventTrigger`
`eventTopic`
`eventSource`
`eventTypes`

Additional Information

Scripted Rule Support - Early documentation on JSR223 usage in openHAB 2. Includes IDE setup instructions.

Predefined Script Variables (all JSR223 languages)

To faciliate JSR223 scripting, several openHAB-related variables are automatically predefined. These presets include:

Default
RuleSimple
RuleSupport
RuleFactories

Default Variables (no preset loading required)

Variable	Description
`State`	`org.eclipse.smarthome.core.types.State`
`Command`	`org.eclipse.smarthome.core.types.State`
`DateTime`	`org.joda.time.DateTime` (if Jodatime is available)
`LocalTime`	`org.joda.time.LocalTime` (if Jodatime is available)
`StringUtils`	`org.apache.commons.lang.StringUtils`
`URLEncoder`	`java.net.URLEncoder`
`FileUtils`	`org.apache.commons.io.FileUtils`
`FilenameUtils`	`org.apache.commons.io.FilenameUtils`
`File`	`java.io.File`
`UnDefType`	`org.eclipse.smarthome.core.library.types.UnDefType`
`NULL`	`UnDefType` enum item
`UNDEF`	`UnDefType` enum item
`IncreaseDecreaseType`	`org.eclipse.smarthome.core.library.types.IncreaseDecreaseType`
`DECREASE`	`IncreaseDecreaseType` enum item
`INCREASE`	`IncreaseDecreaseType` enum item
`OnOffType`	`org.eclipse.smarthome.core.library.types.OnOffType`
`ON`	`OnOffType` enum item
`OFF`	`OnOffType` enum item
`OpenClosedType`	`org.eclipse.smarthome.core.library.types.OpenClosedType`
`OPEN`	`OpenClosedType` enum item
`CLOSED`	`OpenClosedType` enum item
`StopMoveType`	`org.eclipse.smarthome.core.library.types.StopMoveType`
`STOP`	`StopMoveType` enum item
`MOVE`	`StopMoveType` enum item
`RewindFastforwardType`	`org.eclipse.smarthome.core.library.types.RewindFastforwardType`
`REWIND`	`RewindFastforwardType` enum item
`FASTFORWARD`	`RewindFastforwardType` enum item
`NextPreviousType`	`org.eclipse.smarthome.core.library.types.NextPreviusType`
`NEXT`	`NextPreviousType` enum item
`PREVIOUS`	`NextPreviousType` enum item
`PlayPauseType`	`org.eclipse.smarthome.core.library.types.PlayPauseType`
`PLAY`	`PlayPauseType` enum item
`PAUSE`	`PlayPauseType` enum item
`UpDownType`	`org.eclipse.smarthome.core.library.types.UpDownType`
`UP`	`UpDownType` enum item
`DOWN`	`UpDownType` enum item
`DecimalType`	`org.eclipse.smarthome.core.library.types.DecimalType`
`QuantityType`	`org.eclipse.smarthome.core.library.types.QuantityType`
`HSBType`	`org.eclipse.smarthome.core.library.types.HSBType`
`PercentType`	`org.eclipse.smarthome.core.library.types.PercentType`
`PointType`	`org.eclipse.smarthome.core.library.types.PointType`
`StringType`	`org.eclipse.smarthome.core.library.types.StringType`
`StringListType`	`org.eclipse.smarthome.core.library.types.StringListType`
`RawType`	`org.eclipse.smarthome.core.library.types.RawType`
`items`	Instance of `java.util.Map<String, State>`
`itemRegistry`	Instance of `org.eclipse.smarthome.core.items.ItemRegistry`
`ir`	Alias for `itemRegistry`
`things`	Instance of `org.eclipse.smarthome.core.thing.ThingRegistry`
`events`	(internal) Used to send events, post commands, etc. Details below]
`rules`	Instance of `org.eclipse.smarthome.automation.RuleRegistry`
`scriptExtension`	(internal) For loading script presets.
`se`	Alias for `scriptExtension`

`events` operations

postUpdate(String, String)
postUpdate(Item, Number)
postUpdate(Item, String)
postUpdate(Item, State)
sendCommand(String, String)
sendCommand(Item, Number)
sendCommand(Item, String)
sendCommand(Item, Command)
storeStates(Item...)
restoreStates(Map<Item, State>)

RuleSimple Extension/Preset

These variables are loaded using:

scriptExtension.importPreset("RuleSimple")

The primary usage of this preset is for defining rule (SimpleRule) subclasses. See language-specific documentation for examples.

Variable	Description
SimpleRule	Base class for Jython Rules
SimpleActionHandler	`org.eclipse.smarthome.automation.module.script.rulesupport.shared.simple.SimpleActionHandler`
SimpleConditionHandler	`org.eclipse.smarthome.automation.module.script.rulesupport.shared.simple.SimpleConditionHandler`
SimpleTriggerHandler	`org.eclipse.smarthome.automation.module.script.rulesupport.shared.simple.SimpleTriggerHandler`
TriggerType	`org.eclipse.smarthome.automation.type.TriggerType`
ConfigDescriptionParameter	`org.eclipse.smarthome.config.core.ConfigDescriptionParameter`
ModuleType	`org.eclipse.smarthome.automation.type.ModuleType`
ActionType	`org.eclipse.smarthome.automation.type.ActionType`
Visibility	`org.eclipse.smarthome.automation.Visibility` enum

RuleSupport Extension/Preset