openhab-scripting 2.16.1 → 2.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c15fe5aa4e28a32decf98e69c4565e8bb9667e40c34e9d06e1a314423ce7256d
-  data.tar.gz: 50099ece4197b4ed58d48b75ca454f5c0e44e158464ae74730848da919d5b292
+  metadata.gz: 44145354fe523ea40a69c6cf2ba81f2684e9982580fe5bc3996f07ab56202e71
+  data.tar.gz: ac579ab41fe3f005d7e5a87df7d18c7f32efa9f49c40f251e07620f238b9e65f
 SHA512:
-  metadata.gz: 43375143a4d64557961a18e653b1fb75c164c2becdb57464ed5ba71200b9110a11d13d0a1c8f0fa493efcaea51e234257f07c622dd3672c79c48f9b4bd6b7d35
-  data.tar.gz: 002cd1958a0102b1a5a975a17ff98a64d57b529fb2255118d232572a4a20e75d9ddbbef51a50cb927e4e85a4cc6ef4d05e7cf64e16f4730885619a55f34afea4
+  metadata.gz: 00026266f68f7d1c9b1ba442ffe0933ac90b5dbe80b61aa2db25470bf3c166c3f5f73067fbba4c292ad31eaeb6913e56299fc9c3625b1e7ce3efc8aaeac69665
+  data.tar.gz: 497fee2e97d90f9e64bd2ba324b9612ed44becb0aec7eb51d4706f1414e3313afeeb3242b5ece884be2fb15525c190a753116548fc2a022c0d4159cff2a8f559

data/lib/openhab.rb

@@ -1,12 +1,8 @@
 # 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/core/openhab_setup'
+require 'openhab/log/logger'
+require 'openhab/dsl/dsl'
 
 require 'openhab/version'
 
@@ -14,7 +10,7 @@ require 'openhab/version'
 # Module used to extend base object with OpenHAB Library functionality
 #
 module OpenHAB
-  include Logging
+  include OpenHAB::Log
   #
   # Extends calling object with DSL and helper methods
   #
@@ -22,15 +18,15 @@ module OpenHAB
   #
   #
   def self.extended(base)
-    base.extend Logging
-    base.extend Debug
-    base.extend EntityLookup
-    base.extend OpenHAB::Core::DSL
-    base.extend OpenHAB::Core::DSL::Tod
+    OpenHAB::Core.wait_till_openhab_ready
+    base.extend Log
+    base.extend OpenHAB::Core::EntityLookup
+    base.extend OpenHAB::DSL
+    base.extend OpenHAB::DSL::TimeOfDay
 
-    base.send :include, OpenHAB::Core::DSL::Tod
-    base.send :include, OpenHAB::Core::DSL::Items
-    base.send :include, OpenHAB::Core::DSL::Types
+    base.send :include, OpenHAB::DSL::TimeOfDay
+    base.send :include, OpenHAB::DSL::Items
+    base.send :include, OpenHAB::DSL::Types
     logger.info "OpenHAB JRuby Scripting Library Version #{OpenHAB::VERSION} Loaded"
   end
 end

