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 The item name TEXT
command The command TEXT
Trigger: core.ItemStateUpdateTrigger    
itemName The item name TEXT
state The state TEXT
Trigger: core.ItemStateChangeTrigger    
itemName The item name TEXT
previousState The previous state TEXT
state The state TEXT
Trigger: timer.GenericCronTrigger    
cronExpression The cron expression TEXT
Trigger: timer.TimeOfDayTrigger    
time The time in “hh:mm” format TEXT
Trigger: core.GenericEventTrigger    
eventTopic default: “smarthome/” (for channel events: “smarthome/channels//triggered”) TEXT
eventSource item name, channel UID TEXT
eventTypes ItemCommandEvent, ItemStateEvent TEXT

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)

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
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
UpDownType org.eclipse.smarthome.core.library.types.UpDownType
UP UpDownType enum item
DOWN UpDownType enum item
DecimalType org.eclipse.smarthome.core.library.types.DecimalType
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
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

These variables are loaded using:

scriptExtension.importPreset("RuleSupport")
Variable Description
automationManager Instance for managing rules and other openHAB module instances. (e.g., addRule)
Configuration org.eclipse.smarthome.config.core.Configuration
Action org.eclipse.smarthome.config.core.Action
Condition org.eclipse.smarthome.config.core.Condition
Trigger org.eclipse.smarthome.config.core.Trigger
Rule org.eclipse.smarthome.config.core.Action.Rule (use SimpleRule for defining rules)

RuleFactories Extension

NOTE: Advanced usage

scriptExtension.importPreset("RuleFactories")
Variable Description
ActionHandlerFactory org.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.ActionHandlerFactory
ConditionHandlerFactory org.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.ConditionHandlerFactory
TriggerHandlerFactory org.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.TriggerHandlerFactory
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