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 (opens new window) (spec (opens new window)) is a standard scripting API for Java Virtual Machine (JVM) languages (opens new window). 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: Jython (opens new window) (Python on the JVM), Nashorn Javascript (opens new window) (ECMAScript implementation included in JDK8 through 10, deprecated in 11 (opens new window)), and Apache Groovy (opens new window) (JVM scripting language).

Although JSR223 scripts can be used as a general-purpose extension language for openHAB, it is most commonly used for the creation of rules, and within scripted Actions or Conditions. Currently, openHAB allows JSR223 scripting to access all packages, which may not be included in the official APIs. This provides great flexibility for the users of JSR223, but is also use at your own risk, since changes outside of the offical APIs occur frequently, and are not considered to be breaking changes. New APIs are planned to be implemented in the future, which will provide standardized interfaces for interacting with openHAB through scripted automation.

Language-Specific Documentation

• Jython
• Javascript
• Groovy (TODO)

Example rules for a first impression

'use strict';

scriptExtension.importPreset("RuleSupport");
scriptExtension.importPreset("RuleSimple");

var sRule = new SimpleRule() {
    execute: function( module, input) {
        print("This is a 'hello world!' from a Javascript rule.");
    }
};

sRule.setTriggers([
    TriggerBuilder.create()
        .withId("aTimerTrigger")
        .withTypeUID("timer.GenericCronTrigger")
        .withConfiguration(
            new Configuration({
                "cronExpression": "0 * * * * ?"
            })).build()
    ]);

automationManager.addRule(sRule);

scriptExtension.importPreset("RuleSupport")
scriptExtension.importPreset("RuleSimple")

class myRule(SimpleRule):
    def execute(self, module, inputs):
        print "This is a 'hello world!' from Jython rule."

sRule = myRule()
sRule.setTriggers([
    TriggerBuilder.create()
        .withId("aTimerTrigger")
        .withTypeUID("timer.GenericCronTrigger")
        .withConfiguration(
            Configuration({
                "cronExpression": "0 * * * * ?"
            })).build()
    ])

automationManager.addRule(sRule)

import org.openhab.core.automation.*
import org.openhab.core.automation.module.script.rulesupport.shared.simple.*
import org.eclipse.smarthome.config.core.Configuration

scriptExtension.importPreset("RuleSupport")
scriptExtension.importPreset("RuleSimple")

def sRule = new SimpleRule() {
    Object execute(Action module, Map<String, ?> inputs) {
        println("Hello World from Groovy")
    }
}
sRule.setTriggers([
    TriggerBuilder.create()
        .withId("aTimerTrigger")
        .withTypeUID("timer.GenericCronTrigger")
        .withConfiguration(new Configuration([cronExpression: "0 * * * * ?"]))
        .build()
    ])

automationManager.addRule(sRule)

Script Locations

Scripts should be placed in the ${OPENHAB_CONF}/automation/jsr223/ directory. This directory will vary, based on the type of openHAB installation used (opens new window). For example, Linux installations created with a package installer will use /etc/openhab2/automation/jsr223/, and manual installations will use /opt/openhab2/conf/automation/jsr223/.

When openHAB starts, scripts will be loaded in an order based on their file name. If the scripts have the same name, which should rarely happen, the parent directories will be considered in the sort. For example, with the following scripts and directory structure...

├── automation/jsr223
│   ├── dir1
│   │   ├── 001_script.py
│   │   └── script.py
│   ├── 001_script.py
│   ├── dir2
│   │   ├── 002_script.py
│   │   └── script.py
│   └── script.py

... the load order will be: /001_script.py, /dir1/001_script.py, /dir2/002_script.py, /script.py, /dir1/script.py, /dir2/script.py.

ScriptExtension Objects (all JSR223 languages)

To faciliate JSR223 scripting, several openHAB-related variables are automatically predefined within ScriptExtension presets. They can be loaded into the script context using scriptExtension.importPreset(String preset), e.g. scriptExtension.importPreset("RuleSimple"). The default preset is preloaded, so it does not require importing.

• Default
• RuleSimple
• RuleSupport
• RuleFactories

Default Preset (importPreset not required)