data/lib/openhab/core/entity_lookup.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require 'pp'
+require 'java'
+require 'set'
+require 'openhab/dsl/group'
+require 'openhab/log/logger'
+require 'openhab/dsl/items/number_item'
+require 'openhab/dsl/items/string_item'
+require 'openhab/dsl/items/datetime_item'
+
+# Automation lookup and injection of OpenHab entities
+java_import org.openhab.core.items.GroupItem
+
+module OpenHAB
+  module Core
+    #
+    # Manages access to OpenHAB entities
+    #
+    module EntityLookup
+      include OpenHAB::Log
+
+      #
+      # Automatically looks up OpenHAB items and things in appropriate registries
+      #
+      # @param [method] method Name of item to lookup
+      # @param [<Type>] args method arguments
+      # @param [<Type>] block supplied to missing method
+      #
+      # @return [Object] Item or Thing if found in registry
+      #
+      def method_missing(method, *args, &block)
+        return if method.to_s == 'scriptLoaded'
+        return if method.to_s == 'scriptUnloaded'
+
+        logger.trace("method missing, performing OpenHab Lookup for: #{method}")
+        EntityLookup.lookup_entity(method) || super
+      end
+
+      #
+      # Checks if this method responds to the missing method
+      #
+      # @param [String] method_name Name of the method to check
+      # @param [Boolean] _include_private boolean if private methods should be checked
+      #
+      # @return [Boolean] true if this object will respond to the supplied method, false otherwise
+      #
+      def respond_to_missing?(method_name, _include_private = false)
+        logger.trace("Checking if OpenHAB entites exist for #{method_name}")
+        method_name = method_name.to_s if method_name.is_a? Symbol
+
+        method_name == 'scriptLoaded' ||
+          method_name == 'scriptUnloaded' ||
+          EntityLookup.lookup_entity(method_name) ||
+          super
+      end
+
+      #
+      # Looks up an OpenHAB entity
+      #  items are checked first, then things
+      #
+      # @param [String] name of entity to lookup in item or thing registry
+      #
+      # @return [Thing,Item] if found, nil otherwise
+      #
+      def self.lookup_entity(name)
+        lookup_item(name) || lookup_thing(name)
+      end
+
+      #
+      # Decorate items with Ruby wrappers
+      #
+      # @param [Array] items Array of items to decorate
+      #
+      # @return [Array] Array of decorated items
+      #
+      def self.decorate_items(*items)
+        items.flatten.map { |item| decorate_item(item) }
+      end
+
+      #
+      # Decorate item with Ruby wrappers
+      #
+      # @param [Object] item the item object to decorate
+      #
+      # @return [Object] the ruby wrapper for the item
+      #
+      # rubocop: disable Metrics/MethodLength
+      # Method length check disabled - case dispatch pattern
+      private_class_method def self.decorate_item(item)
+        case item
+        when GroupItem
+          decorate_group(item)
+        when Java::Org.openhab.core.library.items::NumberItem
+          OpenHAB::DSL::Items::NumberItem.new(item)
+        when Java::Org.openhab.core.library.items::StringItem
+          OpenHAB::DSL::Items::StringItem.new(item)
+        when Java::Org.openhab.core.library.items::DateTimeItem
+          OpenHAB::DSL::Items::DateTimeItem.new(item)
+        else
+          item
+        end
+      end
+      # rubocop: enable Metrics/MethodLength
+
+      #
+      # Looks up a Thing in the OpenHAB registry replacing '_' with ':'
+      #
+      # @param [String] name of Thing to lookup in Thing registry
+      #
+      # @return [Thing] if found, nil otherwise
+      #
+      def self.lookup_thing(name)
+        logger.trace("Looking up thing(#{name})")
+        # Convert from : syntax to underscore
+        name = name.to_s if name.is_a? Symbol
+
+        # Thing UIDs have at least 3 segements
+        return if name.count('_') < 3
+
+        name = name.gsub('_', ':')
+        # rubocop: disable Style/GlobalVars
+        $things.get(Java::OrgOpenhabCoreThing::ThingUID.new(name))
+        # rubocop: enable Style/GlobalVars
+      end
+
+      #
+      # Lookup OpenHAB items in item registry
+      #
+      # @param [String] name of item to lookup
+      #
+      # @return [Item] OpenHAB item if registry contains a matching item, nil othewise
+      #
+      def self.lookup_item(name)
+        logger.trace("Looking up item(#{name})")
+        name = name.to_s if name.is_a? Symbol
+        # rubocop: disable Style/GlobalVars
+        item = $ir.get(name)
+        # rubocop: enable Style/GlobalVars
+        decorate_item(item)
+      end
+
+      #
+      # Decorate a group from an item base
+      #
+      # @param [OpenHAB item] item item to convert to a group item
+      #
+      # @return [OpenHAB::DSL::Groups::Group] Group created from supplied item
+      #
+      private_class_method def self.decorate_group(item)
+        group = OpenHAB::DSL::Groups::Group.new(Set.new(decorate_items(item.all_members.to_a)))
+        group.group = item
+        group
+      end
+    end
+  end
+end
+
+#
+# Implements const_missing to return OpenHAB items or things if mapping to missing name if they exist
+#
+# @param [String] name Capital string that was not set as a constant and to be looked up
+#
+# @return [Object] OpenHAB Item or Thing if their name exist in OpenHAB item and thing regestries
+#
+def Object.const_missing(name)
+  OpenHAB::Core::EntityLookup.lookup_entity(name) || super
+end

data/lib/openhab/core/openhab_setup.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require 'openhab/log/logger'
+
+module OpenHAB
+  #
+  # Core support for OpenHAB JRuby Library
+  #
+  module Core
+    include OpenHAB::Log
+
+    # @return [Integer] Number of seconds to wait between checks for automation manager
+    CHECK_DELAY = 10
+    private_constant :CHECK_DELAY
+
+    #
+    # Wait until OpenHAB engine ready to process
+    #
+    #
+    def self.wait_till_openhab_ready
+      logger.debug('Checking readyness of OpenHAB')
+      # rubocop: disable Style/GlobalVars
+      until $scriptExtension.get('automationManager')
+        logger.debug("Automation manager not loaded, checking again in #{CHECK_DELAY} seconds.")
+        sleep CHECK_DELAY
+      end
+      # rubocop: enable Style/GlobalVars
+      logger.debug 'Automation manager instantiated, OpenHAB ready for rule processing.'
+    end
+  end
+end

