openhab-scripting 2.16.0 → 2.17.0

data/lib/openhab/dsl/rules/triggers/changed.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'openhab/log/logger'
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # Module holds rule triggers
+      #
+      module Triggers
+        include OpenHAB::Log
+
+        #
+        # Struct capturing data necessary for a conditional trigger
+        #
+        TriggerDelay = Struct.new(:to, :from, :duration, :timer, :tracking_to, keyword_init: true) do
+          def timer_active?
+            timer&.is_active
+          end
+        end
+
+        #
+        # Creates a trigger item, group and thing changed
+        #
+        # @param [Object] items array of objects to create trigger for
+        # @param [to] to state for object to change for
+        # @param [from] from <description>
+        # @param [OpenHAB::Core::Duration] for Duration to delay trigger until to state is met
+        #
+        # @return [Trigger] OpenHAB trigger
+        #
+        def changed(*items, to: nil, from: nil, for: nil)
+          items.flatten.each do |item|
+            logger.trace("Creating changed trigger for entity(#{item}), to(#{to}), from(#{from})")
+            # for is a reserved word in ruby, so use local_variable_get :for
+            if (wait_duration = binding.local_variable_get(:for))
+              changed_wait(item, to: to, from: from, duration: wait_duration)
+            else
+              # Place in array and flatten to support multiple to elements or single or nil
+              [to].flatten.each do |to_state|
+                create_changed_trigger(item, from, to_state)
+              end
+            end
+          end
+        end
+
+        private
+
+        #
+        # Create a TriggerDelay for for an item or group that is changed for a specific duration
+        #
+        # @param [Object] item to create trigger delay for
+        # @param [OpenHAB::Core::Duration] duration to delay trigger for until condition is met
+        # @param [Item State] to OpenHAB Item State item or group needs to change to
+        # @param [Item State] from OpenHAB Item State item or group needs to be coming from
+        #
+        # @return [Array] Array of current TriggerDelay objects
+        #
+        def changed_wait(item, duration:, to: nil, from: nil)
+          # If GroupItems specified, use the group state trigger instead
+          if item.is_a? GroupItems
+            config = { 'groupName' => item.group.name }
+            trigger = Trigger::GROUP_STATE_CHANGE
+          else
+            config = { 'itemName' => item.name }
+            trigger = Trigger::ITEM_STATE_CHANGE
+          end
+          logger.trace("Creating Changed Wait Change Trigger for #{config}")
+          trigger = append_trigger(trigger, config)
+          @trigger_delays[trigger.id] = TriggerDelay.new(to: to, from: from, duration: duration)
+        end
+
+        #
+        # Create a changed trigger
+        #
+        # @param [Object] item to create changed trigger on
+        # @param [String] from state to restrict trigger to
+        # @param [String] to state restrict trigger to
+        #
+        #
+        def create_changed_trigger(item, from, to)
+          trigger, config = case item
+                            when GroupItems then create_group_changed_trigger(item, from, to)
+                            when Thing then create_thing_changed_trigger(item, from, to)
+                            else create_item_changed_trigger(item, from, to)
+                            end
+          append_trigger(trigger, config)
+        end
+
+        #
+        # Create a changed trigger for a thing
+        #
+        # @param [Thing] thing to detected changed states on
+        # @param [String] from state to restrict trigger to
+        # @param [String] to state to restrict trigger to
+        #
+        # @return [Array<Hash,String>] first element is a String specifying trigger type
+        #  second element is a Hash configuring trigger
+        #
+        def create_thing_changed_trigger(thing, from, to)
+          trigger_for_thing(thing, Trigger::THING_CHANGE, to, from)
+        end
+
+        #
+        # Create a changed trigger for an item
+        #
+        # @param [Item] item to detected changed states on
+        # @param [String] from state to restrict trigger to
+        # @param [String] to to restrict trigger to
+        #
+        # @return [Array<Hash,String>] first element is a String specifying trigger type
+        #  second element is a Hash configuring trigger
+        #
+        def create_item_changed_trigger(item, from, to)
+          config = { 'itemName' => item.name }
+          config['state'] = to.to_s if to
+          config['previousState'] = from.to_s if from
+          trigger = Trigger::ITEM_STATE_CHANGE
+          [trigger, config]
+        end
+
+        #
+        # Create a changed trigger for group items
+        #
+        # @param [Group] group to detected changed states on
+        # @param [String] from state to restrict trigger to
+        # @param [String] to to restrict trigger to
+        #
+        # @return [Array<Hash,String>] first element is a String specifying trigger type
+        #  second element is a Hash configuring trigger
+        #
+        def create_group_changed_trigger(group, from, to)
+          config = { 'groupName' => group.group.name }
+          config['state'] = to.to_s if to
+          config['previousState'] = from.to_s if from
+          trigger = Trigger::GROUP_STATE_CHANGE
+          [trigger, config]
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/rules/triggers/channel.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'openhab/log/logger'
+require 'openhab/dsl/rules/triggers/trigger'
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # Channel triggers
+      #
+      module Triggers
+        include OpenHAB::Log
+
+        #
+        # Creates a channel trigger
+        #
+        # @param [Array] channels array to create triggers for on form of 'binding_id:type_id:thing_id#channel_id'
+        #   or 'channel_id' if thing is provided
+        # @param [thing] thing to create trigger for if not specified with the channel
+        # @param [String] triggered specific triggering condition to match for trigger
+        #
+        #
+        def channel(*channels, thing: nil, triggered: nil)
+          channels.flatten.each do |channel|
+            channel = [thing, channel].join(':') if thing
+            logger.trace("Creating channel trigger for channel(#{channel}), thing(#{thing}), trigger(#{triggered})")
+            [triggered].flatten.each do |trigger|
+              create_channel_trigger(channel, trigger)
+            end
+          end
+        end
+
+        private
+
+        #
+        # Create a trigger for a channel
+        #
+        # @param [Channel] channel to look for triggers
+        # @param [Trigger] trigger specific channel trigger to match
+        #
+        #
+        def create_channel_trigger(channel, trigger)
+          config = { 'channelUID' => channel }
+          config['event'] = trigger.to_s unless trigger.nil?
+          config['channelUID'] = channel
+          logger.trace("Creating Change Trigger for #{config}")
+          @triggers << Trigger.trigger(type: Trigger::CHANNEL_EVENT, config: config)
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/rules/triggers/command.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'openhab/log/logger'
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # Module holds rule triggers
+      #
+      module Triggers
+        include OpenHAB::Log
+
+        #
+        # Create a trigger for when an item or group receives a command
+        #
+        # The commands/commands parameters are replicated for DSL fluency
+        #
+        # @param [Array] items Array of items to create trigger for
+        # @param [Array] command commands to match for trigger
+        # @param [Array] commands commands to match for trigger
+        #
+        #
+        def received_command(*items, command: nil, commands: nil)
+          items.flatten.each do |item|
+            logger.trace("Creating received command trigger for item(#{item})"\
+                         "command(#{command}) commands(#{commands})")
+
+            # Combine command and commands, doing union so only a single nil will be in the combined array.
+            combined_commands = combine_commands(command, commands)
+            create_received_trigger(combined_commands, item)
+          end
+        end
+
+        private
+
+        #
+        # Create a received trigger based on item type
+        #
+        # @param [Array] commands to create trigger for
+        # @param [Object] item to create trigger for
+        #
+        #
+        def create_received_trigger(commands, item)
+          commands.each do |command|
+            if item.is_a? GroupItems
+              config, trigger = create_group_command_trigger(item)
+            else
+              config, trigger = create_item_command_trigger(item)
+            end
+            config['command'] = command.to_s unless command.nil?
+            append_trigger(trigger, config)
+          end
+        end
+
+        #
+        # Create trigger for item commands
+        #
+        # @param [Item] item to create trigger for
+        #
+        # @return [Array<Hash,Trigger>] first element is hash of trigger config properties
+        #   second element is trigger type
+        #
+        def create_item_command_trigger(item)
+          config = { 'itemName' => item.name }
+          trigger = Trigger::ITEM_COMMAND
+          [config, trigger]
+        end
+
+        #
+        # Create trigger for group items
+        #
+        # @param [Group] group to create trigger for
+        #
+        # @return [Array<Hash,Trigger>] first element is hash of trigger config properties
+        #   second element is trigger type
+        #
+        def create_group_command_trigger(group)
+          config = { 'groupName' => group.group.name }
+          trigger = Trigger::GROUP_COMMAND
+          [config, trigger]
+        end
+
+        #
+        # Combine command and commands into a single array
+        #
+        # @param [Array] command list of commands to trigger on
+        # @param [Array] commands list of commands to trigger on
+        #
+        # @return [Array] Combined flattened and compacted list of commands
+        #
+        def combine_commands(command, commands)
+          combined_commands = ([command] | [commands]).flatten
+
+          # If either command or commands has a value and one is nil, we need to remove nil from the array.
+          # If it is only now a single nil value, we leave the nil in place, so that we create a trigger
+          # That isn't looking for a specific command.
+          combined_commands = combined_commands.compact unless combined_commands.all?(&:nil?)
+          combined_commands
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/rules/triggers/cron.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require 'java'
+require 'openhab/dsl/time_of_day'
+
+module OpenHAB
+  module DSL
+    module Rules
+      #
+      # Cron type rules
+      #
+      module Triggers
+        java_import org.openhab.core.automation.util.TriggerBuilder
+        java_import org.openhab.core.config.core.Configuration
+
+        #
+        # Returns 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 [Hash] 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
+        # Rubocop check is disabled because YARD cannot process the method if placed in front of
+        #   the method definition
+        # rubocop:disable Style/AccessModifierDeclarations
+        module_function :cron_expression_map
+        # rubocop:enable Style/AccessModifierDeclarations
+
+        # @return [Hash] Map of days of the week from symbols to to OpenHAB cron strings
+        DAY_OF_WEEK_MAP = {
+          monday: 'MON',
+          tuesday: 'TUE',
+          wednesday: 'WED',
+          thursday: 'THU',
+          friday: 'FRI',
+          saturday: 'SAT',
+          sunday: 'SUN'
+        }.freeze
+
+        private_constant :DAY_OF_WEEK_MAP
+
+        # @return [Hash] Converts the DAY_OF_WEEK_MAP to map used by Cron Expression
+        DAY_OF_WEEK_EXPRESSION_MAP = DAY_OF_WEEK_MAP.transform_values { |v| cron_expression_map.merge(dow: v) }
+
+        private_constant :DAY_OF_WEEK_EXPRESSION_MAP
+
+        # @return [Hash] Create a set of cron expressions based on different time intervals
+        EXPRESSION_MAP = {
+          second: cron_expression_map,
+          minute: cron_expression_map.merge(second: '0'),
+          hour: cron_expression_map.merge(second: '0', minute: '0'),
+          day: cron_expression_map.merge(second: '0', minute: '0', hour: '0'),
+          week: cron_expression_map.merge(second: '0', minute: '0', hour: '0', dow: 'MON'),
+          month: cron_expression_map.merge(second: '0', minute: '0', hour: '0', dom: '1'),
+          year: cron_expression_map.merge(second: '0', minute: '0', hour: '0', dom: '1', month: '1')
+        }.merge(DAY_OF_WEEK_EXPRESSION_MAP)
+                         .freeze
+
+        private_constant :EXPRESSION_MAP
+
+        #
+        # Create a rule that executes at the specified interval
+        #
+        # @param [Object] value Symbol or Duration to execute this rule
+        # @param [Object] at TimeOfDay or String representing TimeOfDay in which to execute rule
+        #
+        #
+        def every(value, at: nil)
+          cron_expression = case value
+                            when Symbol then cron_from_symbol(value, at)
+                            when Java::JavaTime::Duration then cron_from_duration(value, at)
+                            else raise ArgumentExpression, 'Unknown interval'
+                            end
+          cron(cron_expression)
+        end
+
+        #
+        # Create a OpenHAB Cron trigger
+        #
+        # @param [String] expression OpenHAB style cron expression
+        #
+        def cron(expression)
+          @triggers << Trigger.trigger(type: Trigger::CRON, config: { 'cronExpression' => expression })
+        end
+
+        private
+
+        #
+        # Create a cron map from a duration
+        #
+        # @param [java::time::Duration] duration
+        # @param [Object] at TimeOfDay or String representing time of day
+        #
+        # @return [Hash] map describing cron expression
+        #
+        def cron_from_duration(duration, at)
+          raise ArgumentError, '"at" cannot be used with duration' if at
+
+          map_to_cron(duration_to_map(duration))
+        end
+
+        #
+        # Create a cron map from a symbol
+        #
+        # @param [Symbol] symbol
+        # @param [Object] at TimeOfDay or String representing time of day
+        #
+        # @return [Hash] map describing cron expression created from symbol
+        #
+        def cron_from_symbol(symbol, at)
+          expression_map = EXPRESSION_MAP[symbol]
+          expression_map = at_condition(expression_map, at) if at
+          map_to_cron(expression_map)
+        end
+
+        #
+        # Map cron expression to to cron string
+        #
+        # @param [Map] map of cron expression
+        #
+        # @return [String] OpenHAB cron string
+        #
+        def map_to_cron(map)
+          %i[second minute hour dom month dow].map { |field| map.fetch(field) }.join(' ')
+        end
+
+        #
+        # Convert a Java Duration to a map for the map_to_cron method
+        #
+        # @param duration [Java::JavaTime::Duration] The duration object
+        #
+        # @return [Hash] a map suitable for map_to_cron
+        #
+        def duration_to_map(duration)
+          if duration.to_millis_part.zero? && duration.to_nanos_part.zero? && duration.to_days.zero?
+            %i[second minute hour].each do |unit|
+              to_unit_part = duration.public_send("to_#{unit}s_part")
+              next unless to_unit_part.positive?
+
+              to_unit = duration.public_send("to_#{unit}s")
+              break unless to_unit_part == to_unit
+
+              return EXPRESSION_MAP[unit].merge(unit => "*/#{to_unit}")
+            end
+          end
+          raise ArgumentError, "Cron Expression not supported for duration: #{duration}"
+        end
+
+        #
+        # If an at time is provided, parse that and merge the new fields into the expression.
+        #
+        # @param [<Type>] expression_map <description>
+        # @param [<Type>] at_time <description>
+        #
+        # @return [<Type>] <description>
+        #
+        def at_condition(expression_map, at_time)
+          if at_time
+            tod = at_time.is_a?(TimeOfDay::TimeOfDay) ? at_time : TimeOfDay::TimeOfDay.parse(at_time)
+            expression_map = expression_map.merge(hour: tod.hour, minute: tod.minute, second: tod.second)
+          end
+          expression_map
+        end
+      end
+    end
+  end
+end