openhab-scripting 5.10.0 → 5.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: acf8ae7ed285c32bb11070e6ae64c54b9687dae7883c272be4a9ad30f399ed8c
-  data.tar.gz: 8820ac3849f07734843d2863ff483fbde70bfe56c41981f2d48ec2e8c7bd73a8
+  metadata.gz: 35d0d28ba4dd272f12cd989761c2d615836d25dbafbc2af2b60692f8a535d5c1
+  data.tar.gz: 4d51dd07a43f5ff7a7ad43bc66cbb1d63b320486a82036d1a8cbfb22412a061b
 SHA512:
-  metadata.gz: ab2e153c20c4d81b4b4b5b7d3025d1f49812099ea1040eba85b03f6fc8ce4217d84a3204e1c0917ed53c8386220b25da7d1da4bc367b51459ef74d67a52d7d44
-  data.tar.gz: 0bdc096799e02f344f7d24c218af6ed045840c9a87ab890e81a339896801c53c6e18a6dabafd060e2c18023b69da8fdb4df9d3d58fcab3917baba6274fe992eb
+  metadata.gz: 76c075f22df43c0ecfe37775e297f496d2f55fe60e6da95bbece311d92fe3e37e50d867a23f6f52c3ebeb690771e7eb5512c357ca3b0745d83d03a8df892cad7
+  data.tar.gz: 93eb532732729b91437a669fbbe9b0b024397332faa435c82ebe17d50c4ea4a29576108c819010c0a497a5912d74eaa95e87fc0d98b01f9fa0987fbb52b5fa7b

data/lib/openhab/core/events/channel_triggered_event.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.thing.events.ChannelTriggeredEvent
+
+      #
+      # {AbstractEvent} sent when a channel triggers.
+      #
+      class ChannelTriggeredEvent < AbstractEvent
+        extend Forwardable
+
+        # @!attribute [r] channel_uid
+        # @return [Things::ChannelUID] The UID of the {Things::Channel Channel} that triggered this event.
+        alias_method :channel_uid, :get_channel
+
+        # @!attribute [r] channel
+        # @return [Things::Channel, nil] The channel that triggered this event.
+
+        # @!attribute [r] thing
+        # @return [Things::Thing, nil] The thing that triggered this event.
+        def_delegators :channel_uid, :thing, :channel
+
+        # @!attribute [r] event
+        # @return [String] The event data
+      end
+    end
+  end
+end

data/lib/openhab/core/events/item_state_updated_event.rb

@@ -5,17 +5,18 @@ require_relative "item_state_event"
 module OpenHAB
   module Core
     module Events
-      begin
+      # @deprecated OH3.4 if guard only needed in OH 3.4
+      if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
         java_import org.openhab.core.items.events.ItemStateUpdatedEvent
 
         #
         # {AbstractEvent} sent when an item's state has updated.
         #
+        # @since openHAB 4.0
+        #
         class ItemStateUpdatedEvent < ItemEvent
           include ItemState
         end
-      rescue NameError
-        # @deprecated OH3.4 OH3 will raise an error ItemStateUpdatedEvent is only in OH4
       end
     end
   end

data/lib/openhab/core/items/dimmer_item.rb

@@ -102,7 +102,7 @@ module OpenHAB
         #
         def dim(amount = 1)
           target = [state&.-(amount), 0].compact.max
-          command(target)
+          command!(target)
           target
         end
 
@@ -121,7 +121,7 @@ module OpenHAB
         #
         def brighten(amount = 1)
           target = [state&.+(amount), 100].compact.min
-          command(target)
+          command!(target)
           target
         end
 

data/lib/openhab/core/items/generic_item.rb

@@ -128,15 +128,19 @@ module OpenHAB
         # Send a command to this item
         #
         # When this method is chained after the {OpenHAB::DSL::Items::Ensure::Ensurable#ensure ensure}
-        # method, or issued inside an {OpenHAB::DSL.ensure_states ensure_states} block,
+        # method, or issued inside an {OpenHAB::DSL.ensure_states ensure_states} block, or after
+        # {OpenHAB::DSL.ensure_states! ensure_states!} have been called,
         # the command will only be sent if the item is not already in the same state.
         #
+        # The similar method `command!`, however, will always send the command regardless of the item's state.
+        #
         # @param [Command] command command to send to the item
         # @return [self, nil] nil when `ensure` is in effect and the item was already in the same state,
         #   otherwise the item.
         #
         # @see DSL::Items::TimedCommand#command Timed Command
         # @see OpenHAB::DSL.ensure_states ensure_states
