openhab-jrubyscripting 5.0.0.rc5 → 5.0.0.rc6

data/lib/openhab/dsl/rules/builder.rb

@@ -14,15 +14,18 @@ end
 module OpenHAB
   module DSL
     #
-    # Creates and manages OpenHAB Rules
+    # Creates and manages openHAB Rules
     #
     module Rules
-      # A rules builder allows you to create OpenHAB rules.
+      # A rules builder allows you to create openHAB rules.
       #
       # Note that all methods on this module are also availabe directly on {OpenHAB::DSL}.
       #
       class Builder
         include Terse
+        include Core::EntityLookup
+
+        self.create_dummy_items = true
 
         # @return [org.openhab.core.automation.RuleProvider]
         attr_reader :provider
@@ -34,21 +37,24 @@ module OpenHAB
         #
         # Create a new rule
         #
+        # The rule must have at least one trigger and one execution block.
+        # To create a "script" without any triggers, use {#script}.
+        #
         # @param [String] name The rule name
-        # @yield Block executed in the context of a {Rules::Builder}
-        # @yieldparam [Rules::Builder] rule
+        # @yield Block executed in the context of a {Rules::BuilderDSL}
+        # @yieldparam [Rules::BuilderDSL] rule
         #   Optional parameter to access the rule configuration from within execution blocks and guards.
-        # @return [Rule]
+        # @return [Core::Rules::Rule, nil] The rule object, or nil if no rule was created.
         #
-        # @see OpenHAB::DSL::Rules::Builder Rule builder for details on rule triggers, guards and execution blocks
+        # @see OpenHAB::DSL::Rules::BuilderDSL Rule BuilderDSL for details on rule triggers, guards and execution blocks
         # @see Rules::Terse Terse Rules
         #
         # @example
         #   require "openhab/dsl"
         #
         #   rule "name" do
-        #     <zero or more triggers>
-        #     <zero or more execution blocks>
+        #     <one or more triggers>
+        #     <one or more execution blocks>
         #     <zero or more guards>
         #   end
         #
@@ -85,7 +91,7 @@ module OpenHAB
         # @param [String] name A descriptive name
         # @param [String] id The script's ID
         # @yield [] Block executed when the script is executed.
-        # @return [Rule]
+        # @return [Core::Rules::Rule]
         #
         def script(name = nil, id: nil, script: nil, &block)
           raise ArgumentError, "Block is required" unless block
@@ -108,7 +114,7 @@ module OpenHAB
       end
 
       #
-      # Rule configuration for OpenHAB Rules engine
+      # Rule configuration for openHAB Rules engine
       #
       class BuilderDSL
         include Core::EntityLookup
@@ -117,6 +123,8 @@ module OpenHAB
         extend Property
         extend Forwardable
 
+        self.create_dummy_items = true
+
         delegate %i[triggers trigger_conditions attachments] => :@rule_triggers
 
         # @!visibility private
@@ -259,7 +267,7 @@ module OpenHAB
         #
         # @example
         #   rule 'Delay sleeps between execution elements' do
-        #     on_start
+        #     on_load
         #     run { logger.info("Sleeping") }
         #     delay 5.seconds
         #     run { logger.info("Awake") }
@@ -267,7 +275,7 @@ module OpenHAB
         #
         # @example Like other execution blocks, multiple can exist in a single rule.
         #   rule 'Multiple delays can exist in a rule' do
-        #     on_start
+        #     on_load
         #     run { logger.info("Sleeping") }
         #     delay 5.seconds
         #     run { logger.info("Sleeping Again") }
@@ -277,7 +285,7 @@ module OpenHAB
         #
         # @example You can use Ruby code in your rule across multiple execution blocks like a run and a delay.
         #   rule 'Dim a switch on system startup over 100 seconds' do
-        #     on_start
+        #     on_load
         #     100.times do
         #       run { DimmerSwitch.dim }
         #       delay 1.second
@@ -302,7 +310,7 @@ module OpenHAB
         #
         # @example
         #   rule 'Turn switch ON or OFF based on value of another switch' do
-        #     on_start
+        #     on_load
         #     run { TestSwitch << ON }
         #     otherwise { TestSwitch << OFF }
         #     only_if { OtherSwitch.on? }
@@ -425,28 +433,28 @@ module OpenHAB
         #
         # @example String of {LocalTime}
         #   rule 'Log an entry if started between 3:30:04 and midnight using strings' do
