openhab-scripting 2.16.2 → 2.19.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7471d207d040d9fb085fa45e4f6be88f7ad9d99b0987b6a6845f2bb85c8bf5ab
-  data.tar.gz: b000d8e9397d5556c4387f09e1ec247ccd8303cfa83b27722737e38324ac91b6
+  metadata.gz: 64cbcfa58ba3a4d63a88514b61fdbe811a317e3902c61e16119e0d97a89a3523
+  data.tar.gz: 075ca2dbc459da17c0c2f13b6a05bf6c8ffb829b5d0f96965b449820db59b216
 SHA512:
-  metadata.gz: 13d1994d629262afc44f8c8e62c965e65e383e91224b8fbd12d83f9ec61fa707a0655060c805e3342b373adc5d3034f1744defca1803f84d52190aab055cd8de
-  data.tar.gz: 368969daaa876bdebbd0b60b8818f9da333c2c6d9df96fa7f00abf99df4891f32cd2151d576a6819c2213630fd1ccf3e1a81a1ddc5aa48d2bfe20be776a3c91a
+  metadata.gz: 4ae006b45842d227600eaaeb094285800bddf16935388d6c686112c31bd596ddc8d7fa53eebc6d1b83c0e4053c379662fbfcebab441794bdc183143c27004f92
+  data.tar.gz: 0506ac926852a72f400d8c47d701205e27a22b3514878a366eba39812b5226358c1a5e11a95bce3376b03fef2adceac9ccc1f76e5d3dca0a079b2883d565e8ea

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,173 @@
+# 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'
+require 'openhab/dsl/items/rollershutter_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
+      # rubocop: disable Metrics/AbcSize
+      # Disabled line length and branch size - 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)
+        when Java::Org.openhab.core.library.items::RollershutterItem
+          OpenHAB::DSL::Items::RollershutterItem.new(item)
+        else
+          item
+        end
+      end
+      # rubocop: enable Metrics/AbcSize
+      # 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