openhab-scripting 2.9.1

data/docs/usage/items/contact.md

@@ -0,0 +1,84 @@
+---
+layout: default
+title: Contact
+nav_order: 3
+has_children: false
+parent: Items
+grand_parent: Usage
+---
+
+# Contact Item
+
+This class is aliased to **Contact** so you can compare compare item types using ` item.is_a? Contact or grep(Contact)`
+
+
+| Method  | Description                          | Example                                   |
+| ------- | ------------------------------------ | ----------------------------------------- |
+| open?   | Returns true if item state == OPEN   | `puts "#{item} is closed." if item.open?` |
+| closed? | Returns true if item state == CLOSED | `puts "#{item} is off." if item.closed`   |
+
+
+##### Examples
+
+`open?`/`closed?` checks state of contact
+
+```ruby
+# Log open contacts
+Contacts.select(&:open?).each { |contact| logger.info("Contact #{contact.id} is open")}
+
+# Log closed contacts
+Contacts.select(&:closed?).each { |contact| logger.info("Contact #{contact.id} is closed")}
+
+```
+
+Contacts can be selected in an enumerable with grep.
+
+```ruby
+# Get all Contacts
+items.grep(Contact)
+     .each { |contact| logger.info("#{contact.id} is a Contact") }
+```
+
+Contacts states work in grep.
+
+```ruby
+# Log all open contacts in a group
+Contacts.grep(OPEN)
+        .each { |contact| logger.info("#{contact.id} is in #{contact}") }
+
+# Log all closed contacts in a group
+Contacts.grep(CLOSED)
+        .each { |contact| logger.info("#{contact.id} is in #{contact}") }
+
+```
+
+Contact states work in case statements.
+
+```ruby
+#Log if contact is open or closed
+case TestContact
+when (OPEN)
+  logger.info("#{TestContact.id} is open")
+when (CLOSED)
+  logger.info("#{TestContact.id} is closed")
+end
+```
+
+
+Other examples
+
+```ruby
+rule 'Log state of all doors on system startup' do
+  on_start
+  run do
+    Doors.each do |door|
+      case door
+      when OPEN then logger.info("#{door.id} is Open")
+      when CLOSED then logger.info("#{door.id} is Open")
+      else logger.info("#{door.id} is not initialized")
+      end
+    end
+  end
+end
+
+```

data/docs/usage/items/dimmer.md

