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: Jython (Python on the JVM), Nashorn Javascript (ECMAScript implementation included in JDK8 through 10, deprecated in 11), and Apache Groovy (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. 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
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
rules	Instance of org.openhab.core.automation.RuleRegistry
scriptExtension	(internal) For loading script presets.
se	Alias for scriptExtension
events	(internal) Used to send events, post commands, etc. Details below]

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 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.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleActionHandler
SimpleConditionHandler	org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleConditionHandler
SimpleTriggerHandler	org.openhab.core.automation.module.script.rulesupport.shared.simple.SimpleTriggerHandler
TriggerType	org.openhab.core.automation.type.TriggerType
ConfigDescriptionParameter	org.eclipse.smarthome.config.core.ConfigDescriptionParameter
ModuleType	org.openhab.core.automation.type.ModuleType
ActionType	org.openhab.core.automation.type.ActionType
Visibility	org.openhab.core.automation.Visibility enum

RuleSupport 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.openhab.core.automation.Action
Condition	org.openhab.core.automation.Condition
Trigger	org.openhab.core.automation.Trigger
Rule	org.openhab.core.automation.Rule (use SimpleRule for defining rules)

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	org.openhab.core.automation.type.TriggerType
ConfigDescriptionParameter	org.eclipse.smarthome.config.core.ConfigDescriptionParameter
ModuleType	org.openhab.core.automation.type.ModuleType
ActionType	org.openhab.core.automation.type.ActionType
Visibility	org.openhab.core.automation.Visibility enum

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 - Early documentation on JSR223 usage in openHAB 2, including IDE setup instructions

Caught a mistake or want to contribute to the documentation? Edit this page on GitHub