openhab-scripting 2.9.1

data/docs/usage/misc/store_states.md

@@ -0,0 +1,42 @@
+---
+layout: default
+title: Store States
+nav_order: 6
+has_children: false
+parent: Misc
+grand_parent: Usage
+---
+
+### store_states
+
+store_states takes one or more items or groups and returns a map `{Item => State}` with the current state of each item. It is implemented by calling OpenHAB's [events.storeStates()](https://www.openhab.org/docs/configuration/actions.html#event-bus-actions).
+
+```ruby
+states = store_states Item1, Item2 
+...
+states.restore
+```
+
+or in a block context:
+```ruby
+store_states Item1, Item2 do
+...
+end # the states will be restored here
+```
+
+It can take an array of items:
+```ruby
+items_to_store = [ Item1, Item2 ]
+states = store_states items_to_store
+...
+states.restore_changes # restore only changed items
+```
+
+
+The returned states variable is a hash that supports some additional methods:
+
+| method          | description                                                                              |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| restore         | Restores the states of all the stored items by calling events.restoreStates() internally |
+| changed?        | Returns true if any of the stored items had changed states                               |
+| restore_changes | restores only items whose state had changed    

data/docs/usage/misc/time_of_day.md

@@ -0,0 +1,69 @@
+---
+layout: default
+title: TimeOfDay
+nav_order: 5
+has_children: false
+parent: Misc
+grand_parent: Usage
+---
+
+# TimeOfDay
+
+TimeOfDay class can be used in rules for time related logic. Methods:
+
+| Method      | Parameter      | Description                                                                                                                                             | Example                                                                                                                                                      |
+| ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| parse       | String         | Creates a TimeOfDay object with a given time string. The format is hh[:mm[:ss]][am\|pm]. When am/pm is not specified, the time should be in 24h format. | curfew_start = TimeOfDay.parse '19:30' => 19:30<br/>TimeOfDay.parse '2pm' => 14:00<br/> TimeOfDay.parse '12:30am' => 00:30<br/>TimeOfDay.parse '15' => 15:00 |
+| now         |                | Creates a TimeOfDay object that represents the current time                                                                                             | TimeOfDay.now > curfew_start, or TimeOfDay.now > '19:30'                                                                                                     |
+| MIDNIGHT    |                | Creates a TimeOfDay object for 00:00                                                                                                                    | TimeOfDay.MIDNIGHT                                                                                                                                           |
+| NOON        |                | Creates a TimeOfDay object for 12:00                                                                                                                    | TimeOfDay.now < TimeOfDay.NOON                                                                                                                               |
+| constructor | h, m, s        | Creates a TimeOfDay with the given hour, minute, second                                                                                                 | TimeOfDay.new(h: 17, m: 30, s: 0)                                                                                                                            |
+| hour        |                | Returns the hour part of the object                                                                                                                     | TimeOfDay.now.hour                                                                                                                                           |
+| minute      |                | Returns the minute part of the object                                                                                                                   | TimeOfDay.now.minute                                                                                                                                         |
+| second      |                | Returns the second part of the object                                                                                                                   | TimeOfDay.now.second                                                                                                                                         |
+| between?    | TimeOfDayRange | Returns true if it falls within the given time range                                                                                                    | TimeOfDay.now.between? '3pm'..'7pm'                                                                                                                          |
+
+
+A TimeOfDay object can be compared against another TimeOfDay object or a parseable string representation of time.
+
+Note: the following global constants are available:
+| Name     | Description |
+| -------- | ----------- |
+| MIDNIGHT | 00:00       |
+| NOON     | 12:00       |
+
+
+## Examples
+
+```ruby
+#Create a TimeOfDay object
+break_time = NOON
+
+if TimeOfDay.now > TimeOfDay.new(h: 17, m: 30, s: 0) # comparing two TimeOfDay objects
+  # do something
+elsif TimeOfDay.now < '8:30' # comparison against a string
+  #do something
+end
+four_pm = TimeOfDay.parse '16:00'
+```
+
+## between
+ 
+ `between` creates a TimeOfDay range that can be used to check if another Time, TimeOfDay, or [TimeOfDay parsable string](#TimeOfDay) is within that range. 
+ 
+ ```ruby
+ logger.info("Within time range") if between('10:00'..'14:00').cover? Time.now
+ logger.info("Within time range") if between('10:00'..'14:00').include? TimeOfDay.now
+ 
+case Time.now
+
+when between('6:00'...'12:00')
+  logger.info("Morning Time")
+when between('12:00'..'15:00')
+  logger.info("Afternoon")
+else
+  logger.info("Not in time range")
+end  
+ ```
+ 
+ 

data/docs/usage/misc/timers.md

@@ -0,0 +1,67 @@
+---
+layout: default
+title: Timers
+nav_order: 4
+has_children: false
+parent: Misc
+grand_parent: Usage
+---
+
+# Timers
+Timers are created using the `after` method. 
+
+After method parameters
+
+| Parameter | Description                                                        |
+| --------- | ------------------------------------------------------------------ |
+| duration  | Duration for timer                                                 |
+| block     | Block to execute after duration, block will be passed timer object |
+
+Timer Object
+The timer object has all of the methods of the [OpenHAB Timer](https://www.openhab.org/docs/configuration/actions.html#timers) with a change to the reschedule method to enable it to operate Ruby context. The following methods are available to a Timer object:
+
+| Method        | Parameter | Description                                                                                      |
+| ------------- | --------- | ------------------------------------------------------------------------------------------------ |
+| `cancel`      |           | Cancel the scheduled timer                                                                       |
+| `reschedule`  | duration  | Optional [duration](#Duration) if unspecified original duration supplied to after method is used |
+| `active?`     |           | An alias for `Timer::isActive()`                                                                 |
+| `running?`    |           | An alias for `Timer::isRunning()`                                                                |
+| `terminated?` |           | An alias for `Timer::hasTerminated()`                                                            |
+
+```ruby
+after 5.seconds do
+  logger.info("Timer Fired")
+end
+```
+
+```ruby
+# Timers delegate methods to OpenHAB timer objects
+after 1.second do |timer|
+  logger.info("Timer is active? #{timer.is_active}")
+end
+```
+
+```ruby
+# Timers can be rescheduled to run again, waiting the original duration
+after 3.seconds do |timer|
+  logger.info("Timer Fired")
+  timer.reschedule
+end
+```
+
+```ruby
+# Timers can be rescheduled for different durations
+after 3.seconds do |timer|
+  logger.info("Timer Fired")
+  timer.reschedule 5.seconds
+end
+```
+
+```ruby
+# Timers can be manipulated through the returned object
+mytimer = after 1.minute do
+  logger.info('It has been 1 minute')
+end
+
+mytimer.cancel
+```

data/docs/usage/rule.md

@@ -0,0 +1,43 @@
+---
+layout: default
+title: Rules
+nav_order: 1
+has_children: false
+parent: Usage
+---
+
+
+##  Rule Syntax
+```ruby
+require 'openhab'
+
+rule 'name' do
+   <zero or more triggers>
+   <zero or more execution blocks>
+   <zero or more guards>
+end
+```
+
+### All of the properties that are available to the rule resource are
+
+| Property         | Type                                                                    | Last/Multiple | Options                               | Default | Description                                                                 | Examples                                                                                                                                                                                                              |
+| ---------------- | ----------------------------------------------------------------------- | ------------- | ------------------------------------- | ------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| description      | String                                                                  | Single        |                                       |         | Set the rule description                                                    |                                                                                                                                                                                                                       |
+| every            | Symbol or Duration                                                      | Multiple      | at: String or TimeOfDay               |         | When to execute rule                                                        | Symbol (:second, :minute, :hour, :day, :week, :month, :year, :monday, :tuesday, :wednesday, :thursday, :friday, :saturday, :sunday) or duration (5.minutes, 20.seconds, 14.hours), at: '5:15' or TimeOfDay(h:5, m:15) |
+| cron             | String                                                                  | Multiple      |                                       |         | OpenHAB Style Cron Expression                                               | '* * * * * * ?'                                                                                                                                                                                                       |
+| changed          | Item or Item Array[] or Group or Group.items or Thing or Thing Array [] | Multiple      | from: State, to: State, for: Duration |         | Execute rule on item state change                                           | BedroomLightSwitch, from: OFF to ON                                                                                                                                                                                   |
+| updated          | Item or Item Array[] or Group or Group.items or Thing or Thing Array [] | Multiple      | to: State                             |         | Execute rule on item update                                                 | BedroomLightSwitch, to: ON                                                                                                                                                                                            |
+| received_command | Item or Item Array[] or Group or Group.items                            | Multiple      | command:                              |         | Execute rule on item command                                                | BedroomLightSwitch command: ON                                                                                                                                                                                        |
+| channel          | Channel                                                                 | Multiple      | triggered:                            |         | Execute rule on channel trigger                                             | `'astro:sun:home:rise#event', triggered: 'START'`                                                                                                                                                                     |
+| on_start         | Boolean                                                                 | Single        |                                       | false   | Execute rule on system start                                                | on_start                                                                                                                                                                                                              |
+| run              | Block passed event                                                      | Multiple      |                                       |         | Code to execute on rule trigger                                             |                                                                                                                                                                                                                       |
+| triggered        | Block passed item                                                       | Multiple      |                                       |         | Code with triggering item to execute on rule trigger                        |                                                                                                                                                                                                                       |
+| delay            | Duration                                                                | Multiple      |                                       |         | Duration to wait between or after run blocks                                | delay 5.seconds                                                                                                                                                                                                       |
+| otherwise        | Block passed event                                                      | Multiple      |                                       |         | Code to execute on rule trigger if guards are not satisfied                 |                                                                                                                                                                                                                       |
+| between          | Range of TimeOfDay or String Objects                                    | Single        |                                       |         | Only execute rule if current time is between supplied time ranges           | '6:05'..'14:05:05' (Include end) or '6:05'...'14:05:05' (Excludes end second) or TimeOfDay.new(h:6,m:5)..TimeOfDay.new(h:14,m:15,s:5)                                                                                 |
+| only_if          | Item or Item Array, or Block                                            | Multiple      |                                       |         | Only execute rule if all supplied items are "On" and/or block returns true  | BedroomLightSwitch, BackyardLightSwitch or {BedroomLightSwitch.state == ON}                                                                                                                                           |
+| not_if           | Item or Item Array, or Block                                            | Multiple      |                                       |         | Do **NOT** execute rule if any of the supplied items or blocks returns true | BedroomLightSwitch                                                                                                                                                                                                    |
+| enabled          | Boolean                                                                 | Single        |                                       | true    | Enable or disable the rule from executing                                   |                                                                                                                                                                                                                       |
+
+Last means that last value for the property is used <br>
+Multiple indicates that multiple entries of the same property can be used in aggregate 

data/docs/usage/things.md

@@ -0,0 +1,29 @@
+---
+layout: default
+title: Things
+nav_order: 5
+has_children: false
+parent: Usage
+has_toc: false
+---
+
+# Things
+
+Things can be access using the `things` method and subsequent operations on that methods. 
+
+| Method             | Description                                                         |
+| ------------------ | ------------------------------------------------------------------- |
+| things             | Return all things as a Ruby Set                                     |
+| []                 | Get a specific thing by name                                        |
+| enumerable methods | All methods [here](https://ruby-doc.org/core-2.5.0/Enumerable.html) |
+
+```ruby
+things.each { |thing| logger.info("Thing: #{thing.uid}")}
+```
+
+```ruby
+logger.info("Thing: #{things['astro:sun:home'].uid}")
+```
+
+For thing objects now additional methods are provided, however the standard [JRuby alternate names and bean convention applies](https://github.com/jruby/jruby/wiki/CallingJavaFromJRuby#alternative-names-and-beans-convention), such that `getUID` becomes `uid`.
+

data/docs/usage/triggers.md

@@ -0,0 +1,8 @@
+---
+layout: default
+title: Triggers
+nav_order: 1
+has_children: true
+parent: Usage
+---
+

data/docs/usage/triggers/changed.md

@@ -0,0 +1,57 @@
+---
+layout: default
+title: Changed
+nav_order: 3
+has_children: false
+parent: Triggers
+grand_parent: Usage
+---
+
+
+# Changed
+
+
+| Options | Description                                            | Example         |
+| ------- | ------------------------------------------------------ | --------------- |
+| from    | Only execute rule if previous state matches from state | from: OFF       |
+| to      | Only execute rule if new state matches from state      | to: ON          |
+| for     | Only execute rule if value stays changed for duration  | for: 10.seconds |
+
+Changed accepts Items, Things or Groups. 
+
+The from and to values operate exactly as they do in the DSL and Python rules with the exception of operating on Things.  If changed element being used as a trigger is a thing than the to and from values will accept symbols and strings, where the symbol matches the [supported status](https://www.openhab.org/docs/concepts/things.html). 
+
+The for parameter provides a method of only executing the rule if the value is changed for a specific duration.  This provides a built-in method of only executing a rule if a condition is true for a period of time without the need to create dummy objects with the expire binding or make or manage your own timers.
+
+For example, the code in [this design pattern](https://community.openhab.org/t/design-pattern-expire-binding-based-timers/32634) becomes (with no need to create the dummy object):
+```ruby
+rule "Execute rule when item is changed for specified duration" do
+  changed Alarm_Mode, for: 20.seconds
+  run { logger.info("Alarm Mode Updated")}
+end
+```
+
+You can optionally provide from and to states to restrict the cases in which the rule executes:
+```ruby
+rule 'Execute rule when item is changed to specific number, from specific number, for specified duration' do
+  changed Alarm_Mode, from: 8, to: 14, for: 12.seconds
+  run { logger.info("Alarm Mode Updated")}
+end
+```
+
+Works with things as well:
+```ruby
+rule 'Execute rule when thing is changed' do
+   changed things['astro:sun:home'], :from => :online, :to => :uninitialized
+   run { |event| logger.info("Thing #{event.uid} status <trigger> to #{event.status}") }
+end
+```
+
+
+Real world example:
+```ruby
+rule 'Log (or notify) when an exterior door is left open for more than 5 minutes' do
+  changed ExteriorDoors, to: OPEN, for: 5.minutes
+  triggered {|door| logger.info("#{door.id} has been left open!")}
+end
+```

data/docs/usage/triggers/channel.md

@@ -0,0 +1,54 @@
+---
+layout: default
+title: Channel
+nav_order: 6
+has_children: false
+parent: Triggers
+grand_parent: Usage
+---
+
+# channel
+
+| Option    | Description                                                                   | Example                                                |
+| --------- | ----------------------------------------------------------------------------- | ------------------------------------------------------ |
+| triggered | Only execute rule if the event on the channel matches this/these event/events | `triggered: 'START' ` or `triggered: ['START','STOP']` |
+| thing     | Thing for specified channels                                                  | `thing: 'astro:sun:home'`                              |
+
+The channel trigger executes rule when a specific channel is triggered.  The syntax supports one or more channels with one or more triggers.   For `thing` is an optional parameter that makes it easier to set triggers on multiple channels on the same thing.
+
+
+```ruby
+rule 'Execute rule when channel is triggered' do
+  channel 'astro:sun:home:rise#event'      
+  run { logger.info("Channel triggered") }
+end
+
+# The above is the same as the below
+
+rule 'Execute rule when channel is triggered' do
+  channel 'rise#event', thing: 'astro:sun:home'   
+  run { logger.info("Channel triggered") }
+end
+
+```
+
+```ruby
+rule 'Rule provides access to channel trigger events in run block' do
+  channel 'astro:sun:home:rise#event', triggered: 'START'
+  run { |trigger| logger.info("Channel(#{trigger.channel}) triggered event: #{trigger.event}") }
+end
+```
+
+```ruby
+rule 'Rules support multiple channels' do
+  channel ['rise#event','set#event'], thing: 'astro:sun:home' 
+  run { logger.info("Channel triggered") }
+end
+```
+
+```ruby
+rule 'Rules support multiple channels and triggers' do
+  channel ['rise#event','set#event'], thing: 'astro:sun:home', triggered: ['START', 'STOP'] 
+  run { logger.info("Channel triggered") }
+end
+```

data/docs/usage/triggers/command.md

@@ -0,0 +1,69 @@
+---
+layout: default
+title: Received Command
+nav_order: 5
+has_children: false
+parent: Triggers
+grand_parent: Usage
+---
+
+
+# Received_Command
+
+
+| Options  | Description                                                          | Example                            |
+| -------- | -------------------------------------------------------------------- | ---------------------------------- |
+| command  | Only execute rule if the command matches this/these command/commands | `command: 7` or `commands: [7,14]` |
+| commands | Alias of command, may be used if matching more than one command      | `commands: [7,14]`                 |
+
+The `command` value restricts the rule from running to only if the command matches
+
+The examples below assume the following background:
+
+| type   | name             | group      | state |
+| ------ | ---------------- | ---------- | ----- |
+| Number | Alarm_Mode       | AlarmModes | 7     |
+| Number | Alarm_Mode_Other | AlarmModes | 7     |
+
+
+```ruby
+rule 'Execute rule when item received command' do
+  received_command Alarm_Mode
+  run { |event| logger.info("Item received command: #{event.command}" ) }
+end
+```
+
+```ruby
+rule 'Execute rule when item receives specific command' do
+  received_command Alarm_Mode, command: 7
+  run { |event| logger.info("Item received command: #{event.command}" ) }
+end
+```
+
+```ruby
+rule 'Execute rule when item receives one of many specific commands' do
+  received_command Alarm_Mode, commands: [7,14]
+  run { |event| logger.info("Item received command: #{event.command}" ) }
+end
+```
+
+```ruby
+rule 'Execute rule when group receives a specific command' do
+  received_command AlarmModes
+  triggered { |item| logger.info("Group #{item.id} received command")}
+end
+```
+
+```ruby
+rule 'Execute rule when member of group receives any command' do
+  received_command AlarmModes.items
+  triggered { |item| logger.info("Group item #{item.id} received command")}
+end
+```
+
+```ruby
+rule 'Execute rule when member of group is changed to one of many states' do
+  received_command AlarmModes.items, commands: [7,14]
+  triggered { |item| logger.info("Group item #{item.id} received command")}
+end
+```