-        #     on_start
+        #     on_load
         #     run { logger.info ("Started at #{LocalTime.now}")}
         #     between '3:30:04'..LocalTime::MIDNIGHT
         #   end
         #
         # @example {LocalTime}
         #   rule 'Log an entry if started between 3:30:04 and midnight using LocalTime objects' do
-        #     on_start
+        #     on_load
         #     run { logger.info ("Started at #{LocalTime.now}")}
         #     between LocalTime.of(3, 30, 4)..LocalTime::MIDNIGHT
         #   end
         #
         # @example String of {MonthDay}
         #   rule 'Log an entry if started between March 9th and April 10ths' do
-        #     on_start
+        #     on_load
         #     run { logger.info ("Started at #{Time.now}")}
         #     between '03-09'..'04-10'
         #   end
         #
         # @example {MonthDay}
         #   rule 'Log an entry if started between March 9th and April 10ths' do
-        #     on_start
+        #     on_load
         #     run { logger.info ("Started at #{Time.now}")}
         #     between MonthDay.of(03,09)..'04-06'
         #   end
@@ -533,8 +541,8 @@ module OpenHAB
           @rule_triggers = RuleTriggers.new
           @caller = caller_binding.eval "self"
           @ruby_triggers = []
+          @on_load_id = nil
           enabled(true)
-          on_start(false)
           tags([])
         end
 
@@ -789,19 +797,19 @@ module OpenHAB
           # for is a reserved word in ruby, so use local_variable_get :for
           duration = binding.local_variable_get(:for)
 
+          @ruby_triggers << [:changed, items, { to: to, from: from, duration: duration }]
+
           from = [nil] if from.nil?
           to = [nil] if to.nil?
-
-          @ruby_triggers << [:changed, items, { to: to, from: from, duration: duration }]
           items.each do |item|
             case item
             when Core::Things::Thing,
                  Core::Things::ThingUID,
-                 Core::Items::GenericItem,
+                 Core::Items::Item,
                  Core::Items::GroupItem::Members
               nil
             else
-              raise ArgumentError, "items must be a GenericItem, GroupItem::Members, Thing, or ThingUID"
+              raise ArgumentError, "items must be an Item, GroupItem::Members, Thing, or ThingUID"
             end
 
             logger.trace("Creating changed trigger for entity(#{item}), to(#{to.inspect}), from(#{from.inspect})")
@@ -818,7 +826,7 @@ module OpenHAB
         # Create a cron trigger
         #
         # @overload cron(expression, attach: nil)
-        #   @param [String, nil] expression [OpenHAB style cron expression](https://www.openhab.org/docs/configuration/rules-dsl.html#time-based-triggers)
+        #   @param [String, nil] expression [openHAB style cron expression](https://www.openhab.org/docs/configuration/rules-dsl.html#time-based-triggers)
         #   @param [Object] attach object to be attached to the trigger
         #
         #   @example Using a cron expression
@@ -962,45 +970,116 @@ module OpenHAB
         end
 
         #
-        # Run this rule when the script is loaded.
+        # Creates a trigger that executes when the script is loaded
         #
-        # Execute the rule on OpenHAB start up and whenever the script is
-        # reloaded. This is useful to perform initialization routines,
-        # especially when combined with other triggers.
+        # Execute the rule whenever the script is first loaded, including on openHAB start up,
+        # and on subsequent reloads on file modifications.
+        # This is useful to perform initialization routines, especially when combined with other triggers.
         #
-        # @param [true, false] run_on_start Run this rule on start, defaults to True
-        # @param [Object] attach object to be attached to the trigger
+        # @param [Object] attach Object to be attached to the trigger
         # @return [void]
         #
         # @example
-        #   rule "startup rule" do
-        #     on_start
+        #   rule "script startup rule" do
+        #     on_load
         #     run do
         #       <calculate some item state>
         #     end
         #   end
         #
         # @example
-        #   rule 'Ensure all security lights are on' do
-        #     on_start
+        #   rule "Ensure all security lights are on" do
+        #     on_load
         #     run { Security_Lights.on }
         #   end
         #
