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

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