@@ -0,0 +1,147 @@
+---
+layout: default
+title: Dimmer
+nav_order: 2
+has_children: false
+parent: Items
+grand_parent: Usage
+---
+
+# Dimmer 
+
+DimmerItem  is aliased to **Dimmer** so you can compare compare item types using 
+
+`item.is_a? Dimmer or grep(Dimmer)`
+
+
+| Method   | Parameters         | Description                                  | Example                                         |
+| -------- | ------------------ | -------------------------------------------- | ----------------------------------------------- |
+| truthy?  |                    | Item state not UNDEF, not NULL and is ON     | `puts "#{item.name} is truthy" if item.truthy?` |
+| on       |                    | Send command to turn item ON                 | `item.on`                                       |
+| off      |                    | Send command to turn item OFF                | `item.off`                                      |
+| on?      |                    | Returns true if item state == ON             | `puts "#{item.name} is on." if item.on?`        |
+| off?     |                    | Returns true if item state == OFF            | `puts "#{item.name} is off." if item.off?`      |
+| dim      | amount (default 1) | Dim the switch the specified amount          | `DimmerSwitch.dim`                              |
+| -        | amount             | Subtract the supplied amount from DimmerItem | `DimmerSwitch << DimmerSwitch - 5`              |
+| brighten | amount (default 1) | Brighten the switch the specified amount     | `DimmerSwitch.brighten`                         |
+| +        | amount             | Add the supplied amount from the DimmerItem  | `DimmerSwitch << DimmerSwitch + 5`              |
+
+
+## Examples
+
+```ruby
+DimmerOne << DimmerOne - 5
+DimmerOne << 100 - DimmerOne
+
+```
+
+`on`/`off` sends commands to a Dimmer
+
+```ruby
+# Turn on all dimmers in group
+Dimmers.each(&:on)
+
+# Turn off all dimmers in group
+Dimmers.each(&:off)
+```
+
+ `on?`/`off?` Checks state of dimmer
+
+```ruby
+# Turn on switches that are off
+Dimmers.select(&:off?).each(&:on)
+	  
+# Turn off switches that are on
+Dimmers.select(&:on?).each(&:off)
+```
+
+`dim` dims the specified amount, defaulting to 1. If 1 is the amount, the decrease command is sent, otherwise the current state - amount is sent as a command.
+
+```ruby
+DimmerOne.dim
+DimmerOne.dim 2
+```
+
+`brighten` brightens the specified amount, defaulting to 1. If 1 is the amount, the increase command is sent, otherwise the current state + amount is sent as a command.
+
+```ruby
+DimmerOne.brighten
+DimmerOne.brighten 2   
+```
+
+Dimmers can be selected in an enumerable with grep.
+
+```ruby
+# Get all dimmers
+items.grep(Dimmer)
+     .each { |dimmer| logger.info("#{dimmer.id} is a Dimmer") }
+```
+
+Dimmers work with ranges and can be used in grep.
+
+```ruby
+# Get dimmers with a state of less than 50
+items.grep(Dimmer)
+     .grep(0...50)
+     .each { |item| logger.info("#{item.id} is less than 50") }
+```
+
+Dimmers can also be used in case statements with ranges.
+```ruby
+#Log dimmer states partioning aat 50%
+items.grep(Dimmer)
+     .each do |dimmer|
+       case dimmer
+       when (0..50)
+         logger.info("#{dimmer.id} is less than 50%")
+        when (51..100)
+         logger.info("#{dimmer.id} is greater than 50%")
+         end
+end
+```
+
+Other examples
+
+```ruby
+rule 'Dim a switch on system startup over 100 seconds' do
+  on_start
+  100.times do
+    run { DimmerSwitch.dim }
+    delay 1.second
+  end
+end
+
+```
+
+```ruby
+rule 'Dim a switch on system startup by 5, pausing every second' do
+   on_start
+   100.step(-5, 0) do | level |
+     run { DimmerSwitch << level }
+     delay 1.second
+   end
+end
+```
+
+```ruby
+rule 'Turn off any dimmers curently on at midnight' do
+   every :day
+   run do
+     items.grep(Dimmer)
+          .select(&:on?)
+          .each(&:off)
+    end
+end
+```
+
+```ruby
+rule 'Turn off any dimmers set to less than 50 at midnight' do
+   every :day
+   run do
+     items.grep(Dimmer)
+          .grep(1...50)
+          .each(&:off)
+     end
+end
+```
+

data/docs/usage/items/groups.md