data/lib/openhab/core/osgi.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'openhab/log/logger'
+
+module OpenHAB
+  module Core
+    #
+    # OSGI services interface
+    #
+    class OSGI
+      include OpenHAB::Log
+
+      java_import org.openhab.core.model.script.actions.ScriptExecution
+      java_import org.osgi.framework.FrameworkUtil
+
+      #
+      # @param name [String] The service name
+      #
+      # @return [Service]
+      #
+      def self.service(name)
+        ref = bundle_context.getServiceReference(name)
+        service = bundle_context.getService(ref) if ref
+        logger.trace "OSGI service(#{service}) found for '#{name}' using OSGI Service Reference #{ref}"
+
+        service
+      end
+
+      #
+      # @param name [String] The service name
+      # @param filter [String] Filter for service names. See https://docs.osgi.org/javadoc/r4v43/core/org/osgi/framework/Filter.html
+      #
+      # @return [Array] An array of services
+      #
+      def self.services(name, filter: nil)
+        bundle_context.getServiceReferences(name, filter)&.map do |reference|
+          bundle_context.getService(reference)
+        end
+      end
+
+      #
+      # Get the bundle context
+      #
+      # @return [java::org::osgi::framework::BundleContext] OSGI bundle context
+      #
+      def self.bundle_context
+        @bundle_context ||= bundle.getBundleContext
+      end
+      private_class_method :bundle_context
+
+      # Get the OSGI Bundle for ScriptExtension Class
+      def self.bundle
+        # rubocop: disable Style/GlobalVars
+        @bundle ||= FrameworkUtil.getBundle($scriptExtension.class)
+        # rubocop: enable Style/GlobalVars
+      end
+      private_class_method :bundle
+    end
+  end
+end

data/lib/openhab/dsl/actions.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'openhab/core/osgi'
+
+module OpenHAB
+  module DSL
+    #
+    # Module to import and streamline access to OpenHAB actions
+    #
+    module Actions
+      java_import org.openhab.core.library.types.PercentType
+      include OpenHAB::Log
+
+      OpenHAB::Core::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

data/lib/openhab/dsl/dsl.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'openhab/log/logger'
+require 'openhab/dsl/monkey_patch/events/events'
+require 'openhab/dsl/monkey_patch/ruby/ruby'
+require 'openhab/dsl/monkey_patch/items/items'
+require 'openhab/dsl/monkey_patch/types/types'
+require 'openhab/dsl/monkey_patch/actions/actions'
+require 'openhab/dsl/rules/rule'
+require 'openhab/dsl/actions'
+require 'openhab/dsl/timers'
+require 'openhab/dsl/group'
+require 'openhab/dsl/things'
+require 'openhab/dsl/items/items'
+require 'openhab/dsl/items/datetime_item'
+require 'openhab/dsl/items/number_item'
+require 'openhab/dsl/time_of_day'
+require 'openhab/dsl/gems'
+require 'openhab/dsl/persistence'
+require 'openhab/dsl/units'
+require 'openhab/dsl/types/datetime'
+require 'openhab/dsl/types/quantity'
+require 'openhab/dsl/states'
+
+module OpenHAB
+  #
+  # Module to be extended to access the OpenHAB Ruby DSL
+  #
+  module DSL
+    # Extend the calling module/class with the DSL
+    # Disabling method length because they are all includes
+    # rubocop:disable Metrics/MethodLength
+    def self.extended(base)
+      base.send :include, OpenHAB::DSL::Actions
+      base.send :include, OpenHAB::DSL::Groups
+      base.send :include, OpenHAB::DSL::Items
+      base.send :include, OpenHAB::DSL::Persistence
+      base.send :include, OpenHAB::DSL::Rules
+      base.send :include, OpenHAB::DSL::States
+      base.send :include, OpenHAB::DSL::Things
+      base.send :include, OpenHAB::DSL::Timers
+      base.send :include, OpenHAB::DSL::TimeOfDay
+      base.send :include, OpenHAB::DSL::Types
+      base.send :include, OpenHAB::DSL::Units
+    end
+    # rubocop:enable Metrics/MethodLength
+  end
+end