-        # rubocop:disable Style/OptionalBooleanParameter
-        def on_start(run_on_start = true, attach: nil)
-          @on_start = Struct.new(:enabled, :attach).new(run_on_start, attach)
+        def on_load(attach: nil)
+          # prevent overwriting @on_load_id
+          raise ArgumentError, "on_load can only be used once within a rule" if @on_load_id
+
+          @on_load_id = SecureRandom.uuid
+          attachments[@on_load_id] = attach
+        end
+
+        #
+        # Creates a trigger that executes when openHAB reaches a certain start level
+        #
+        # This will only trigger once during openHAB start up. It won't trigger on script reloads.
+        #
+        # @param [Integer,:rules,:ruleengine,:ui,:things,:complete] at_level
+        #   Zero or more start levels. Note that Startlevels less than 40 are not available as triggers
+        #   because the rule engine needs to start up first before it can execute any rules
+        #
+        #   | Symbol        | Start Level |
+        #   | ------------- | ----------- |
+        #   | `:osgi`       | 10          |
+        #   | `:model`      | 20          |
+        #   | `:state`      | 30          |
+        #   | `:rules`      | 40          |
+        #   | `:ruleengine` | 50          |
+        #   | `:ui`         | 70          |
+        #   | `:things`     | 80          |
+        #   | `:complete`   | 100         |
+        # @param [Array<Integer,:rules,:ruleengine,:ui,:things,:complete>] at_levels Fluent alias for `at_level`
+        # @param [Object] attach Object to be attached to the trigger
+        # @return [void]
+        #
+        # @example
+        #   rule "Trigger at openHAB system start" do
+        #     on_start # trigger at the default startlevel 100
+        #     run { logger.info "openHAB start up complete." }
+        #   end
+        #
+        # @example Trigger at a specific start level
+        #   rule "Trigger after things are loaded" do
+        #     on_start at_level: :things
+        #     run { logger.info "Things are ready!" }
+        #   end
+        #
+        # @example Trigger at multiple levels
+        #   rule "Multiple start up triggers" do
+        #     on_start at_levels: %i[ui things complete]
+        #     run do |event|
+        #       logger.info "openHAB startlevel has reached level #{event.startlevel}"
+        #     end
+        #   end
+        #
+        # @see https://www.openhab.org/docs/configuration/rules-dsl.html#system-based-triggers System based triggers
+        #
+        def on_start(at_level: nil, at_levels: nil, attach: nil)
+          levels = Array.wrap(at_level) | Array.wrap(at_levels)
+          levels = [100] if levels.empty?
+
+          levels.map! do |level|
+            next level unless level.is_a?(Symbol)
+
+            begin
+              klass = org.openhab.core.service.StartLevelService.java_class
+              klass.declared_field("STARTLEVEL_#{level.upcase}").get_int(klass)
+            rescue java.lang.NoSuchFieldException
+              raise ArgumentError, "Invalid symbol for at_level: :#{level}"
+            end
+          end
+
+          @ruby_triggers << [:on_start, levels]
+          levels.each do |level|
+            logger.warn "Rule engine doesn't start until start level 40" if level < 40
+            config = { startlevel: level }
+            logger.trace("Creating a SystemStartlevelTrigger with startlevel=#{level}")
+            Triggers::Trigger.new(rule_triggers: @rule_triggers)
+                             .append_trigger(type: "core.SystemStartlevelTrigger", config: config, attach: attach)
+          end
         end
-        # rubocop:enable Style/OptionalBooleanParameter
 
         #
-        # Create a trigger for when an item or group receives a command
+        # Creates a trigger for when an item or group receives a command.
         #
         # The command/commands parameters are replicated for DSL fluency.
         #
         # The `event` passed to run blocks will be an
         # {Core::Events::ItemCommandEvent}.
         #
-        # @param [GenericItem, GroupItem::Members] items Items to create trigger for
+        # @param [Item, GroupItem::Members] items Items to create trigger for
         # @param [Core::TypesCommand, Array<Command>, Range, Proc] command commands to match for trigger
         # @param [Array<Command>, Range, Proc] commands Fluent alias for `command`
         # @param [Object] attach object to be attached to the trigger
@@ -1072,11 +1151,11 @@ module OpenHAB
 
           items.each do |item|
             case item
-            when Core::Items::GenericItem,
+            when Core::Items::Item,
                  Core::Items::GroupItem::Members
               nil
             else
-              raise ArgumentError, "items must be a GenericItem or GroupItem::Members"
+              raise ArgumentError, "items must be an Item or GroupItem::Members"
             end
             commands.each do |cmd|
               logger.trace "Creating received command trigger for items #{item.inspect} and commands #{cmd.inspect}"
@@ -1194,7 +1273,7 @@ module OpenHAB
         # {Core::Events::ThingStatusInfoEvent} depending on if the triggering
         # element was an item or a thing.
         #
