openhab-scripting 2.9.1 → 2.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. checksums.yaml +4 -4
  2. data/lib/openhab/version.rb +1 -1
  3. metadata +1 -61
  4. data/.github/workflows/workflow.yml +0 -327
  5. data/.gitignore +0 -17
  6. data/.java-version +0 -1
  7. data/.rspec +0 -1
  8. data/.yardopts +0 -1
  9. data/CHANGELOG.md +0 -113
  10. data/Gemfile +0 -28
  11. data/Gemfile.lock +0 -245
  12. data/Guardfile +0 -35
  13. data/LICENSE +0 -277
  14. data/README.md +0 -23
  15. data/Rakefile +0 -406
  16. data/bin/console +0 -15
  17. data/bin/setup +0 -8
  18. data/config/userdata/config/org/openhab/restauth.config +0 -3
  19. data/cucumber.yml +0 -1
  20. data/docs/_config.yml +0 -135
  21. data/docs/contributing/index.md +0 -47
  22. data/docs/examples/conversions.md +0 -123
  23. data/docs/examples/index.md +0 -61
  24. data/docs/index.md +0 -19
  25. data/docs/installation/index.md +0 -26
  26. data/docs/motivation/index.md +0 -27
  27. data/docs/usage/execution.md +0 -9
  28. data/docs/usage/execution/delay.md +0 -48
  29. data/docs/usage/execution/otherwise.md +0 -30
  30. data/docs/usage/execution/run.md +0 -70
  31. data/docs/usage/execution/triggered.md +0 -48
  32. data/docs/usage/guards.md +0 -51
  33. data/docs/usage/guards/between.md +0 -30
  34. data/docs/usage/guards/not_if.md +0 -41
  35. data/docs/usage/guards/only_if.md +0 -40
  36. data/docs/usage/index.md +0 -11
  37. data/docs/usage/items.md +0 -66
  38. data/docs/usage/items/contact.md +0 -84
  39. data/docs/usage/items/dimmer.md +0 -147
  40. data/docs/usage/items/groups.md +0 -76
  41. data/docs/usage/items/number.md +0 -225
  42. data/docs/usage/items/string.md +0 -49
  43. data/docs/usage/items/switch.md +0 -85
  44. data/docs/usage/misc.md +0 -7
  45. data/docs/usage/misc/actions.md +0 -108
  46. data/docs/usage/misc/duration.md +0 -21
  47. data/docs/usage/misc/gems.md +0 -25
  48. data/docs/usage/misc/logging.md +0 -21
  49. data/docs/usage/misc/metadata.md +0 -128
  50. data/docs/usage/misc/store_states.md +0 -42
  51. data/docs/usage/misc/time_of_day.md +0 -69
  52. data/docs/usage/misc/timers.md +0 -67
  53. data/docs/usage/rule.md +0 -43
  54. data/docs/usage/things.md +0 -29
  55. data/docs/usage/triggers.md +0 -8
  56. data/docs/usage/triggers/changed.md +0 -57
  57. data/docs/usage/triggers/channel.md +0 -54
  58. data/docs/usage/triggers/command.md +0 -69
  59. data/docs/usage/triggers/cron.md +0 -19
  60. data/docs/usage/triggers/every.md +0 -76
  61. data/docs/usage/triggers/updated.md +0 -78
  62. data/openhab-scripting.gemspec +0 -30
  63. data/openhab_rules/warmup.rb +0 -5
