---
layout: documentation
title: JSR223 Scripting
---

{% include base.html %}

# 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](https://docs.oracle.com/javase/6/docs/technotes/guides/scripting/) ([spec](https://jcp.org/aboutJava/communityprocess/pr/jsr223/index.html)) 
is a standard scripting API for Java Virtual Machine (JVM) 
[languages](https://en.wikipedia.org/wiki/List_of_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: 
[**Oracle Nashorn**](http://www.oracle.com/technetwork/articles/java/jf14-nashorn-2126515.html) (Javascript bundled with Java),
[**Jython**](http://www.jython.org/) (Python on the JVM) and
[**Apache Groovy**](http://www.groovy-lang.org/) (JVM scripting language).

Although JSR223 scripts can be used as a general-purpose extension language for openHAB, 
the most common usage will be for defining openHAB rules.

### Language-Specific Documentation

- [Javascript](jsr223-js.html)
- [Jython](jsr223-jython.html)
- Groovy (TODO)

### Script Locations

Scripts should be placed in the 'USERDATA/automation/jsr223' directory. For example, 
in Linux installations created with a package installer, 
the directory would be `/etc/openhab2/automation/jsr223`.

At system start time the scripts will be loaded in an order based on their name 
and then top-down through the directory hierarchy. 
Note that while scripts may be placed in subdirectories of `jsr223`, 
they should not have the same names as scripts in other directories (this may be changed in the future). 
For example, with the following directory structure...

```text
automation/jsr223
  01/
    script1.py
    scriptx.py
  00script.py
  script2.py
```

the load order will be: `00script.py`, `01/script1.py`, `script2.py`, `01/scriptx.py`.

<a name="trigger_types"></a>

### Trigger Types (all JSR223 languages)

The following trigger types are defined by openHAB (custom triggers can also be defined)
and take the specified configuration parameters.

| Trigger: `core.ItemCommandTrigger` |
|-----------------------------|
| `itemName` | The item name | TEXT |
| `command` | The command | TEXT |

| Trigger: `core.ItemStateUpdateTrigger` |
|-----------------------------|
| `itemName` | The item name | TEXT |
| `state` | The state | TEXT |

| Trigger: `core.ItemStateChangeTrigger` |
|-----------------------------|
| `itemName` | The item name | TEXT |
| `previousState` | The previous state | TEXT |
| `state` | The state | TEXT |

| Trigger: `timer.GenericCronTrigger` |
|-----------------------------|
| `cronExpression` | The cron expression | TEXT |

| Trigger: `timer.TimeOfDayTrigger` |
|-----------------------------|
| `time` | The time in "hh:mm" format | TEXT |

| Trigger: `core.GenericEventTrigger` |
|-----------------------------|
| `eventTopic` | default: "smarthome/*" (for channel events: "smarthome/channels/*/triggered") | TEXT |
| `eventSource` | item name, channel UID | TEXT |
| `eventTypes` | ItemCommandEvent, ItemStateEvent | TEXT |

### Additional Information

- [Scripted Rule Support](https://github.com/eclipse/smarthome/wiki/Scripted-Rule-Support) - 
    Early documentation on JSR223 usage in openHAB 2. Includes IDE setup instructions.

<a name="presets"></a>

### Predefined Script Variables (all JSR223 languages)

To faciliate JSR223 scripting, several openHAB-related variables are automatically predefined. These presets include:

- [Default](#default_presets)
- [`RuleSimple`](#rulesimple_presets)
- [`RuleSupport`](#rulesupport_presets)
- [`RuleFactories`](#rulefactories_presets)

<a name="default_presets"></a>

#### Default Variables (no preset loading 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&lt;String, State&gt;` | 
| `itemRegistry` | Instance of `org.eclipse.smarthome.core.items.ItemRegistry` |
| `ir` | Alias for `itemRegistry` |
| `things` | Instance of `org.eclipse.smarthome.core.thing.ThingRegistry` |
| `events` | (internal) Used to send events, post commands, etc. [Details](#event_operations) below] |
| `rules` | Instance of `org.eclipse.smarthome.automation.RuleRegistry` |
| `scriptExtension` | (internal) For loading script presets. |
| `se` | Alias for `scriptExtension` |

<a name="#event_operations"></a>

##### `events` operations

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

<a name="rulesimple_presets"></a>

#### RuleSimple Extension/Preset

These variables are loaded using:

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

<a name="rulesupport_presets"></a>

#### RuleSupport Extension/Preset

These variables are loaded using:

```python
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.eclipse.smarthome.config.core.Action` | 
| Condition | `org.eclipse.smarthome.config.core.Condition` | 
| Trigger | `org.eclipse.smarthome.config.core.Trigger` |
| Rule | `org.eclipse.smarthome.config.core.Action.Rule` (use `SimpleRule` for defining rules) | 

<a name="rulefactories_presets"></a>

#### RuleFactories Extension

> NOTE: Advanced usage

```python
scriptExtension.importPreset("RuleFactories")
```

| Variable | Description |
|----------|-------------|
| `ActionHandlerFactory` | `org.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.ActionHandlerFactory` |
| `ConditionHandlerFactory` | `org.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.ConditionHandlerFactory` | 
| `TriggerHandlerFactory` | `org.eclipse.smarthome.automation.module.script.rulesupport.shared.factories.TriggerHandlerFactory` | 
| `TriggerType` | `org.eclipse.smarthome.automation.type.TriggerType` |
| `ConfigDescriptionParameter` | `org.eclipse.smarthome.config.core.ConfigDescriptionParameter` | 
| `ModuleType` | `org.eclipse.smarthome.automation.type.ModuleType` | 
| `ActionType` | `org.eclipse.smarthome.automation.type.ActionType` | 
| `Visibility` | `org.eclipse.smarthome.automation.Visibility` enum |