-        # @param [GenericItem, GroupItem::Members, Thing] items
+        # @param [Item, GroupItem::Members, Thing] items
         #   Objects to create trigger for.
         # @param [State, Array<State>, Range, Proc, Symbol, String] to
         #   Only execute rule if the state matches `to` state(s). If the
@@ -1271,11 +1350,11 @@ module OpenHAB
             case item
             when Core::Things::Thing,
                  Core::Things::ThingUID,
-                 Core::Items::GenericItem,
+                 Core::Items::Item,
                  Core::Items::GroupItem::Members
               nil
             else
-              raise ArgumentError, "items must be a GenericItem, GroupItem::Members, Thing, or ThingUID"
+              raise ArgumentError, "items must be an Item, GroupItem::Members, Thing, or ThingUID"
             end
 
             logger.trace("Creating updated trigger for item(#{item}) to(#{to})")
@@ -1317,7 +1396,7 @@ module OpenHAB
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
         #
-        # @example Watch `items` directory inside of the OpenHAB configuration path and log any changes.
+        # @example Watch `items` directory inside of the openHAB configuration path and log any changes.
         #   rule 'watch directory' do
         #     watch OpenHAB::Core.config_folder / 'items'
         #     run { |event| logger.info("#{event.path.basename} - #{event.type}") }
@@ -1358,36 +1437,6 @@ module OpenHAB
 
         # @!endgroup
 
-        #
-        # Checks if this rule should run on start
-        #
-        # @return [true, false] True if rule should run on start, false otherwise.
-        #
-        def on_start?
-          @on_start.enabled
-        end
-
-        #
-        # Get the optional start attachment
-        #
-        # @return [Object] optional user provided attachment to the on_start method
-        #
-        # @!visibility private
-        def start_attachment
-          @on_start.attach
-        end
-
-        # @!visibility private
-        #
-        # Run the supplied block inside the object instance of the object that created the rule
-        #
-        # @yield [] Block executed in context of the object creating the rule
-        #
-        #
-        def my(&block)
-          @caller.instance_eval(&block)
-        end
-
         #
         # @return [String]
         #
@@ -1396,7 +1445,7 @@ module OpenHAB
             #<OpenHAB::DSL::Rules::Builder: #{uid}
             triggers=#{triggers.inspect},
             run blocks=#{run.inspect},
-            on_start=#{on_start?},
+            on_load=#{!@on_load_id.nil?},
             Trigger Conditions=#{trigger_conditions.inspect},
             Trigger UIDs=#{triggers.map(&:id).inspect},
             Attachments=#{attachments.inspect}
@@ -1419,7 +1468,7 @@ module OpenHAB
           added_rule.actions.first.configuration.put("type", "application/x-ruby")
           added_rule.actions.first.configuration.put("script", script) if script
 
-          rule.execute(nil, { "event" => Struct.new(:attachment).new(start_attachment) }) if on_start?
+          rule.execute(nil, { "module" => @on_load_id }) if @on_load_id
           added_rule
         end
 
@@ -1456,7 +1505,7 @@ module OpenHAB
         # @return [true,false] True if rule has triggers, false otherwise
         #
         def triggers?
-          on_start? || !triggers.empty?
+          @on_load_id || !triggers.empty?
         end
 
         #

data/lib/openhab/dsl/rules/guard.rb

@@ -34,7 +34,7 @@ module OpenHAB
         #
         # Checks if a guard should run
         #
-        # @param [OpenHAB Trigger Event] event OpenHAB Trigger Event
+        # @param [Object] event openHAB Trigger Event
         #
         # @return [true,false] True if guard is satisfied, false otherwise
         #
@@ -51,7 +51,7 @@ module OpenHAB
         #
         # @param [Array] conditions to check
         # @param [Symbol] check_type type of check to perform (:only_if or :not_if)
-        # @param [Event] event OpenHAB event to see if it satisfies the guard
+        # @param [Event] event openHAB event to see if it satisfies the guard
         #
         # @return [true,false] True if guard is satisfied, false otherwise
         #
@@ -70,7 +70,7 @@ module OpenHAB
         # Execute the guard check
         #
         # @param [Symbol] check_type :only_if or :not_if to check
-        # @param [OpenHAB Event] event event to check if meets guard
+        # @param [Object] event event to check if meets guard
         # @param [Array<Item>] items to check if satisfy criteria
         # @param [Array] procs to check if satisfy criteria
         #
