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.


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

Example rules for a first impression

    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.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:


    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:

    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

    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.

    Parameter Description
    cronExpression The cron expression
    Parameter Description
    time The time in "hh:mm" format
    Parameter Description
    itemName The name of the Item
    command The Command (optional)
    Parameter Description
    itemName The name of the Item
    state The State (optional)
    Parameter Description
    itemName The name of the Item
    previousState The previous State (optional)
    state The State (optional)
    Parameter Description
    channelUID The ChannelUID of the Channel
    event The Channel trigger Event (optional)
    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