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

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 Variables (no preset loading required)

VariableDescription
Stateorg.eclipse.smarthome.core.types.State
Commandorg.eclipse.smarthome.core.types.State
DateTimeorg.joda.time.DateTime (if Jodatime is available)
LocalTimeorg.joda.time.LocalTime (if Jodatime is available)
StringUtilsorg.apache.commons.lang.StringUtils
URLEncoderjava.net.URLEncoder
FileUtilsorg.apache.commons.io.FileUtils
FilenameUtilsorg.apache.commons.io.FilenameUtils
Filejava.io.File
IncreaseDecreaseTypeorg.eclipse.smarthome.core.library.types.IncreaseDecreaseType
DECREASEIncreaseDecreaseType enum item
INCREASEIncreaseDecreaseType enum item
OnOffTypeorg.eclipse.smarthome.core.library.types.OnOffType
ONOnOffType enum item
OFFOnOffType enum item
OpenClosedTypeorg.eclipse.smarthome.core.library.types.OpenClosedType
OPENOpenClosedType enum item
CLOSEDOpenClosedType enum item
StopMoveTypeorg.eclipse.smarthome.core.library.types.StopMoveType
STOPStopMoveType enum item
MOVEStopMoveType enum item
UpDownTypeorg.eclipse.smarthome.core.library.types.UpDownType
UPUpDownType enum item
DOWNUpDownType enum item
DecimalTypeorg.eclipse.smarthome.core.library.types.DecimalType
HSBTypeorg.eclipse.smarthome.core.library.types.HSBType
PercentTypeorg.eclipse.smarthome.core.library.types.PercentType
PointTypeorg.eclipse.smarthome.core.library.types.PointType
StringTypeorg.eclipse.smarthome.core.library.types.StringType
itemsInstance of java.util.Map<String, State>
itemRegistryInstance of org.eclipse.smarthome.core.items.ItemRegistry
irAlias for itemRegistry
thingsInstance of org.eclipse.smarthome.core.thing.ThingRegistry
events(internal) Used to send events, post commands, etc. Details below]
rulesInstance of org.eclipse.smarthome.automation.RuleRegistry
scriptExtension(internal) For loading script presets.
seAlias 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.

VariableDescription
SimpleRuleBase class for Jython Rules
SimpleActionHandlerorg.eclipse.smarthome.automation.module.script.rulesupport.shared.simple.SimpleActionHandler
SimpleConditionHandlerorg.eclipse.smarthome.automation.module.script.rulesupport.shared.simple.SimpleConditionHandler
SimpleTriggerHandlerorg.eclipse.smarthome.automation.module.script.rulesupport.shared.simple.SimpleTriggerHandler
TriggerTypeorg.eclipse.smarthome.automation.type.TriggerType
ConfigDescriptionParameterorg.eclipse.smarthome.config.core.ConfigDescriptionParameter
ModuleTypeorg.eclipse.smarthome.automation.type.ModuleType
ActionTypeorg.eclipse.smarthome.automation.type.ActionType
Visibilityorg.eclipse.smarthome.automation.Visibility enum

RuleSupport Extension/Preset

These variables are loaded using:

scriptExtension.importPreset("RuleSupport")
VariableDescription
automationManagerInstance for managing rules and other openHAB module instances. (e.g., addRule)
Configurationorg.eclipse.smarthome.config.core.Configuration
Actionorg.eclipse.smarthome.config.core.Action
Conditionorg.eclipse.smarthome.config.core.Condition
Triggerorg.eclipse.smarthome.config.core.Trigger
Ruleorg.eclipse.smarthome.config.core.Action.Rule (use SimpleRule for defining rules)

RuleFactories Extension

NOTE: Advanced usage

scriptExtension.importPreset("RuleFactories")
VariableDescription
ActionHandlerFactoryorg.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.ActionHandlerFactory
ConditionHandlerFactoryorg.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.ConditionHandlerFactory
TriggerHandlerFactoryorg.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.TriggerHandlerFactory
TriggerTypeorg.eclipse.smarthome.automation.type.TriggerType
ConfigDescriptionParameterorg.eclipse.smarthome.config.core.ConfigDescriptionParameter
ModuleTypeorg.eclipse.smarthome.automation.type.ModuleType
ActionTypeorg.eclipse.smarthome.automation.type.ActionType
Visibilityorg.eclipse.smarthome.automation.Visibility enum