@@ -87,7 +87,7 @@ module OpenHAB
         #
         # Check not_if guard
         #
-        # @param [OpenHAB Event] event to check if meets guard
+        # @param [Object] event to check if meets guard
         # @param [Array<Item>] items to check if satisfy criteria
         # @param [Array] procs to check if satisfy criteria
         #
@@ -100,7 +100,7 @@ module OpenHAB
         #
         # Check only_if guard
         #
-        # @param [OpenHAB Event] event to check if meets guard
+        # @param [Object] event to check if meets guard
         # @param [Array<Item>] items to check if satisfy criteria
         # @param [Array] procs to check if satisfy criteria
         #

data/lib/openhab/dsl/rules/name_inference.rb

@@ -18,6 +18,7 @@ module OpenHAB
           "core.ItemCommandTrigger",
           "core.ItemStateChangeTrigger",
           "core.ItemStateUpdateTrigger",
+          "core.SystemStartlevelTrigger",
           Triggers::Cron::CRON_TRIGGER_MODULE_ID
         ].freeze
         private_constant :KNOWN_TRIGGER_TYPES
@@ -61,6 +62,8 @@ module OpenHAB
               infer_rule_name_from_channel_link_trigger(trigger)
             when :thing_added, :thing_removed, :thing_updated
               infer_rule_name_from_thing_trigger(trigger)
+            when :on_start
+              infer_rule_name_from_on_start_trigger(items)
             end
           end
 
@@ -122,6 +125,22 @@ module OpenHAB
             }[trigger]
           end
 
+          # formulate a readable rule name from an on_start trigger
+          def infer_rule_name_from_on_start_trigger(levels)
+            levels = levels.map { |level| "#{level} (#{start_level_description(level)})" }
+            levels = format_array(levels)
+            "System Start Level reached #{levels}"
+          end
+
+          def start_level_description(level)
+            klass = org.openhab.core.service.StartLevelService.java_class
+            start_level_type = klass.declared_field("STARTLEVEL_OSGI").type
+            klass.declared_fields
+                 .select { |field| field.type == start_level_type && field.name.start_with?("STARTLEVEL_") }
+                 .find { |field| field.get_int(klass) == level }
+                 .name.split("_", 2).last.downcase
+          end
+
           # format an array of words that will be the beginning of a sentence
           def format_beginning_of_sentence_array(array)
             result = format_array(array)
@@ -146,7 +165,7 @@ module OpenHAB
             return array[0] if array.length == 1
             return "#{array[0]} or #{array[1]}" if array.length == 2
 
-            "any of #{array.join(", ")}"
+            "#{array[0..-2].join(", ")}, or #{array[-1]}"
           end
         end
       end

data/lib/openhab/dsl/rules/rule_triggers.rb

@@ -10,7 +10,7 @@ module OpenHAB
   module DSL
     module Rules
       #
-      # Rule configuration for OpenHAB Rules engine
+      # Rule configuration for openHAB Rules engine
       #
       # @!visibility private
       class RuleTriggers
@@ -39,7 +39,7 @@ module OpenHAB
         # @param [Map] config map describing trigger configuration
         # @param [Object] attach object to be attached to the trigger
         #
-        # @return [Trigger] OpenHAB trigger
+        # @return [org.openhab.core.automation.Trigger] openHAB trigger
         #
         def append_trigger(type:, config:, attach: nil, conditions: nil)
           config.transform_keys!(&:to_s)
@@ -57,7 +57,7 @@ module OpenHAB
         # @param [String] type of trigger
         # @param [Map] config map
         #
-        # @return [OpenHAB Trigger] configured by type and supplied config
+        # @return [org.openhab.core.automation.Trigger] configured by type and supplied config
         #
         def self.trigger(type:, config:)
           logger.trace("Creating trigger of type '#{type}' config: #{config}")

data/lib/openhab/dsl/rules/terse.rb

@@ -56,6 +56,7 @@ module OpenHAB
         def_terse_rule(:thing_updated)
         def_terse_rule(:thing_removed)
         def_terse_rule(:updated)
+        def_terse_rule(:on_start)
       end
     end
   end

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

@@ -16,13 +16,13 @@ module OpenHAB
           #
           # Create the trigger
           #