data/docs/usage/misc/store_states.md DELETED
@@ -1,42 +0,0 @@
1
- ---
2
- layout: default
3
- title: Store States
4
- nav_order: 6
5
- has_children: false
6
- parent: Misc
7
- grand_parent: Usage
8
- ---
9
-
10
- ### store_states
11
-
12
- 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).
13
-
14
- ```ruby
15
- states = store_states Item1, Item2
16
- ...
17
- states.restore
18
- ```
19
-
20
- or in a block context:
21
- ```ruby
22
- store_states Item1, Item2 do
23
- ...
24
- end # the states will be restored here
25
- ```
26
-
27
- It can take an array of items:
28
- ```ruby
29
- items_to_store = [ Item1, Item2 ]
30
- states = store_states items_to_store
31
- ...
32
- states.restore_changes # restore only changed items
33
- ```
34
-
35
-
36
- The returned states variable is a hash that supports some additional methods:
37
-
38
- | method | description |
39
- | --------------- | ---------------------------------------------------------------------------------------- |
40
- | restore | Restores the states of all the stored items by calling events.restoreStates() internally |
41
- | changed? | Returns true if any of the stored items had changed states |
42
- | restore_changes | restores only items whose state had changed
data/docs/usage/misc/time_of_day.md DELETED
@@ -1,69 +0,0 @@
1
- ---
2
- layout: default
3
- title: TimeOfDay
4
- nav_order: 5
5
- has_children: false
6
- parent: Misc
7
- grand_parent: Usage
8
- ---
9
-
10
- # TimeOfDay
11
-
12
- TimeOfDay class can be used in rules for time related logic. Methods:
13
-
14
- | Method | Parameter | Description | Example |
15
- | ----------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
16
- | 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 |
17
- | now | | Creates a TimeOfDay object that represents the current time | TimeOfDay.now > curfew_start, or TimeOfDay.now > '19:30' |
18
- | MIDNIGHT | | Creates a TimeOfDay object for 00:00 | TimeOfDay.MIDNIGHT |
19
- | NOON | | Creates a TimeOfDay object for 12:00 | TimeOfDay.now < TimeOfDay.NOON |
20
- | constructor | h, m, s | Creates a TimeOfDay with the given hour, minute, second | TimeOfDay.new(h: 17, m: 30, s: 0) |
21
- | hour | | Returns the hour part of the object | TimeOfDay.now.hour |
22
- | minute | | Returns the minute part of the object | TimeOfDay.now.minute |
23
- | second | | Returns the second part of the object | TimeOfDay.now.second |
24
- | between? | TimeOfDayRange | Returns true if it falls within the given time range | TimeOfDay.now.between? '3pm'..'7pm' |
25
-
26
-
27
- A TimeOfDay object can be compared against another TimeOfDay object or a parseable string representation of time.
28
-
29
- Note: the following global constants are available:
30
- | Name | Description |
31
- | -------- | ----------- |
32
- | MIDNIGHT | 00:00 |
33
- | NOON | 12:00 |
34
-
35
-
36
- ## Examples
37
-
38
- ```ruby
39
- #Create a TimeOfDay object
40
- break_time = NOON
41
-
42
- if TimeOfDay.now > TimeOfDay.new(h: 17, m: 30, s: 0) # comparing two TimeOfDay objects
43
- # do something
44
- elsif TimeOfDay.now < '8:30' # comparison against a string
45
- #do something
46
- end
47
- four_pm = TimeOfDay.parse '16:00'
48
- ```
49
-
50
- ## between
51
-
52
- `between` creates a TimeOfDay range that can be used to check if another Time, TimeOfDay, or [TimeOfDay parsable string](#TimeOfDay) is within that range.
53
-
54
- ```ruby
55
- logger.info("Within time range") if between('10:00'..'14:00').cover? Time.now
56
- logger.info("Within time range") if between('10:00'..'14:00').include? TimeOfDay.now
57
-
58
- case Time.now
59
-
60
- when between('6:00'...'12:00')
61
- logger.info("Morning Time")
62
- when between('12:00'..'15:00')
63
- logger.info("Afternoon")
64
- else
65
- logger.info("Not in time range")
66
- end
67
- ```
68
-
69
-
data/docs/usage/misc/timers.md DELETED
@@ -1,67 +0,0 @@
1
- ---
2
- layout: default
3
- title: Timers
4
- nav_order: 4
5
- has_children: false
6
- parent: Misc
7
- grand_parent: Usage
8
- ---
9
-
10
- # Timers
11
- Timers are created using the `after` method.
12
-
13
- After method parameters
14
-
15
- | Parameter | Description |
16
- | --------- | ------------------------------------------------------------------ |
17
- | duration | Duration for timer |
18
- | block | Block to execute after duration, block will be passed timer object |
19
-
20
- Timer Object
21
- 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:
22
-
23
- | Method | Parameter | Description |
24
- | ------------- | --------- | ------------------------------------------------------------------------------------------------ |
25
- | `cancel` | | Cancel the scheduled timer |
26
- | `reschedule` | duration | Optional [duration](#Duration) if unspecified original duration supplied to after method is used |
27
- | `active?` | | An alias for `Timer::isActive()` |
28
- | `running?` | | An alias for `Timer::isRunning()` |
29
- | `terminated?` | | An alias for `Timer::hasTerminated()` |
30
-
31
- ```ruby
32
- after 5.seconds do
33
- logger.info("Timer Fired")
34
- end
35
- ```
36
-
37
- ```ruby
38
- # Timers delegate methods to OpenHAB timer objects
39
- after 1.second do |timer|
40
- logger.info("Timer is active? #{timer.is_active}")
41
- end
42
- ```
43
-
44
- ```ruby
45
- # Timers can be rescheduled to run again, waiting the original duration
46
- after 3.seconds do |timer|
47
- logger.info("Timer Fired")
48
- timer.reschedule
49
- end
50
- ```
51
-
52
- ```ruby
53
- # Timers can be rescheduled for different durations
54
- after 3.seconds do |timer|
55
- logger.info("Timer Fired")
56
- timer.reschedule 5.seconds
57
- end
58
- ```
59
-
60
- ```ruby
61
- # Timers can be manipulated through the returned object
62
- mytimer = after 1.minute do
63
- logger.info('It has been 1 minute')
64
- end
65
-
66
- mytimer.cancel
67
- ```
data/docs/usage/rule.md DELETED
@@ -1,43 +0,0 @@
1
- ---
2
- layout: default
3
- title: Rules
4
- nav_order: 1
5
- has_children: false
6
- parent: Usage
7
- ---
8
-
9
-
10
- ## Rule Syntax
11
- ```ruby
12
- require 'openhab'
13
-
14
- rule 'name' do
15
- <zero or more triggers>
16
- <zero or more execution blocks>
17
- <zero or more guards>
18
- end
19
- ```
20
-
21
- ### All of the properties that are available to the rule resource are
22
-
23
- | Property | Type | Last/Multiple | Options | Default | Description | Examples |
24
- | ---------------- | ----------------------------------------------------------------------- | ------------- | ------------------------------------- | ------- | --------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
25
- | description | String | Single | | | Set the rule description | |
26
- | 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) |
27
- | cron | String | Multiple | | | OpenHAB Style Cron Expression | '* * * * * * ?' |
28
- | 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 |
29
- | 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 |
30
- | received_command | Item or Item Array[] or Group or Group.items | Multiple | command: | | Execute rule on item command | BedroomLightSwitch command: ON |
31
- | channel | Channel | Multiple | triggered: | | Execute rule on channel trigger | `'astro:sun:home:rise#event', triggered: 'START'` |
32
- | on_start | Boolean | Single | | false | Execute rule on system start | on_start |
33
- | run | Block passed event | Multiple | | | Code to execute on rule trigger | |
34
- | triggered | Block passed item | Multiple | | | Code with triggering item to execute on rule trigger | |
35
- | delay | Duration | Multiple | | | Duration to wait between or after run blocks | delay 5.seconds |
36
- | otherwise | Block passed event | Multiple | | | Code to execute on rule trigger if guards are not satisfied | |
37
- | 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) |
38
- | 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} |
39
- | not_if | Item or Item Array, or Block | Multiple | | | Do **NOT** execute rule if any of the supplied items or blocks returns true | BedroomLightSwitch |
40
- | enabled | Boolean | Single | | true | Enable or disable the rule from executing | |
41
-
42
- Last means that last value for the property is used <br>
43
- Multiple indicates that multiple entries of the same property can be used in aggregate
data/docs/usage/things.md DELETED
@@ -1,29 +0,0 @@
1
- ---
2
- layout: default
3
- title: Things
4
- nav_order: 5
5
- has_children: false
6
- parent: Usage
7
- has_toc: false
8
- ---
9
-
10
- # Things
11
-
12
- Things can be access using the `things` method and subsequent operations on that methods.
13
-
14
- | Method | Description |
15
- | ------------------ | ------------------------------------------------------------------- |
16
- | things | Return all things as a Ruby Set |
17
- | [] | Get a specific thing by name |
18
- | enumerable methods | All methods [here](https://ruby-doc.org/core-2.5.0/Enumerable.html) |
19
-
20
- ```ruby
21
- things.each { |thing| logger.info("Thing: #{thing.uid}")}
22
- ```
23
-
24
- ```ruby
25
- logger.info("Thing: #{things['astro:sun:home'].uid}")
26
- ```
27
-
28
- 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`.
29
-
data/docs/usage/triggers.md DELETED
@@ -1,8 +0,0 @@
1
- ---
2
- layout: default
3
- title: Triggers
4
- nav_order: 1
5
- has_children: true
6
- parent: Usage
7
- ---
8
-
data/docs/usage/triggers/changed.md DELETED
@@ -1,57 +0,0 @@
1
- ---
2
- layout: default
3
- title: Changed
4
- nav_order: 3
5
- has_children: false
6
- parent: Triggers
7
- grand_parent: Usage
8
- ---
9
-
10
-
11
- # Changed
12
-
13
-
14
- | Options | Description | Example |
15
- | ------- | ------------------------------------------------------ | --------------- |
16
- | from | Only execute rule if previous state matches from state | from: OFF |
17
- | to | Only execute rule if new state matches from state | to: ON |
18
- | for | Only execute rule if value stays changed for duration | for: 10.seconds |
19
-
20
- Changed accepts Items, Things or Groups.
21
-
22
- 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).
23
-
24
- 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.
25
-
26
- 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):
27
- ```ruby
28
- rule "Execute rule when item is changed for specified duration" do
29
- changed Alarm_Mode, for: 20.seconds
30
- run { logger.info("Alarm Mode Updated")}
31
- end
32
- ```
33
-
34
- You can optionally provide from and to states to restrict the cases in which the rule executes:
35
- ```ruby
36
- rule 'Execute rule when item is changed to specific number, from specific number, for specified duration' do
37
- changed Alarm_Mode, from: 8, to: 14, for: 12.seconds
38
- run { logger.info("Alarm Mode Updated")}
39
- end
40
- ```
41
-
42
- Works with things as well:
43
- ```ruby
44
- rule 'Execute rule when thing is changed' do
45
- changed things['astro:sun:home'], :from => :online, :to => :uninitialized
46
- run { |event| logger.info("Thing #{event.uid} status <trigger> to #{event.status}") }
47
- end
48
- ```
49
-
50
-
51
- Real world example:
52
- ```ruby
53
- rule 'Log (or notify) when an exterior door is left open for more than 5 minutes' do
54
- changed ExteriorDoors, to: OPEN, for: 5.minutes
55
- triggered {|door| logger.info("#{door.id} has been left open!")}
56
- end
57
- ```
data/docs/usage/triggers/channel.md DELETED
@@ -1,54 +0,0 @@
1
- ---
2
- layout: default
3
- title: Channel
4
- nav_order: 6
5
- has_children: false
6
- parent: Triggers
7
- grand_parent: Usage
8
- ---
9
-
10
- # channel
11
-
12
- | Option | Description | Example |
13
- | --------- | ----------------------------------------------------------------------------- | ------------------------------------------------------ |
14
- | triggered | Only execute rule if the event on the channel matches this/these event/events | `triggered: 'START' ` or `triggered: ['START','STOP']` |
15
- | thing | Thing for specified channels | `thing: 'astro:sun:home'` |
16
-
17
- 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.
18
-
19
-
20
- ```ruby
21
- rule 'Execute rule when channel is triggered' do
22
- channel 'astro:sun:home:rise#event'
23
- run { logger.info("Channel triggered") }
24
- end
25
-
26
- # The above is the same as the below
27
-
28
- rule 'Execute rule when channel is triggered' do
29
- channel 'rise#event', thing: 'astro:sun:home'
30
- run { logger.info("Channel triggered") }
31
- end
32
-
33
- ```
34
-
35
- ```ruby
36
- rule 'Rule provides access to channel trigger events in run block' do
37
- channel 'astro:sun:home:rise#event', triggered: 'START'
38
- run { |trigger| logger.info("Channel(#{trigger.channel}) triggered event: #{trigger.event}") }
39
- end
40
- ```
41
-
42
- ```ruby
43
- rule 'Rules support multiple channels' do
44
- channel ['rise#event','set#event'], thing: 'astro:sun:home'
45
- run { logger.info("Channel triggered") }
46
- end
47
- ```
48
-
49
- ```ruby
50
- rule 'Rules support multiple channels and triggers' do
51
- channel ['rise#event','set#event'], thing: 'astro:sun:home', triggered: ['START', 'STOP']
52
- run { logger.info("Channel triggered") }
53
- end
54
- ```
data/docs/usage/triggers/command.md DELETED
@@ -1,69 +0,0 @@
1
- ---
2
- layout: default
3
- title: Received Command
4
- nav_order: 5
5
- has_children: false
6
- parent: Triggers
7
- grand_parent: Usage
8
- ---
9
-
10
-
11
- # Received_Command
12
-
13
-
14
- | Options | Description | Example |
15
- | -------- | -------------------------------------------------------------------- | ---------------------------------- |
16
- | command | Only execute rule if the command matches this/these command/commands | `command: 7` or `commands: [7,14]` |
17
- | commands | Alias of command, may be used if matching more than one command | `commands: [7,14]` |
18
-
19
- The `command` value restricts the rule from running to only if the command matches
20
-
21
- The examples below assume the following background:
22
-
23
- | type | name | group | state |
24
- | ------ | ---------------- | ---------- | ----- |
25
- | Number | Alarm_Mode | AlarmModes | 7 |
26
- | Number | Alarm_Mode_Other | AlarmModes | 7 |
27
-
28
-
29
- ```ruby
30
- rule 'Execute rule when item received command' do
31
- received_command Alarm_Mode
32
- run { |event| logger.info("Item received command: #{event.command}" ) }
33
- end
34
- ```
35
-
36
- ```ruby
37
- rule 'Execute rule when item receives specific command' do
38
- received_command Alarm_Mode, command: 7
39
- run { |event| logger.info("Item received command: #{event.command}" ) }
40
- end
41
- ```
42
-
43
- ```ruby
44
- rule 'Execute rule when item receives one of many specific commands' do
45
- received_command Alarm_Mode, commands: [7,14]
46
- run { |event| logger.info("Item received command: #{event.command}" ) }
47
- end
48
- ```
49
-
50
- ```ruby
51
- rule 'Execute rule when group receives a specific command' do
52
- received_command AlarmModes
53
- triggered { |item| logger.info("Group #{item.id} received command")}
54
- end
55
- ```
56
-
57
- ```ruby
58
- rule 'Execute rule when member of group receives any command' do
59
- received_command AlarmModes.items
60
- triggered { |item| logger.info("Group item #{item.id} received command")}
61
- end
62
- ```
63
-
64
- ```ruby
65
- rule 'Execute rule when member of group is changed to one of many states' do
66
- received_command AlarmModes.items, commands: [7,14]
67
- triggered { |item| logger.info("Group item #{item.id} received command")}
68
- end
69
- ```