Added warning and small updates (#927)
I did some tidying up, corrected some of the classes that changed due to the ESH reintegration, and added a warning about using anything other than the official APIs (requested here... https://github.com/openhab/openhab-core/pull/663#issuecomment-478233196). Signed-off-by: Scott Rushworth <openhab@5iver.com>pull/935/head
Scott Rushworth
Jerome Luckenbach
parent
a973dbedec
commit
76c8f08c35
|
|
@ -13,103 +13,63 @@ title: JSR223 Scripting
|
|||
|
||||
## 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).
|
||||
[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
|
||||
[**Jython**](https://jython.github.io/) (Python on the JVM),
|
||||
[**Nashorn Javascript**](http://www.oracle.com/technetwork/articles/java/jf14-nashorn-2126515.html) (ECMAScript implementation included in JDK8 through 10, [deprecated in 11](https://openjdk.java.net/jeps/335)), 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.
|
||||
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
|
||||
|
||||
- [Javascript](jsr223-js.html)
|
||||
- [Jython](jsr223-jython.html)
|
||||
- [Javascript](jsr223-js.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`.
|
||||
Scripts should be placed in the `${OPENHAB_CONF}/automation/jsr223/` directory.
|
||||
This directory will vary, [based on the type of openHAB installation used](https://www.openhab.org/docs/installation/linux.html#installation).
|
||||
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/`.
|
||||
|
||||
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...
|
||||
When openHAB starts, scripts will be loaded in an order based on their file name and path.
|
||||
For example, with the following scripts and directory structure...
|
||||
|
||||
```text
|
||||
automation/jsr223
|
||||
01/
|
||||
script1.py
|
||||
scriptx.py
|
||||
00script.py
|
||||
script2.py
|
||||
├── automation/jsr223
|
||||
│ ├── 00
|
||||
│ │ ├── 00_00.py
|
||||
│ │ └── 01_00.py
|
||||
│ ├── 00.py
|
||||
│ ├── 01
|
||||
│ │ ├── 00_01.py
|
||||
│ │ └── 01_01.py
|
||||
│ └── 01.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.
|
||||
... the load order will be: `00.py`, `00/00_00.py`, `00/01_00.py`, `01.py`, `01/00_01.py`, `01/01_01.py`.
|
||||
|
||||
<a name="presets"></a>
|
||||
|
||||
### Predefined Script Variables (all JSR223 languages)
|
||||
### `ScriptExtension` Objects (all JSR223 languages)
|
||||
|
||||
To faciliate JSR223 scripting, several openHAB-related variables are automatically predefined. These presets include:
|
||||
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](#default_presets)
|
||||
- [`Default`](#default_presets)
|
||||
- [`RuleSimple`](#rulesimple_presets)
|
||||
- [`RuleSupport`](#rulesupport_presets)
|
||||
- [`RuleFactories`](#rulefactories_presets)
|
||||
|
||||
<a name="default_presets"></a>
|
||||
|
||||
#### Default Variables (no preset loading required)
|
||||
#### Default Preset (`importPreset` not required)
|
||||
|
||||
| Variable | Description |
|
||||
|---------|-------------|
|
||||
|
|
@ -161,29 +121,29 @@ To faciliate JSR223 scripting, several openHAB-related variables are automatical
|
|||
| `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` |
|
||||
| `events` | (internal) Used to send events, post commands, etc. [Details](#event_operations) below] |
|
||||
|
||||
<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>)`
|
||||
- `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>)`
|
||||
|
||||
<a name="rulesimple_presets"></a>
|
||||
|
||||
#### RuleSimple Extension/Preset
|
||||
#### RuleSimple Preset
|
||||
|
||||
These variables are loaded using:
|
||||
|
||||
|
|
@ -197,18 +157,18 @@ 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` |
|
||||
| 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.eclipse.smarthome.automation.type.ModuleType` |
|
||||
| ActionType | `org.eclipse.smarthome.automation.type.ActionType` |
|
||||
| Visibility | `org.eclipse.smarthome.automation.Visibility` enum |
|
||||
| ModuleType | `org.openhab.core.automation.type.ModuleType` |
|
||||
| ActionType | `org.openhab.core.automation.type.ActionType` |
|
||||
| Visibility | `org.openhab.core.automation.Visibility` enum |
|
||||
|
||||
<a name="rulesupport_presets"></a>
|
||||
|
||||
#### RuleSupport Extension/Preset
|
||||
#### `RuleSupport` Preset
|
||||
|
||||
These variables are loaded using:
|
||||
|
||||
|
|
@ -220,14 +180,14 @@ scriptExtension.importPreset("RuleSupport")
|
|||
|----------|-------------|
|
||||
| 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) |
|
||||
| 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) |
|
||||
|
||||
<a name="rulefactories_presets"></a>
|
||||
|
||||
#### RuleFactories Extension
|
||||
#### `RuleFactories` Preset
|
||||
|
||||
> NOTE: Advanced usage
|
||||
|
||||
|
|
@ -237,11 +197,88 @@ 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` |
|
||||
| `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.eclipse.smarthome.automation.type.ModuleType` |
|
||||
| `ActionType` | `org.eclipse.smarthome.automation.type.ActionType` |
|
||||
| `Visibility` | `org.eclipse.smarthome.automation.Visibility` enum |
|
||||
| `ModuleType` | `org.openhab.core.automation.type.ModuleType` |
|
||||
| `ActionType` | `org.openhab.core.automation.type.ActionType` |
|
||||
| `Visibility` | `org.openhab.core.automation.Visibility` enum |
|
||||
|
||||
|
||||
<a name="trigger_types"></a>
|
||||
|
||||
### `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.
|
||||
|
||||
<details>
|
||||
<summary>timer.GenericCronTrigger</summary>
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `cronExpression` | The cron expression |
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>timer.TimeOfDayTrigger</summary>
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `time` | The time in "hh:mm" format |
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>core.ItemCommandTrigger</summary>
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `itemName` | The name of the `Item` |
|
||||
| `command` | The `Command` (optional) |
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>core.ItemStateUpdateTrigger</summary>
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `itemName` | The name of the `Item` |
|
||||
| `state` | The `State` (optional) |
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>core.ItemStateChangeTrigger</summary>
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `itemName` | The name of the `Item` |
|
||||
| `previousState` | The previous `State` (optional) |
|
||||
| `state` | The `State` (optional) |
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>core.ChannelEventTrigger</summary>
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `channelUID` | The `ChannelUID` of the `Channel` |
|
||||
| `event` | The `Channel` trigger `Event` (optional) |
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>core.GenericEventTrigger</summary>
|
||||
|
||||
| Parameter | Description |
|
||||
|-----------|-------------|
|
||||
| `eventTopic` | Default: "smarthome/\*"<br><br>Events can also be filtered, e.g.<br>Item events: "smarthome/items/\*/"<br>Channel events: "smarthome/channels/\*/triggered"<br>Thing events: "smarthome/things/\*/" |
|
||||
| `eventSource` | `Item` name, `ChannelUID`, `ThingUID`, etc. |
|
||||
| `eventTypes` | `ItemCommandEvent`, `ItemStateEvent`, `ItemStateChangedEvent`, `GroupItemStateChangedEvent`, `ItemAddedEvent`, `ItemRemovedEvent`, `ThingAddedEvent`, `ThingRemovedEvent`, `ThingStatusInfoChangedEvent`, `ThingStatusInfoEvent`, `ThingUpdatedEvent`, etc. |
|
||||
</details>
|
||||
|
||||
### Additional Information
|
||||
|
||||
- [Scripted Rule Support](https://github.com/eclipse/smarthome/wiki/Scripted-Rule-Support) -
|
||||
Early documentation on JSR223 usage in openHAB 2, including IDE setup instructions
|
||||
|
|
|
|||
Loading…
Reference in New Issue