+        # @see OpenHAB::DSL.ensure_states! ensure_states!
         # @see DSL::Items::Ensure::Ensurable#ensure ensure
         #
         def command(command)
@@ -145,6 +149,7 @@ module OpenHAB
           $events.send_command(self, command)
           Proxy.new(self)
         end
+        alias_method :command!, :command
 
         # not an alias to allow easier stubbing and overriding
         def <<(command)
@@ -170,6 +175,7 @@ module OpenHAB
           $events.post_update(self, state)
           Proxy.new(self)
         end
+        alias_method :update!, :update
 
         # @!visibility private
         def format_command(command)

data/lib/openhab/core/items/player_item.rb

@@ -39,18 +39,35 @@ module OpenHAB
         #   Send the {PLAY} command to the item
         #   @return [PlayerItem] `self`
 
+        # @!method play!
+        #   Send the {PLAY} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [PlayerItem] `self`
+
         # @!method pause
         #   Send the {PAUSE} command to the item
         #   @return [PlayerItem] `self`
 
+        # @!method pause!
+        #   Send the {PAUSE} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [PlayerItem] `self`
+
         # @!method rewind
         #   Send the {REWIND} command to the item
         #   @return [PlayerItem] `self`
 
+        # @!method rewind!
+        #   Send the {REWIND} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [PlayerItem] `self`
+
         # @!method fast_forward
         #   Send the {FASTFORWARD} command to the item
         #   @return [PlayerItem] `self`
 
+        # @!method fast_forward!
+        #   Send the {FASTFORWARD} command to the item, even when
+        #     {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [PlayerItem] `self`
+
         # @!method next
         #   Send the {NEXT} command to the item
         #   @return [PlayerItem] `self`

data/lib/openhab/core/items/rollershutter_item.rb

@@ -41,10 +41,18 @@ module OpenHAB
         #   Send the {UP} command to the item
         #   @return [RollershutterItem] `self`
 
+        # @!method up!
+        #   Send the {UP} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [RollershutterItem] `self`
+
         # @!method down
         #   Send the {DOWN} command to the item
         #   @return [RollershutterItem] `self`
 
+        # @!method down!
+        #   Send the {DOWN} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [RollershutterItem] `self`
+
         # @!method stop
         #   Send the {STOP} command to the item
         #   @return [RollershutterItem] `self`

data/lib/openhab/core/items/semantics/enumerable.rb

@@ -101,6 +101,15 @@ module Enumerable
     self if count { |i| i.command(command) }.positive?
   end
 
+  # Send a command to every item in the collection, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+  # @return [self]
+  def command!(command)
+    # We cannot alias this to #command above, otherwise it will call
+    # DSL::Items::Ensure::Item#command which checks for ensure_states
+    each { |i| i.command!(command) }
+    self
+  end
+
   # Update the state of every item in the collection
   # @return [self, nil] nil when `ensure` is in effect and all the items were already in the same state,
   #   otherwise self
@@ -108,6 +117,16 @@ module Enumerable
     self if count { |i| i.update(state) }.positive?
   end
 
+  # Update the state of every item in the collection, even when
+  #   {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+  # @return [self]
+  def update!(state)
+    # We cannot alias this to #update above, otherwise it will call
+    # DSL::Items::Ensure::Item#update which checks for ensure_states
+    each { |i| i.update!(state) }
+    self
+  end
+
   # @!method refresh
   #   Send the {REFRESH} command to every item in the collection
   #   @return [self]

data/lib/openhab/core/items/switch_item.rb

@@ -50,9 +50,9 @@ module OpenHAB
         # @return [self]
         #
         def toggle
-          return on unless state?
+          return on! unless state?
 
-          command(!state)
+          command!(!state)
         end
 
         # @!method on?
@@ -67,9 +67,17 @@ module OpenHAB
         #   Send the {ON} command to the item
         #   @return [SwitchItem] `self`
 
+        # @!method on!
+        #   Send the {ON} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [SwitchItem] `self`
+
         # @!method off
         #   Send the {OFF} command to the item
         #   @return [SwitchItem] `self`
+
+        # @!method off!
+        #   Send the {OFF} command to the item, even when {OpenHAB::DSL.ensure_states! ensure_states!} is in effect.
+        #   @return [SwitchItem] `self`
       end
     end
   end