@@ -0,0 +1,76 @@
+---
+layout: default
+title: Groups
+nav_order: 5
+has_children: false
+parent: Items
+grand_parent: Usage
+---
+
+# Groups
+
+A group can be accessed directly by name, to access all groups use the `groups` method. 
+
+
+## Group Methods
+
+| Method             | Description                                                                                     |
+| ------------------ | ----------------------------------------------------------------------------------------------- |
+| group              | Access Group Item                                                                               |
+| items              | Used to inform a rule that you want it to operate on the items in the group (see example below) |
+| groups             | Direct subgroups of this group                                                                  |
+| set methods        | All methods [here](https://ruby-doc.org/stdlib-2.5.0/libdoc/set/rdoc/Set.html)                  |
+| enumerable methods | All methods [here](https://ruby-doc.org/core-2.5.0/Enumerable.html)                             |
+
+
+## Examples
+
+Given the following
+
+```
+Group House
+// Location perspective
+Group GroundFloor  (House)
+Group Livingroom   (GroundFloor)
+// Functional perspective
+Group Sensors      (House)
+Group Temperatures (Sensors)
+
+Number Livingroom_Temperature "Living Room temperature" (Livingroom, Temperatures)
+Number Bedroom_Temp "Bedroom temperature" (GroundFloor, Temperatures)
+Number Den_Temp "Den temperature" (GroundFloor, Temperatures)
+```
+
+The following are log lines and the output after the comment
+
+```ruby
+#Operate on items in a group using enumerable methods
+logger.info("Total Temperatures: #{Temperatures.count}")     #Total Temperatures: 3'
+logger.info("Temperatures: #{House.sort_by(&:label).map(&:label).join(', ')}") #Temperatures: Bedroom temperature, Den temperature, Living Room temperature' 
+
+#Access to the group object via the 'group' method
+logger.info("Group: #{Temperatures.group.name}" # Group: Temperatures'
+
+#Operates on items in nested groups using enumerable methods
+logger.info("House Count: #{House.count}")           # House Count: 3
+llogger.info("Items: #{House.sort_by(&:label).map(&:label).join(', ')}")  # Items: Bedroom temperature, Den temperature, Living Room temperature
+
+#Access to sub groups using the 'groups' method
+logger.info("House Sub Groups: #{House.groups.count}")  # House Sub Groups: 2
+logger.info("Groups: #{House.groups.sort_by(&:id).map(&:id).join(', ')}")  # Groups: GroundFloor, Sensors
+
+```
+
+
+```ruby
+rule 'Turn off any switch that changes' do
+  changed Switches.items
+  triggered &:off
+end
+```
+
+Built in [enumerable](https://ruby-doc.org/core-2.5.1/Enumerable.html)/[set](https://ruby-doc.org/stdlib-2.5.1/libdoc/set/rdoc/Set.html) functions can be applied to groups.  
+```ruby
+logger.info("Max is #{Temperatures.max}")
+logger.info("Min is #{Temperatures.min}")
+```

data/docs/usage/items/number.md

@@ -0,0 +1,225 @@
+---
+layout: default
+title: Number
+nav_order: 4
+has_children: false
+parent: Items
+grand_parent: Usage
+---
+
+
+#### Number Item
+
+| Method          | Parameters | Description                                                                                                                                              | Example                                                                      |
+| --------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| truthy?         |            | Item state not UNDEF, not NULL and is not Zero                                                                                                           | `puts "#{item.name} is truthy" if item.truthy?`                              |
+| +,-,\*,/        | amount     | Perform the operation between the state of the number item and the supplied value*                                                                       | `NumberItem << NumberItem - 5` or `NumberItem << 10 + NumberItem`            |
+| \|              | unit       | Convert the supplied NumberItem to the supplied unit. Unit can either be a Unit class or string representation of the symbol, returns a Quantity object. | `NumberItem` &#124; `ImperialUnits::FAHRENHEIT` or `NumberItem `&#124;`'°F'` |
+| to_d            |            | Returns the state as a BigDecimal or nil if state is UNEF or NULL                                                                                        | `NumberOne.to_d`                                                             |
+| to_i            |            | Returns the state as an Integer or nil if state is UNEF or NULL                                                                                          | `NumberOne.to_i`                                                             |
+| to_f            |            | Returns the state as a Float or nil if state is UNEF or NULL                                                                                             | `NumberOne.to_f`                                                             |
+| dimension       |            | Returns the dimension of the Number Item, nil if the number is dimensionless                                                                             | `Numberone.dimension`                                                        |
+| Numeric Methods |            | All methods for [Ruby Numeric](https://ruby-doc.org/core-2.5.0/Numeric.html)                                                                             |                                                                              |
+
+ Math operations for dimensionless numbers return a type of [Ruby BigDecimal](https://ruby-doc.org/stjjdlib-2.5.1/libdoc/bigdecimal/rdoc/BigDecimal.html).  Check [Quantities section](#Quantities) for details of how math operations impact dimensioned numbers. 
+
+
+##### Examples
+
+Math operations can be performed directly on the NumberItem
+
+```ruby
+# Add 5 to a number item
+NumberOne << NumberOne + 5
+
+# Add Number item to 5
+NumberOne << 5 + NumberOne
+
+```
+
+Number Items can be selected in an enumerable with grep.
+
+```ruby
+# Get all NumberItems
+items.grep(NumberItem)
+      .each { |number| logger.info("#{number.id} is a Number Item") }
+```
+
+Number Item work with ranges and can be used in grep.
+
+```ruby
+# Get numbers in group Numbers with a state of less than 50
+      # Get all NumberItems less than 50
+      Numbers.grep(0...50)
+           .each { |number| logger.info("#{number.id} is less than 50") }
+```
+
+Number Items can also be used in case statements with ranges.
+```ruby
+#Check if number items is less than 50
+case NumberOne
+when (0...50)
+  logger.info("#{NumberOne.id} is less than 50")
+when (50..100)
+  logger.info("#{NumberOne.id} is greater than 50")
+end
+```
+
+
+#### Quantities 
+Quantities are part of the [Units of Measurement](https://www.openhab.org/docs/concepts/units-of-measurement.html) framework in OpenHAB.  The quantity object acts as ruby wrapper around the OpenHAB QuantityType.
+
+| Method             | Parameters | Description                                                                                                                | Example                                                                      |
+| ------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| +,-,\*,/,-(negate) | amount     | Perform the operation between the state of the number item and the supplied value*                                         | `NumberItem << NumberItem - 5` or `NumberItem << 10 + NumberItem`            |
+| \|                 | unit       | Convert the supplied Quantity to the supplied unit. Unit can either be a Unit class or string representation of the symbol | `NumberItem` &#124; `ImperialUnits::FAHRENHEIT` or `NumberItem `&#124;`'°F'` |
+| quantity           |            | Returns the underlying OpenHAB QuantityType object                                                                         | `Numberone.dimension`                                                        |
+| Numeric Methods    |            | All methods for [Ruby Numeric](https://ruby-doc.org/core-2.5.0/Numeric.html)                                               |                                                                              |
+
+###### Examples
+
+Quantity types can perform math operations between them.  
+
+```ruby
+Quantity.new('50 °F') + -Quantity.new('25 °F') = 25.0 °F
+Quantity.new('100 °F') / Quantity.new('2 °F') = 50
+Quantity.new('50 °F') * Quantity.new('2 °F') = 100 °F
+Quantity.new('50 °F') - Quantity.new('25 °F') = 25 °F
+Quantity.new('50 °F') + Quantity.new('50 °F') = 100 °F
+```
+
+If the operand is a string it will be automatically converted into a Quantity. 
+```ruby
+Quantity.new('100 °F') / '2 °F' = 50
+Quantity.new('50 °F') * '2 °F' = 100 °F
+Quantity.new('50 °F') - '25 °F' = 25 °F
+Quantity.new('50 °F') + '50 °F' = 100 °F
+```
+
+If the operand is a number, it will be unit-less, but the result of the operation will have a unit.  This only works for multiplication and division. 
+```ruby
+Quantity.new('50 °F')  * 2 = 100 °F
+Quantity.new('100 °F') / 2 = 50 °F 
+```
+
+If the operand is a dimensioned NumberItem it will automatically be converted to a quantity for the operation.
+```ruby
+# NumberF = '2 °F'
+# NumberC = '2 °C'
+
+Quantity.new('50 °F') + NumberF # = 52.0 °F
+Quantity.new('50 °F') + NumberC # = 85.60 °F 
+```
+
+If the operand is a non-dimensioned NumberItem it can be used only in multiplication and division operations.
+
+```ruby
+# Number Dimensionless = 2
+
+Quantity.new('50 °F') * Dimensionless # = 100 °F   
+Quantity.new('50 °F') / Dimensionless # = 25 °F    
+```
+
+Quantities can be compared, if they have comparable units.
+```ruby
+Quantity.new('50 °F') >  Quantity.new('25 °F')  
+Quantity.new('50 °F') >  Quantity.new('525 °F') 
+Quantity.new('50 °F') >= Quantity.new('50 °F')  
+Quantity.new('50 °F') == Quantity.new('50 °F')  
+Quantity.new('50 °F') <  Quantity.new('25 °C')  
+```
+
+If the compare-to is a string, it will be automatically converted into a quantity.
+```ruby
+Quantity.new('50 °F') == '50 °F' 
+Quantity.new('50 °F') <  '25 °C'
+```
+
+Dimensioned Number Items can be converted to quantities with other units using the \| operator
+
+```ruby
+# NumberC = '23 °C'
+
+# Using a unit 
+logger.info("In Fahrenheit #{NumberC| ImperialUnits::FAHRENHEIT }")
+
+# Using a string
+logger.info("In Fahrenheit #{NumberC | '°F'}")
+
+```
+
+Dimensionless Number Items can be converted to quantities with units using the \| operator
+
+```ruby
+# Dimensionless = 70
+
+# Using a unit 
+logger.info("In Fahrenheit #{Dimensionless| ImperialUnits::FAHRENHEIT }")
+
+# Using a string
+logger.info("In Fahrenheit #{Dimensionless | '°F'}")
+
+```
+
+Dimensioned Number Items automatically use their units and convert automatically for math operations
+
+```ruby
+# Number:Temperature NumberC = 23 °C
+# Number:Temperature NumberF = 70 °F
+
+NumberC - NumberF # = 1.88 °C
+NumberF + NumberC # = 143.40 °F 
+```
+
+Dimensionless Number Items can be used for multiplication and division. 
+
+```ruby
+# Number Dimensionless = 2
+# Number:Temperature NumberF = 70 °F
+
+NumberF * Dimensionless # = 140.0 °F 
+NumberF / Dimensionless # = 35.0 °F
+Dimensionless * NumberF # = 140.0 °F 
+2 * NumberF             # = 140.0 °F 
+```
+
+Comparisons work on dimensioned number items with different, but comparable units.
+```ruby
+# Number:Temperature NumberC = 23 °C
+# Number:Temperature NumberF = 70 °F
+
+NumberC > NumberF # = true
+```
+
+Comparisons work with dimensioned numbers and strings representing quantities
+```ruby
+# Number:Temperature NumberC = 23 °C
+# Number:Temperature NumberF = 70 °F
+
+NumberC > '4 °F'   #= true 
+NumberC == '23 °C' #= true  
+```
+
+For certain unit types, such as temperature, all unit needs to be normalized to the comparator for all operations when combining comparison operators with dimensioned numbers.
+
+```ruby
+(NumberC |'°F') - (NumberF |'°F') < '4 °F' 
+```
+
+To facilitate conversion of multiple dimensioned and dimensionless numbers the unit block may be used.  The unit block attempts to do the _right thing_ based on the mix of dimensioned and dimensionless items within the block.  Specifically all dimensionless items are converted to the supplied unit, except when they are used for multiplication or division. 
+
+```ruby
+# Number:Temperature NumberC = 23 °C
+# Number:Temperature NumberF = 70 °F
+# Number Dimensionless = 2
+
+unit('°F') { NumberC - NumberF < 4 }               					#= true   
+unit('°F') { NumberC - '24 °C' < 4 }               					#= true   
+unit('°F') { Quantity.new('24 °C') - NumberC < 4 }					#= true   
+unit('°C') { NumberF - '20 °C' < 2 }               					#= true   
+unit('°C') { NumberF - Dimensionless }             					#= 19.11 °C
+unit('°C') { NumberF - Dimensionless < 20 }        					#= true   
+unit('°C') { Dimensionless + NumberC == 25 }       					#= true     unit('°C') { 2 + NumberC == 25 }                   					#= true
+unit('°C') { Dimensionless * NumberC == 46 }       					#= true      unit('°C') { 2 * NumberC == 46 }                   				 #= true
+unit('°C') { ( (2 * (NumberF + NumberC) ) / Dimensionless ) < 45} 	#= true      unit('°C') { [NumberC, NumberF, Dimensionless].min }              	 #= 2       
+```