openhab-scripting 2.9.1

data/docs/usage/triggers/cron.md

@@ -0,0 +1,19 @@
+---
+layout: default
+title: Cron
+nav_order: 2
+has_children: false
+parent: Triggers
+grand_parent: Usage
+---
+
+
+# Cron
+Utilizes [OpenHAB style cron expressions](https://www.openhab.org/docs/configuration/rules-dsl.html#time-based-triggers) to trigger rules.  This property can be utilized when you need to represent complex expressions not possible with the simpler [every](#Every) syntax.
+
+```ruby
+rule 'Using Cron Syntax' do
+  cron '43 46 13 ? * ?'
+  run { logger.info "Cron rule executed" }
+end
+```

data/docs/usage/triggers/every.md

@@ -0,0 +1,76 @@
+---
+layout: default
+title: Every
+nav_order: 1
+has_children: false
+parent: Triggers
+grand_parent: Usage
+---
+
+# Every
+
+| Value             | Description                              | Example    |
+| ----------------- | ---------------------------------------- | ---------- |
+| :second           | Execute rule every second                | :second    |
+| :minute           | Execute rule very minute                 | :minute    |
+| :hour             | Execute rule every hour                  | :hour      |
+| :day              | Execute rule every day                   | :day       |
+| :week             | Execute rule every week                  | :week      |
+| :month            | Execute rule every month                 | :month     |
+| :year             | Execute rule one a year                  | :year      |
+| :monday           | Execute rule every Monday at midnight    | :monday    |
+| :tuesday          | Execute rule every Tuesday at midnight   | :tuesday   |
+| :wednesday        | Execute rule every Wednesday at midnight | :wednesday |
+| :thursday         | Execute rule every Thursday at midnight  | :thursday  |
+| :friday           | Execute rule every Friday at midnight    | :friday    |
+| :saturday         | Execute rule every Saturday at midnight  | :saturday  |
+| :sunday           | Execute rule every Sunday at midnight    | :sunday    |
+| [Integer].seconds | Execute a rule every X seconds           | 5.seconds  |
+| [Integer].minutes | Execute rule every X minutes             | 3.minutes  |
+| [Integer].hours   | Execute rule every X minutes             | 10.hours   |
+
+| Option | Description                                                                                          | Example                                        |
+| ------ | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
+| :at    | Limit the execution to specific times of day. The value can either be a String or a TimeOfDay object | at: '16:45' or at: TimeOfDay.new(h: 16, m: 45) |
+
+
+# Examples
+
+```ruby
+rule 'Log the rule name every minute' do
+  description 'This rule will create a log every minute'
+  every :minute
+  run { logger.info "Rule '#{name}' executed" }
+end
+```
+
+
+```ruby
+rule 'Log an entry at 11:21' do
+  every :day, at: '11:21'
+  run { logger.info("Rule #{name} run at #{TimeOfDay.now}") }
+end
+
+# The above rule could also be expressed using TimeOfDay class as below
+
+rule 'Log an entry at 11:21' do
+  every :day, at: TimeOfDay.new(h: 11, m: 21)
+  run { logger.info("Rule #{name} run at #{TimeOfDay.now}") }
+end
+```
+
+
+```ruby
+rule 'Log an entry Wednesdays at 11:21' do
+  every :wednesday, at: '11:21'
+  run { logger.info("Rule #{name} run at #{TimeOfDay.now}") }
+end
+```
+
+
+```ruby
+rule 'Every 5 seconds' do
+  every 5.seconds
+  run { logger.info "Rule #{name} executed" }
+end
+```

data/docs/usage/triggers/updated.md

@@ -0,0 +1,78 @@
+---
+layout: default
+title: Updated
+nav_order: 4
+has_children: false
+parent: Triggers
+grand_parent: Usage
+---
+
+# Updated 
+
+
+
+| Options | Description                                        | Example                 |
+| ------- | -------------------------------------------------- | ----------------------- |
+| to      | Only execute rule if update state matches to state | `to: 7` or `to: [7,14]` |
+
+Changed accepts Items, Things or Groups. 
+
+The to value restricts the rule from running to only if the updated state matches. If the updated 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 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 is updated to any value' do
+  updated Alarm_Mode
+  run { logger.info("Alarm Mode Updated") }
+end
+```
+
+```ruby
+rule 'Execute rule when item is updated to specific number' do
+  updated Alarm_Mode, to: 7
+  run { logger.info("Alarm Mode Updated") }
+end
+```
+
+```ruby
+rule 'Execute rule when item is updated to one of many specific states' do
+  updated Alarm_Mode, to: [7,14]
+  run { logger.info("Alarm Mode Updated")}
+end
+```
+
+```ruby
+rule 'Execute rule when group is updated to any state' do
+  updated AlarmModes
+  triggered { |item| logger.info("Group #{item.id} updated")}
+end  
+```
+
+```ruby
+rule 'Execute rule when member of group is changed to any state' do
+  updated AlarmModes.items
+  triggered { |item| logger.info("Group item #{item.id} updated")}
+end 
+```
+
+```ruby
+rule 'Execute rule when member of group is changed to one of many states' do
+  updated AlarmModes.items, to: [7,14]
+  triggered { |item| logger.info("Group item #{item.id} updated")}
+end
+```
+
+Works with things as well:
+```ruby
+rule 'Execute rule when thing is updated' do
+   updated things['astro:sun:home'], :to => :uninitialized
+   run { |event| logger.info("Thing #{event.uid} status <trigger> to #{event.status}") }
+end
+```

data/lib/openhab.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# First patch the $LOAD_PATH to include lib dir
+require 'openhab/core/patch_load_path'
+
+require 'openhab/core/startup_delay'
+require 'openhab/core/log'
+require 'openhab/core/debug'
+require 'openhab/core/dsl'
+
+require 'openhab/version'
+
+#
+# Module used to extend base object with OpenHAB Library functionality
+#
+module OpenHAB
+  include Logging
+  #
+  # Extends calling object with DSL and helper methods
+  #
+  # @param [Object] base Object to decorate with DSL and helper methods
+  #
+  #
+  def self.extended(base)
+    base.extend Logging
+    base.extend Debug
+    base.extend EntityLookup
+    base.extend OpenHAB::Core::DSL
+    base.extend OpenHAB::Core::DSL::Tod
+
+    base.send :include, OpenHAB::Core::DSL::Tod
+    base.send :include, OpenHAB::Core::DSL::Items
+    base.send :include, OpenHAB::Core::DSL::Types
+    logger.info "OpenHAB JRuby Scripting Library Version #{OpenHAB::VERSION} Loaded"
+  end
+end
+
+# Extend caller with OpenHAB methods
+extend OpenHAB

data/lib/openhab/configuration.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# This module holds global configuration values
+module Configuration
+  # -*- coding: utf-8 -*-
+  LOG_PREFIX = 'jsr223.jruby'
+
+  #
+  # Gets the log prefix
+  #
+  # @return [String] Prefix for all log entries
+  #
+  def self.log_prefix
+    LOG_PREFIX
+  end
+end

data/lib/openhab/core/cron.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    #
+    # Module for Cron related methods
+    #
+    module Cron
+      #
+      # Retruns a default map for cron expressions that fires every second
+      # This map is usually updated via merge by other methods to refine cron type triggers.
+      #
+      # @return [Map] Map with symbols for :seconds, :minute, :hour, :dom, :month, :dow configured to fire every second
+      #
+      def cron_expression_map
+        {
+          second: '*',
+          minute: '*',
+          hour: '*',
+          dom: '?',
+          month: '*',
+          dow: '?'
+        }
+      end
+    end
+  end
+end

data/lib/openhab/core/debug.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'pp'
+require 'core/log'
+require 'core/dsl/things'
+
+#
+# Module to support debugging information about the Ruby or OpenHAB environment
+#
+module Debug
+  include Logging
+  include OpenHAB::Core::DSL::Things
+
+  #
+  # Print the loadpath, instance and global variables
+  #
+  def debug_variables
+    pp "Instance #{instance_variables}"
+    pp "Global #{global_variables}"
+    pp "Load Path #{$LOAD_PATH}"
+    # pp "Constants #{Module.constants}"
+  end
+
+  #
+  # Print information about the OpenHAB instance
+  #
+  def debug_openhab
+    logger.debug { "Things - Count #{things.size}" }
+    things.each do |thing|
+      logger.debug { "Thing:(#{thing.label})  UID:(#{thing.uid}) Channels(#{thing.channels.map(&:uid).join(', ')})" }
+    end
+    # logger.debug { $things.getAll.join(", ") }
+  end
+end

data/lib/openhab/core/dsl.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'core/log'
+require 'core/dsl/monkey_patch/events'
+require 'core/dsl/monkey_patch/ruby/ruby'
+require 'core/dsl/monkey_patch/items/items'
+require 'core/dsl/monkey_patch/types/types'
+require 'core/dsl/monkey_patch/actions/actions'
+require 'core/dsl/rule/rule'
+require 'core/dsl/actions'
+require 'core/dsl/timers'
+require 'core/dsl/group'
+require 'core/dsl/things'
+require 'core/dsl/items/items'
+require 'core/dsl/items/number_item'
+require 'core/dsl/time_of_day'
+require 'core/dsl/gems'
+require 'core/dsl/units'
+require 'core/dsl/types/quantity'
+require 'core/dsl/states'
+
+module OpenHAB
+  #
+  #  Holds core functions for OpenHAB Helper Library
+  #
+  module Core
+    #
+    # Module to be extended to access the OpenHAB Ruby DSL
+    #
+    module DSL
+      # Extend the calling module/class with the DSL
+      def self.extended(base)
+        base.send :include, OpenHAB::Core::DSL::Rule
+        base.send :include, OpenHAB::Core::DSL::Items
+        base.send :include, OpenHAB::Core::DSL::Types
+        base.send :include, OpenHAB::Core::DSL::Groups
+        base.send :include, OpenHAB::Core::DSL::Units
+        base.send :include, OpenHAB::Core::DSL::Actions
+        base.send :include, OpenHAB::Core::DSL::Timers
+        base.send :include, OpenHAB::Core::DSL::States
+        base.send :include, OpenHAB::Core::DSL::Tod
+        base.send :include, Things
+      end
+    end
+  end
+end

data/lib/openhab/core/dsl/actions.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'openhab/osgi'
+
+module OpenHAB
+  module Core
+    module DSL
+      #
+      # Module to import and steramlime access to OpenHAB actions
+      #
+      module Actions
+        java_import org.openhab.core.library.types.PercentType
+        include Logging
+
+        OpenHAB::OSGI.services('org.openhab.core.model.script.engine.action.ActionService')&.each do |service|
+          java_import service.actionClass.to_s
+          logger.trace("Loaded ACTION: #{service.actionClass}")
+        end
+        # Import common actions
+        %w[Exec HTTP Ping].each { |action| java_import "org.openhab.core.model.script.actions.#{action}" }
+
+        #
+        # Return an OpenHAB Action object for the given scope and thing
+        #
+        # @param scope [String] The action scope
+        # @param thing_uid [String] Thing UID
+        #
+        # @return [Object] OpenHAB action
+        #
+        def actions(scope, thing_uid)
+          # rubocop: disable Style/GlobalVars
+          $actions.get(scope, thing_uid)
+          # rubocop: enable Style/GlobalVars
+        end
+
+        #
+        # Gets the list of action objects associated with a specific ThingUID
+        #
+        # @param [Java::org::openhab::core::thing::ThingUID] thing_uid to get associated actions for
+        #
+        # @return [Array] of action objects associated with thing_uid, may be empty
+        #
+        def actions_for_thing(thing_uid)
+          thing_uid = thing_uid.to_s
+          # rubocop: disable Style/GlobalVars
+          action_keys = $actions.action_keys
+          # rubocop: enable Style/GlobalVars
+          logger.trace( "Registered actions: '#{action_keys}' for thing '#{thing_uid}'")
+          action_keys.map { |action_key| action_key.split('-', 2) }
+                     .select { |action_pair| action_pair.last == thing_uid }
+                     .map(&:first)
+                     .map { |scope| actions(scope, thing_uid) }
+        end
+
+        #
+        # Send notification to an email or broadcast
+        #
+        # @param msg [String] The notification message to send
+        # @param email [String] The email address to send to. If nil, the message will be broadcasted
+        #
+        # @return [void]
+        #
+        def notify(msg, email: nil)
+          unless defined? NotificationAction
+            raise NoMethodError, 'NotificationAction is not available. Please install the OpenHAB cloud addon'
+          end
+
+          if email
+            NotificationAction.sendNotification email, msg
+          else
+            NotificationAction.sendBroadcastNotification msg
+          end
+        end
+
+        #
+        # Say text via OpenHAB Text-To-Speech service, Voice.say()
+        #
+        # @param text [String] The text to say
+        # @param voice [String] Specify a particular voice to use
+        # @param sink [String] Specify a particular sink to output the speech
+        # @param volume [PercentType] Specify the volume for the speech
+        #
+        # @return [void]
+        #
+        def say(text, voice: nil, sink: nil, volume: nil)
+          volume = PercentType.new(volume&.to_i) unless volume.is_a?(PercentType) || volume.nil?
+          Voice.say text, voice, sink, volume
+        end
+
+        #
+        # Play an audio file via OpenHAB sound service, Audio.playSound()
+        #
+        # @param filename [String] The sound file to play
+        # @param sink [String] Specify a particular sink to output the speech
+        # @param volume [PercentType] Specify the volume for the speech
+        #
+        # @return [void]
+        #
+        def play_sound(filename, sink: nil, volume: nil)
+          volume = PercentType.new(volume&.to_i) unless volume.is_a?(PercentType) || volume.nil?
+          Audio.playSound sink, filename, volume
+        end
+      end
+    end
+  end
+end