data/lib/openhab/core/items.rb

@@ -60,19 +60,43 @@ module OpenHAB
             command = Types::COMMAND_ALIASES[value.to_s]
             next if klass.instance_methods.include?(command)
 
-            logger.trace("Defining #{klass}##{command} for #{value}")
-            klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
-              ruby2_keywords def #{command}(*args, &block)  # ruby2_keywords def on(*args, &block)
-                command(#{value}, *args, &block)            #   command(ON, *args, &block)
-              end                                           # end
-            RUBY
+            if value.is_a?(Types::State)
+              logger.trace("Defining #{klass}/Enumerable##{command}/#{command}! for #{value}")
 
-            logger.trace("Defining Enumerable##{command} for #{value}")
-            Enumerable.class_eval <<~RUBY, __FILE__, __LINE__ + 1
-              def #{command}        # def on
-                each(&:#{command})  #   each(&:on)
-              end                   # end
-            RUBY
+              klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                ruby2_keywords def #{command}(*args, &block)   # ruby2_keywords def on(*args, &block)
+                  command(#{value}, *args, &block)             #   command(ON, *args, &block)
+                end                                            # end
+                                                               #
+                ruby2_keywords def #{command}!(*args, &block)  # ruby2_keywords def on!(*args, &block)
+                  command!(#{value}, *args, &block)            #   command!(ON, *args, &block)
+                end                                            # end
+              RUBY
+
+              Enumerable.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                def #{command}         # def on
+                  each(&:#{command})   #   each(&:on)
+                end                    # end
+                                       #
+                def #{command}!        # def on!
+                  each(&:#{command}!)  #   each(&:on!)
+                end                    # end
+              RUBY
+            else
+              logger.trace("Defining #{klass}/Enumerable##{command} for #{value}")
+
+              klass.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                ruby2_keywords def #{command}(*args, &block)  # ruby2_keywords def refresh(*args, &block)
+                  command!(#{value}, *args, &block)           #   command!(REFRESH, *args, &block)
+                end                                           # end
+              RUBY
+
+              Enumerable.class_eval <<~RUBY, __FILE__, __LINE__ + 1
+                def #{command}        # def refresh
+                  each(&:#{command})  #   each(&:refresh)
+                end                   # end
+              RUBY
+            end
 
             logger.trace("Defining ItemCommandEvent##{command}? for #{value}")
             Events::ItemCommandEvent.class_eval <<~RUBY, __FILE__, __LINE__ + 1

data/lib/openhab/core/profile_factory.rb

@@ -6,12 +6,14 @@ require_relative "script_handling"
 
 module OpenHAB
   module Core
+    # rubocop:disable Naming/MethodName
     # @!visibility private
     class ProfileFactory
+      include org.openhab.core.config.core.ConfigDescriptionProvider # This needs to be included first
       include org.openhab.core.thing.profiles.ProfileFactory
+      include org.openhab.core.thing.profiles.ProfileTypeProvider
       include Singleton
 
-      # rubocop:disable Naming/MethodName
       class Profile
         include org.openhab.core.thing.profiles.StateProfile
 
@@ -96,10 +98,10 @@ module OpenHAB
         end
       end
       private_constant :Profile
-      # rubocop:enable Naming/MethodName
 
       def initialize
         @profiles = {}
+        @uri_to_uid = {}
 
         @registration = OSGi.register_service(self)
         ScriptHandling.script_unloaded { unregister }
@@ -116,17 +118,56 @@ module OpenHAB
       end
 
       # @!visibility private
-      def register(uid, block)
-        @profiles[uid] = [DSL::ThreadLocal.persist, block]
+      def register(id, block, label: nil, config_description: nil)
+        uid = org.openhab.core.thing.profiles.ProfileTypeUID.new("ruby", id)
+        uri = java.net.URI.new("profile", uid.to_s, nil)
+        if config_description && config_description.uid != uri
+          config_description = org.openhab.core.config.core.ConfigDescriptionBuilder.create(uri)
+                                  .with_parameters(config_description.parameters)
+                                  .with_parameter_groups(config_description.parameter_groups)
+                                  .build
+        end
+
+        @profiles[uid] = {
+          thread_locals: DSL::ThreadLocal.persist,
+          label: label,
+          config_description: config_description,
+          block: block
+        }
+        @uri_to_uid[uri] = uid
       end
 
-      def createProfile(type, callback, context) # rubocop:disable Naming/MethodName
-        @profiles[type].then { |(thread_locals, block)| Profile.new(callback, context, type, thread_locals, block) }
+      # @!visibility private
+      def createProfile(uid, callback, context)
+        profile = @profiles[uid]
+        Profile.new(callback, context, uid, profile[:thread_locals], profile[:block])
       end
 
-      def getSupportedProfileTypeUIDs # rubocop:disable Naming/MethodName
+      # @!visibility private
+      def getSupportedProfileTypeUIDs
         @profiles.keys
       end
+
+      # @!visibility private
+      def getProfileTypes(_locale)
+        @profiles.map do |uid, profile|
+          next if profile[:label].nil?
+
+          org.openhab.core.thing.profiles.ProfileTypeBuilder.new_state(uid, "RUBY #{profile[:label]}").build
+        end.compact
+      end
+
+      # @!visibility private
+      def getConfigDescriptions(_locale)
+        @profiles.values.map { |profile| profile[:config_description] if profile[:label] }.compact
+      end
+
+      # @!visibility private
+      def getConfigDescription(uri, _locale)
+        uid = @uri_to_uid[uri]
+        @profiles.dig(uid, :config_description)
+      end
     end
+    # rubocop:enable Naming/MethodName
   end
 end

data/lib/openhab/core/sitemaps/provider.rb

@@ -70,13 +70,17 @@ module OpenHAB
         #         text label: "Climate", icon: "if:mdi:home-thermometer-outline" do
         #           frame label: "Main Floor" do
         #             text item: MainFloor_AmbTemp
-        #             switch item: MainFloorThermostat_TargetMode, label: "Mode", mappings: %w[off auto cool heat]
+        #             # colors are set with a hash, with key being condition, and value being the color
+        #             switch item: MainFloorThermostat_TargetMode, label: "Mode", mappings: %w[off auto cool heat], label_color: { "==heat" => "red", "" => "black" }
+        #             # an array of conditions are OR'd together
+        #             switch item: MainFloorThermostat_TargetMode, label: "Mode", mappings: %w[off auto cool heat], label_color: { ["==heat", "==cool"], => "green" }
         #             setpoint item: MainFloorThermostat_SetPoint, label: "Set Point", visibility: "MainFloorThermostat_TargetMode!=off"
         #           end
         #           frame label: "Basement" do
         #             text item: Basement_AmbTemp
         #             switch item: BasementThermostat_TargetMode, label: "Mode", mappings: { OFF: "off", COOL: "cool", HEAT: "heat" }
-        #             setpoint item: BasementThermostat_SetPoint, label: "Set Point", visibility: "BasementThermostat_TargetMode!=off"
+        #             # nested arrays are conditions that are AND'd together, instead of OR'd (requires openHAB 4.1)
+        #             setpoint item: BasementThermostat_SetPoint, label: "Set Point", visibility: [["BasementThermostat_TargetMode!=off", "Vacation_Switch!=OFF"]]
         #           end
         #         end
         #       end

data/lib/openhab/core/things/channel_uid.rb

@@ -22,6 +22,16 @@ module OpenHAB
           EntityLookup.lookup_thing(thing_uid)
         end
 
+        # @attribute [r] channel
+        #
+        # Return the channel object for this channel
+        #
+        # @return [Channel, nil]
+        #
+        def channel
+          thing.channels[self]
+        end
+
         #
         # @attribute [r] item
         #

data/lib/openhab/core/things/profile_callback.rb

@@ -14,9 +14,10 @@ module OpenHAB
         # @param [Command] command
         #
         def handle_command(command)
-          @dummy_channel_item ||= DSL::Items::ItemBuilder.item_factory.create_item(link.channel.accepted_item_type,
-                                                                                   "")
-          command = @dummy_channel_item.format_command(command)
+          unless instance_variable_defined?(:@dummy_channel_item)
+            @dummy_channel_item = DSL::Items::ItemBuilder.item_factory.create_item(link.channel.accepted_item_type, "")
+          end
+          command = @dummy_channel_item.format_command(command) if @dummy_channel_item
           super(command)
         end
 

data/lib/openhab/core/things/thing.rb

@@ -72,6 +72,7 @@ module OpenHAB
           # Allows indexing by both integer as an array or channel id acting like a hash.
           # @param [Integer, String, ChannelUID] index
           #   Numeric index, string channel id, or a {ChannelUID} to search for.
+          # @return [Channel, nil]
           def [](index)
             return @thing.get_channel(index) if index.is_a?(ChannelUID)
             return @thing.get_channel(index.to_str) if index.respond_to?(:to_str)

data/lib/openhab/core/types/decimal_type.rb

@@ -70,7 +70,7 @@ module OpenHAB
         #
         # Convert DecimalType to a QuantityType
         #
-        # @param [String, javax.measure.units.Unit] other
+        # @param [String, javax.measure.Unit] other
         #
         # @return [QuantityType] `self` as a {QuantityType} of the supplied Unit
         #

data/lib/openhab/core/types/quantity_type.rb

@@ -106,7 +106,7 @@ module OpenHAB
         #   #
         #   # Convert this {QuantityType} into another unit.
         #   #
-        #   # @param [String, javax.measure.units.Unit] unit
+        #   # @param [String, javax.measure.Unit] unit
         #   # @return [QuantityType]
         #   #
         #   # @example
@@ -287,7 +287,7 @@ module OpenHAB
           end
         end
 
-        # if unit is {org.openhab.core.library.unit.Units.ONE}, return a plain
+        # if unit is {org.openhab.core.library.unit.Units::ONE}, return a plain
         # Java BigDecimal
         # @!visibility private
         def deunitize

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

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module DSL
+    #
+    # Contains the DSL for creating {org.openhab.core.config.core.ConfigDescription} instances.
+    #
+    module ConfigDescription
+      #
+      # A ConfigDescriptionBuilder is used to create a {org.openhab.core.config.core.ConfigDescription}
+      # instance.
+      #
+      # @see DSL.config_description config_description
+      #
+      class Builder
+        def initialize
+          @parameters = []
+          @parameter_groups = []
+          @current_group = nil
+        end
+
+        #
+        # Create a parameter group.
+        #
+        # @param [String, Symbol] name The group name. This name will be referred to by {parameter}.
+        # @param [String, nil] label The group label
+        # @param [String, nil] description The group description
+        # @param [Boolean] advanced Whether the group is advanced
+        # @param [<Type>] context Context for the group
+        #
+        # @yield Block executed in the context of this group. Any {parameter} calls within the block will
+        #   automatically be added to this group, unless it specifies a different group name.
+        #
+        # @return [void]
+        #
+        def group(name, label: nil, description: nil, advanced: false, context: nil, &block)
+          raise ArgumentError, "Groups cannot be nested" if @current_group
+
+          name = name.to_s
+          @parameter_groups << org.openhab.core.config.core.ConfigDescriptionParameterGroupBuilder
+                                  .create(name)
+                                  .with_label(label)
+                                  .with_description(description)
+                                  .with_advanced(advanced)
+                                  .with_context(context)
+                                  .build
+
+          @current_group = name
+          instance_eval(&block) if block
+        ensure
+          @current_group = nil
+        end
+
+        #
+        # Adds a parameter to the config description.
+        #
+        # @param [String, Symbol] name Parameter name
+        # @param [:text, :integer, :decimal, :boolean] type
+        #   Parameter type. See {org.openhab.core.config.core.ConfigDescriptionParameter.Type}
+        # @param [String, nil] label Parameter label
+        # @param [String, nil] description Parameter description
+        # @param [Numeric, nil] min Minimum value for numeric types
+        # @param [Numeric, nil] max Maximum value for numeric types
+        # @param [Numeric, nil] step Step size for numeric types
+        # @param [String, nil] pattern Regular expression pattern for string types
+        # @param [true, false] required Whether the parameter is required
+        # @param [true, false] read_only Whether the parameter is read only
+        # @param [true, false] multiple Whether the parameter is a list of values
+        # @param [String, nil] context Context for the parameter
+        # @param [Object, nil] default Default value for the parameter
+        # @param [Hash] options Options for the parameter
+        # @param [Hash] filter_criteria Filter criteria for the parameter
+        # @param [String, nil] group_name Parameter group name.
+        #   When nil, it will be inferred when this method is called inside a {group} block.
+        # @param [true, false] advanced Whether the parameter is advanced
+        # @param [true, false] limit_to_options Whether the parameter is limited to the given options
+        # @param [Integer, nil] multiple_limit Maximum number of values for a multiple parameter
+        # @param [String, nil] unit Parameter unit
+        # @param [String, nil] unit_label Parameter unit label
+        # @param [true, false] verify Whether the parameter value should be verified
+        #
+        # @return [void]
+        #
+        # @see org.openhab.core.config.core.ConfigDescriptionParameter
+        #
+        def parameter(name,
+                      type,
+                      label: nil,
+                      description: nil,
+                      min: nil,
+                      max: nil,
+                      step: nil,
+                      pattern: nil,
+                      required: false,
+                      read_only: false,
+                      multiple: false,
+                      context: nil,
+                      default: nil,
+                      options: {},
+                      filter_criteria: {},
+                      group_name: nil,
+                      advanced: false,
+                      limit_to_options: false,
+                      multiple_limit: nil,
+                      unit: nil,
+                      unit_label: nil,
+                      verify: false)
+          # Extract the named arguments into a hash
+          @parameters << method(__method__).parameters
+                                           .select { |param_type, _| param_type == :key }
+                                           .to_h { |_, key| [key, binding.local_variable_get(key)] }
+                                           .then do |p|
+            p[:options] = p[:options].map do |opt_value, opt_label|
+              org.openhab.core.config.core.ParameterOption.new(opt_value, opt_label)
+            end
+            p[:filter_criteria] = p[:filter_criteria].map do |filter_name, filter_value|
+              org.openhab.core.config.core.FilterCriteria.new(filter_name, filter_value)
+            end
+            p[:minimum] = p.delete(:min)&.to_d&.to_java
+            p[:maximum] = p.delete(:max)&.to_d&.to_java
+            p[:step] = p.delete(:step)&.to_d&.to_java
+            p[:group_name] ||= @current_group
+            type = org.openhab.core.config.core.ConfigDescriptionParameter::Type.value_of(type.to_s.upcase)
+
+            parameter = org.openhab.core.config.core.ConfigDescriptionParameterBuilder.create(name.to_s, type)
+
+            p.each do |key, value|
+              parameter.send("with_#{key}", value) unless value.nil?
+            end
+            parameter.build
+          end
+        end
+
+        #
+        # Build the config description
+        #
+        # @param [String, java.net.URI] uri The URI for the config description. When nil, it will default to `dummy:uri`
+        # @yield Block executed in the context of this builder. Inside the block, you can call {parameter} and {group}.
+        #
+        # @return [org.openhab.core.config.core.ConfigDescription] The created ConfigDescription object
+        #
+        def build(uri = nil, &block)
+          instance_eval(&block) if block
+          raise ArgumentError, "No parameters defined" if @parameters.empty?
+
+          uri ||= "dummy:uri"
+          uri = java.net.URI.new(uri.to_s) unless uri.is_a?(java.net.URI)
+          org.openhab.core.config.core.ConfigDescriptionBuilder
+             .create(uri)
+             .with_parameters(@parameters)
+             .with_parameter_groups(@parameter_groups)
+             .build
+        end
+      end
+    end
+  end
+end

data/lib/openhab/dsl/items/ensure.rb

@@ -24,7 +24,7 @@ module OpenHAB
 
         # Extensions for {::Item} to implement {Ensure}'s functionality
         #
-        # @see OpenHAB::DSL.ensure ensure
+        # @see OpenHAB::DSL::Items::Ensure::Ensurable#ensure ensure
         # @see OpenHAB::DSL.ensure_states ensure_states
         module Item
           include Ensurable
@@ -36,6 +36,8 @@ module OpenHAB
           # sending the command
           %i[command update].each do |ensured_method|
             # def command(state)
+            #   # immediately send the command if it's a command, but not a state (like REFRESH)
+            #   return super(state) if state.is_a?(Command) && !state.is_a?(State)
             #   return super(state) unless Thread.current[:openhab_ensure_states]
             #
             #   formatted_state = format_command(state)
@@ -48,6 +50,8 @@ module OpenHAB
             # end
             class_eval <<~RUBY, __FILE__, __LINE__ + 1 # rubocop:disable Style/DocumentDynamicEvalDefinition
               def #{ensured_method}(state)
+                # immediately send the command if it's a command, but not a state (like REFRESH)
+                #{"return super(state) if state.is_a?(Command) && !state.is_a?(State)" if ensured_method == :command}
                 return super(state) unless Thread.current[:openhab_ensure_states]
 
                 formatted_state = format_#{ensured_method}(state)