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

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 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.eclipse.smarthome.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.ActionHandlerFactory
ConditionHandlerFactory org.openhab.core.automation.module.script.rulesupport.shared.factories.ConditionHandlerFactory
TriggerHandlerFactory org.openhab.core.automation.module.script.rulesupport.shared.factories.TriggerHandlerFactory
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