-          # @param [Object] item item to create trigger for
-          # @param [Item State] from state to restrict trigger to
-          # @param [Item State] to state to restrict trigger to
-          # @param [Duration, nil] duration ruration to delay trigger until to state is met
+          # @param [Core::Items::Item, Core::Items::GroupItem::Members] item item to create trigger for
+          # @param [Core::Types::State, Array<Core::Types::State>, Range, Proc] from state to restrict trigger to
+          # @param [Core::Types::State, Array<Core::Types::State>, Range, Proc] to state to restrict trigger to
+          # @param [Duration, nil] duration duration to delay trigger until to state is met
           # @param [Object] attach object to be attached to the trigger
           #
-          # @return [Trigger] OpenHAB triggers
+          # @return [org.openhab.core.automation.Trigger] openHAB triggers
           #
           def trigger(item:, from:, to:, duration:, attach:)
             if duration
@@ -50,13 +50,15 @@ module OpenHAB
           #
           # 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 [Core::Items::Item, Core::Items::GroupItem::Members] item to create trigger delay for
           # @param [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
+          # @param [Core::Types::State, Array<Core::Types::State>, Range, Proc] to
+          #   State item or group needs to change to
+          # @param [Core::Types::State, Array<Core::Types::State>, Range, Proc] from
+          #   State item or group needs to be coming from
           # @param [Object] attach object to be attached to the trigger
           #
-          # @return [Trigger] OpenHAB trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def wait_trigger(item:, duration:, to: nil, from: nil, attach: nil)
             item_name = item.respond_to?(:name) ? item.name : item.to_s
@@ -68,11 +70,11 @@ module OpenHAB
 
           #
           # Creates a trigger with a range condition on either 'from' or 'to' field
-          # @param [Object] item to create changed trigger on
-          # @param [Object] from state to restrict trigger to
-          # @param [Object] to state restrict trigger to
+          # @param [Core::Items::Item, Core::Items::GroupItem::Members] item to create changed trigger on
+          # @param [Range] from state to restrict trigger to
+          # @param [Range] to state restrict trigger to
           # @param [Object] attach object to be attached to the trigger
-          # @return [Trigger] OpenHAB trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def range_trigger(item:, from:, to:, attach:)
             from, to = Conditions::Proc.range_procs(from, to)
@@ -81,11 +83,11 @@ module OpenHAB
 
           #
           # Creates a trigger with a proc condition on either 'from' or 'to' field
-          # @param [Object] item to create changed trigger on
-          # @param [Object] from state to restrict trigger to
-          # @param [Object] to state restrict trigger to
+          # @param [Core::Items::Item, Core::Items::GroupItem::Members] item to create changed trigger on
+          # @param [Proc] from state to restrict trigger to
+          # @param [Proc] to state restrict trigger to
           # @param [Object] attach object to be attached to the trigger
-          # @return [Trigger] OpenHAB trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def proc_trigger(item:, from:, to:, attach:)
             # swap from/to w/ nil if from/to is a proc
@@ -100,10 +102,11 @@ module OpenHAB
           #
           # Create a changed trigger
           #
-          # @param [Object] item to create changed trigger on
-          # @param [Object] from state to restrict trigger to
-          # @param [Object] to state restrict trigger to
+          # @param [Core::Items::Item, Core::Items::GroupItem::Members] item to create changed trigger on
+          # @param [Core::Items::State, Array<Core::Items::State>] from state to restrict trigger to
+          # @param [Core::Items::State, Array<Core::Items::State>] to state restrict trigger to
           # @param [Object] attach object to be attached to the trigger
+          # @return [org.openhab.core.automation.Trigger]
           #
           def changed_trigger(item:, from:, to:, attach: nil, conditions: nil)
             type, config = case item
@@ -121,7 +124,7 @@ module OpenHAB
           #
           # Create a changed trigger for a thing
           #
-          # @param [Thing] thing to detected changed states on
+          # @param [Core::Things::Thing] thing to detected changed states on
           # @param [String] from state to restrict trigger to
           # @param [String] to state to restrict trigger to
           #
@@ -152,7 +155,7 @@ module OpenHAB
           #
           # Create a changed trigger for group items
           #
-          # @param [Group] group to detected changed states on
+          # @param [GroupItem] group to detected changed states on
           # @param [String] from state to restrict trigger to
           # @param [String] to to restrict trigger to
           #
@@ -160,7 +163,7 @@ module OpenHAB
           #  second element is a Hash configuring trigger
           #
           def group(group:, from:, to:)
-            config = { "groupName" => group.group.name }
+            config = { "groupName" => group.name }
             config["state"] = to.to_s if to
             config["previousState"] = from.to_s if from
             [GROUP_STATE_CHANGE, config]