From 84eb97acd0050f1786fbf896cf72f4154d402787 Mon Sep 17 00:00:00 2001 From: jimtng <2554958+jimtng@users.noreply.github.com> Date: Thu, 22 Feb 2024 18:30:20 +1000 Subject: [PATCH] [jrubyscripting] Update README (#16440) Signed-off-by: Jimmy Tanagra --- .../README.md | 39 +++++++++++++++---- 1 file changed, 31 insertions(+), 8 deletions(-) diff --git a/bundles/org.openhab.automation.jrubyscripting/README.md b/bundles/org.openhab.automation.jrubyscripting/README.md index e6b1145b65e..91636e0b8e3 100644 --- a/bundles/org.openhab.automation.jrubyscripting/README.md +++ b/bundles/org.openhab.automation.jrubyscripting/README.md @@ -60,6 +60,7 @@ If you're new to Ruby, you may want to check out [Ruby Basics](https://openhab.g - [Terse Rules](#terse-rules) - [Early Exit From a Rule](#early-exit-from-a-rule) - [Dynamic Generation of Rules](#dynamic-generation-of-rules) + - [Scenes and Scripts](#scenes-and-scripts) - [Hooks](#hooks) - [Calling Java From JRuby](#calling-java-from-jruby) - [Full Documentation](#full-documentation) @@ -99,7 +100,7 @@ Additional [example rules are available](https://openhab.github.io/openhab-jruby 1. Go to `Settings -> Add-ons -> Automation` and install the jrubyscripting automation addon following the [openHAB instructions](https://www.openhab.org/docs/configuration/addons.html). In openHAB 4.0+ the defaults are set so the next step can be skipped. -1. Go to `Settings -> Other Services -> JRuby Scripting`: +1. Go to `Settings -> Add-on Settings -> JRuby Scripting`: - **Ruby Gems**: `openhab-scripting=~>5.0` - **Require Scripts**: `openhab/dsl` (not required, but recommended) @@ -118,7 +119,7 @@ Additional [example rules are available](https://openhab.github.io/openhab-jruby ## Configuration -After installing this add-on, you will find configuration options in the openHAB portal under _Settings -> Other Services -> JRuby Scripting_. +After installing this add-on, you will find configuration options in the openHAB portal under _Settings -> Add-on Settings -> JRuby Scripting_. Alternatively, JRuby configuration parameters may be set by creating a `jruby.cfg` file in `conf/services/`. By default this add-on includes the [openhab-scripting](https://github.com/openhab/openhab-jruby) Ruby gem and automatically `require`s it. @@ -262,12 +263,13 @@ When you use "Item event" as trigger (i.e. "[item] received a command", "[item] This tables gives an overview of the `event` object for most common trigger types. For full details, explore [OpenHAB::Core::Events](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Events.html). -| Property Name | Type | Trigger Types | Description | Rules DSL Equivalent | -| ------------- | -------------------------------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------- | ---------------------- | -| `state` | [State](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/State.html) or `nil` | `[item] changed`, `[item] was updated` | State that triggered event | `triggeringItem.state` | -| `was` | [State](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/State.html) or `nil` | `[item] changed` | Previous state of Item or Group that triggered event | `previousState` | -| `command` | [Command](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/Command.html) | `[item] received a command` | Command that triggered event | `receivedCommand` | -| `item` | [Item](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Item.html) | all | Item that triggered event | `triggeringItem` | +| Property Name | Type | Trigger Types | Description | Rules DSL Equivalent | +| ------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------- | +| `state` | [State](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/State.html) or `nil` | `[item] changed`, `[item] was updated` | State that triggered event | `triggeringItem.state` | +| `was` | [State](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/State.html) or `nil` | `[item] changed` | Previous state of Item or Group that triggered event | `previousState` | +| `command` | [Command](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Types/Command.html) | `[item] received a command` | Command that triggered event | `receivedCommand` | +| `item` | [Item](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Item.html) | All item related triggers | Item that triggered event | `triggeringItem` | +| `group` | [GroupItem](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/Items/Item.html) | `Member of [group] changed`, `Member of [group] was updated`, `Member of [group] received a command` | Group whose member triggered the event | `triggeringGroup` | ```ruby logger.info(event.state == ON) @@ -473,6 +475,9 @@ My_Item.ensure << ON logger.info("Turning off the light") if My_Item.ensure.off ``` +See [ensure_states](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#ensure_states-class_method), [ensure_states!](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#ensure_states!-class_method), +[ensure](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Items/Ensure/Ensurable.html#ensure-instance_method). + ##### Timed Commands A [Timed Command](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL/Items/TimedCommand.html) is similar to the openHAB Item's [expire parameter](https://www.openhab.org/docs/configuration/items.html#parameter-expire) but it offers more flexibility. @@ -1740,6 +1745,24 @@ virtual_switches.each do |switch| end ``` +### Scenes and Scripts + +A `scene` can be created using the [.scene](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#scene-class_method) method. + +```ruby +scene "Movie", id: "movie", description: "Set up the theatre for movie watching" do + Theatre_Window_Blinds.down + Theatre_Screen_Curtain.up + Theatre_Mood_Light.on + Theatre_Light.off + Theatre_Projector.on + Theatre_Receiver.on +end +``` + +To create a `script`, use the [.script](https://openhab.github.io/openhab-jruby/main/OpenHAB/DSL.html#script-class_method) method. +Note that scripts can be executed with additional contexts. + ### Hooks File based scripts can also register [hooks](https://openhab.github.io/openhab-jruby/main/OpenHAB/Core/ScriptHandling.html) that will be called when the script has completed loading (`script_loaded`) and when it gets unloaded (`script_unloaded`).