Variable	Description
DateTime	org.joda.time.DateTime (if Jodatime is available)
LocalTime	org.joda.time.LocalTime (if Jodatime is available)
State	org.eclipse.smarthome.core.types.State
Command	org.eclipse.smarthome.core.types.State
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
UnDefType	org.eclipse.smarthome.core.library.types.UnDefType
NULL	UnDefType enum item
UNDEF	UnDefType enum item
RefreshType	org.eclipse.smarthome.core.library.types.RefreshType
REFRESH	RefreshType 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
RewindFastforwardType	org.eclipse.smarthome.core.library.types.RewindFastforwardType
REWIND	RewindFastforwardType enum item
FASTFORWARD	RewindFastforwardType enum item
QuantityType	org.eclipse.smarthome.core.library.types.QuantityType
StringListType	org.eclipse.smarthome.core.library.types.StringListType
RawType	org.eclipse.smarthome.core.library.types.RawType
DateTimeType	org.eclipse.smarthome.core.library.types.DateTimeType
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
SIUnits	org.eclipse.smarthome.core.library.unit.SIUnits
ImperialUnits	org.eclipse.smarthome.core.library.unit.SmartHomeUnits
MetricPrefix	org.eclipse.smarthome.core.library.unit.SmartHomeUnits
SmartHomeUnits	org.eclipse.smarthome.core.library.unit.SmartHomeUnits
BinaryPrefix	org.eclipse.smarthome.core.library.unit.SmartHomeUnits
items	Instance of java.util.Map<String, State>
ir	Alias for itemRegistry
itemRegistry	Instance of org.eclipse.smarthome.core.items.ItemRegistry
things	Instance of org.eclipse.smarthome.core.thing.ThingRegistry
rules	Instance of org.openhab.core.automation.RuleRegistry
events	(internal) Used to send events, post commands, etc. Details below]
actions	Instance of org.eclipse.smarthome.core.thing.binding.ThingActions
scriptExtension	(internal) For loading script presets.
se	Alias for scriptExtension

events operations

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

RuleSimple Preset

These variables and classes 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
ActionType	org.openhab.core.automation.type.ActionType
ConfigDescriptionParameter	org.eclipse.smarthome.config.core.ConfigDescriptionParameter
ModuleType	org.openhab.core.automation.type.ModuleType
SimpleActionHandler	org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleActionHandler
SimpleConditionHandler	org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleConditionHandler
SimpleRule	Base class for Jython Rules org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleRule
SimpleTriggerHandler	org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleTriggerHandler
TriggerType	org.openhab.core.automation.type.TriggerType
Visibility	org.openhab.core.automation.Visibility enum

RuleSupport Preset

These variables and classes are loaded using:

scriptExtension.importPreset("RuleSupport")

Variable	Description
Action	org.openhab.core.automation.Action
ActionBuilder	org.openhab.core.automation.ActionBuilder
Condition	org.openhab.core.automation.Condition
ConditionBuilder	org.openhab.core.automation.ConditionBuilder
Configuration	org.eclipse.smarthome.config.core.Configuration
ModuleBuilder	org.openhab.core.automation.ModuleBuilder
Rule	org.openhab.core.automation.Rule (use SimpleRule for defining rules)
Trigger	org.openhab.core.automation.Trigger
TriggerBuilder	org.openhab.core.automation.TriggerBuilder
automationManager	Instance for managing rules and other openHAB module instances. (e.g., addRule)
ruleRegistry	org.openhab.core.automation.Rule

RuleFactories Preset

Note: Advanced usage

scriptExtension.importPreset("RuleFactories")

Variable	Description
ActionHandlerFactory	org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedActionHandlerFactory
ConditionHandlerFactory	org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedConditionHandlerFactory
TriggerHandlerFactory	org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory

TriggerType Objects (all JSR223 languages)

The following trigger types are defined by openHAB (custom triggers can also be defined) and take the specified configuration parameters. All parameters are Strings. Read the JSR223 language specific documentation for examples of using these TriggerType objects.

timer.GenericCronTrigger

Parameter	Description
cronExpression	The cron expression

timer.TimeOfDayTrigger

Parameter	Description
time	The time in "hh:mm" format

core.ItemCommandTrigger

Parameter	Description
itemName	The name of the Item
command	The Command (optional)

core.ItemStateUpdateTrigger

Parameter	Description
itemName	The name of the Item
state	The State (optional)

core.ItemStateChangeTrigger

Parameter	Description
itemName	The name of the Item
previousState	The previous State (optional)
state	The State (optional)

core.ChannelEventTrigger

Parameter	Description
channelUID	The ChannelUID of the Channel
event	The Channel trigger Event (optional)

core.GenericEventTrigger

Parameter	Description
eventTopic	Default: "smarthome/*" Events can also be filtered, e.g. Item events: "smarthome/items/*/" Channel events: "smarthome/channels/*/triggered" Thing events: "smarthome/things/*/"
eventSource	Item name, ChannelUID, ThingUID, etc.
eventTypes	ItemCommandEvent, ItemStateEvent, ItemStateChangedEvent, GroupItemStateChangedEvent, ItemAddedEvent, ItemRemovedEvent, ThingAddedEvent, ThingRemovedEvent, ThingStatusInfoChangedEvent, ThingStatusInfoEvent, ThingUpdatedEvent, etc.

Additional Information

• Scripted Rule Support (opens new window) - Early documentation on JSR223 usage in openHAB 2, including IDE setup instructions

• Stable
• Latest

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub (opens new window)