openhab-scripting 5.16.0 → 5.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66607fb79de6b8b718ddd8cc5cc10662809001e67915074b44360ba9f6408d31
-  data.tar.gz: e21976073a7323b4e8bfe05a09e8959472d950ad28df26534371c857fe64699f
+  metadata.gz: ecc05f177e95b3a962f2b1fac6f924c5af5d6c49ed8a7e38d896c03417fe9e23
+  data.tar.gz: 408fa59899bb838caa9a6f3fc80ef82a4051c03fc590249ab53e0a098c5f335d
 SHA512:
-  metadata.gz: 815f05142db0071b36cd45b9f9e81c1c033cf759823150066f2c65ec4f5eb61fdf9b1bf4dbc0e8125adf3535eb9e83b71fbbf401c2e6f1a716838fe6f37cdd29
-  data.tar.gz: 4fe2bd7469d2d4489bd41ee9c62c6b4e7d53e6350e095c895b936813582d89e088b772bb0a44fde82aaecbfe5ff1c3fac320505001e24d0ac4519646abac5889
+  metadata.gz: ccbc0e426427d262cd1f2a5ed671979f5644b4c5b0da5ff34958254de6221283a9420e2b3c45384ac5aafc7feeffd41fa54740f76c4d99ccaa8adba207c32d52
+  data.tar.gz: 9f9a5f3b120a838f151a1f8edf5e1400f1df0a183cef5a47b921bc661889231c1b186ce2830f8cf7349ab3f89b166de5e1ffc89675628dba21799740b9029cc6

data/lib/openhab/core/entity_lookup.rb

@@ -74,7 +74,7 @@ module OpenHAB
       ruby2_keywords def method_missing(method, *args)
         return super unless args.empty? && !block_given?
 
-        logger.trace("method missing, performing openHAB Lookup for: #{method}")
+        logger.trace { "method missing, performing openHAB Lookup for: #{method}" }
         EntityLookup.lookup_entity(method,
                                    create_dummy_items: self.class.respond_to?(:create_dummy_items?) &&
                                      self.class.create_dummy_items?) || super
@@ -82,7 +82,7 @@ module OpenHAB
 
       # @!visibility private
       def respond_to_missing?(method, *)
-        logger.trace("Checking if openHAB entities exist for #{method}")
+        logger.trace { "Checking if openHAB entities exist for #{method}" }
         EntityLookup.lookup_entity(method) || super
       end
 
@@ -121,14 +121,14 @@ module OpenHAB
         # @return [Things::Thing, nil]
         #
         def lookup_thing(uid)
-          logger.trace("Looking up thing '#{uid}'")
+          logger.trace { "Looking up thing '#{uid}'" }
           uid = uid.to_s if uid.is_a?(Symbol)
 
           uid = Things::ThingUID.new(uid) unless uid.is_a?(Things::ThingUID)
           thing = $things.get(uid)
           return unless thing
 
-          logger.trace("Retrieved Thing(#{thing}) from registry for uid: #{uid}")
+          logger.trace { "Retrieved Thing(#{thing}) from registry for uid: #{uid}" }
           Things::Proxy.new(thing)
         end
 
@@ -164,7 +164,7 @@ module OpenHAB
         # @return [Item, nil]
         #
         def lookup_item(name)
-          logger.trace("Looking up item '#{name}'")
+          logger.trace { "Looking up item '#{name}'" }
           name = name.to_s if name.is_a?(Symbol)
           item = $ir.get(name)
           Items::Proxy.new(item) unless item.nil?

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

@@ -2,21 +2,21 @@
 
 require_relative "item_state_event"
 
+# @deprecated OH3.4 guard only needed in OH 3.4
+return unless OpenHAB::Core.version >= OpenHAB::Core::V4_0
+
 module OpenHAB
   module Core
     module Events
-      # @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
+      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
+      #
+      # {AbstractEvent} sent when an item's state has updated.
+      #
+      # @since openHAB 4.0
+      #
+      class ItemStateUpdatedEvent < ItemEvent
+        include ItemState
       end
     end
   end

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

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# @deprecated OH4.0 guard not needed in OH 4.1
+return unless OpenHAB::Core.version >= OpenHAB::Core::V4_1
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.items.events.ItemTimeSeriesUpdatedEvent
+
+      #
+      # {AbstractEvent} sent when an item received a time series update.
+      #
+      # @!attribute [r] time_series
+      #   @return [TimeSeries] The updated time series.
+      #
+      # @since openHAB 4.1
+      # @see DSL::Rules::BuilderDSL#time_series_updated #time_series_updated rule trigger
+      #
+      class ItemTimeSeriesUpdatedEvent < ItemEvent; end
+    end
+  end
+end

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

@@ -1,46 +1,46 @@
 # frozen_string_literal: true
 
+# @deprecated OH3.4 this guard is not needed on OH4
+return unless OpenHAB::Core.version >= OpenHAB::Core::V4_0
+
 module OpenHAB
   module Core
     module Events
-      # @deprecated OH3.4 this guard is not needed on OH4
-      if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
-        java_import org.openhab.core.automation.events.TimerEvent
+      java_import org.openhab.core.automation.events.TimerEvent
 
+      #
+      # Adds methods to core openHAB TimerEvent to make it more natural in Ruby
+      #
+      # This event can be triggered by a `DateTimeTrigger`, `cron`, or `TimeOfDay` trigger.
+      #
+      # @since openHAB 4.0
+      #
+      class TimerEvent < AbstractEvent
         #
-        # Adds methods to core openHAB TimerEvent to make it more natural in Ruby
+        # @!attribute [r] cron_expression
+        # @return [String, nil] The cron expression that triggered this event.
+        #   `nil` when this event wasn't triggered by a cron trigger.
         #
-        # This event can be triggered by a `DateTimeTrigger`, `cron`, or `TimeOfDay` trigger.
+        def cron_expression
+          payload&.[](:cronExpression)
+        end
+
         #
-        # @since openHAB 4.0
+        # @!attribute [r] item
+        # @return [Item, nil] The DateTime item that triggered this event.
+        #   `nil` when this event wasn't triggered by a DateTimeItem trigger.
         #
-        class TimerEvent < AbstractEvent
-          #
-          # @!attribute [r] cron_expression
-          # @return [String, nil] The cron expression that triggered this event.
-          #   `nil` when this event wasn't triggered by a cron trigger.
-          #
-          def cron_expression
-            payload&.[](:cronExpression)
-          end
-
-          #
-          # @!attribute [r] item
-          # @return [Item, nil] The DateTime item that triggered this event.
-          #   `nil` when this event wasn't triggered by a DateTimeItem trigger.
-          #
-          def item
-            payload&.[](:itemName)&.then { |item_name| EntityLookup.lookup_item(item_name) }
-          end
+        def item
+          payload&.[](:itemName)&.then { |item_name| EntityLookup.lookup_item(item_name) }
+        end
 
-          #
-          # @!attribute [r] time
-          # @return [LocalTime, nil] The configured time for this TimeOfDay trigger event.
-          #   `nil` when this event wasn't triggered by a TimeOfDay trigger.
-          #
-          def time
-            payload&.[](:time)&.then { |time| LocalTime.parse(time) }
-          end
+        #
+        # @!attribute [r] time
+        # @return [LocalTime, nil] The configured time for this TimeOfDay trigger event.
+        #   `nil` when this event wasn't triggered by a TimeOfDay trigger.
+        #
+        def time
+          payload&.[](:time)&.then { |time| LocalTime.parse(time) }
         end
       end
     end

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

@@ -207,6 +207,18 @@ module OpenHAB
           type.to_s
         end
 
+        #
+        # @method time_series=(time_series)
+        #   Set a new time series.
+        #
+        #   This will trigger a {DSL::Rules::BuilderDSL#time_series_updated time_series_updated} event.
+        #
+        #   @param [Core::Types::TimeSeries] time_series New time series to set.
+        #   @return [void]
+        #
+        #   @since openHAB 4.1
+        #
+
         #
         # Defers notifying openHAB of modifications to multiple attributes until the block is complete.
         #

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

@@ -7,7 +7,7 @@ module OpenHAB
     module Items
       # Mixin for implementing type coercion for number-like items
       module NumericItem
-        %i[positive? negative? zero?].each do |predicate|
+        %i[positive? negative? zero? nonzero?].each do |predicate|
           class_eval <<~RUBY, __FILE__, __LINE__ + 1
             def #{predicate}              # def positive?
               return false unless state?  #   return false unless state?

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

@@ -83,9 +83,7 @@ module OpenHAB
                                   updated_since?])
 
         # @deprecated OH3.4 - in openHAB 4, just add :get_all_states_since and freeze the list above
-        if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
-          PERSISTENCE_METHODS << :get_all_states_since
-        end
+        PERSISTENCE_METHODS << :get_all_states_since if OpenHAB::Core.version >= OpenHAB::Core::V4_0
         PERSISTENCE_METHODS.freeze
 
         private_constant :QUANTITY_METHODS, :PERSISTENCE_METHODS
@@ -386,7 +384,7 @@ module OpenHAB
         alias_method :state_changes_since, :count_state_changes_since
         alias_method :state_changes_between, :count_state_changes_between
         # @deprecated OH 3.4 - if guard is unnecessary in OH4
-        if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
+        if OpenHAB::Core.version >= OpenHAB::Core::V4_0
           alias_method :all_states_since, :get_all_states_since
           alias_method :all_states_between, :get_all_states_between
         end

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

@@ -21,15 +21,13 @@ module OpenHAB
         # @return [Item] Item from registry, nil if item missing or requested item is a Group Type
         def [](name)
           EntityLookup.lookup_item(name)
-        rescue org.openhab.core.items.ItemNotFoundException
-          nil
         end
 
         # Returns true if the given item name exists
         # @param name [String] Item name to check
         # @return [true,false] true if the item exists, false otherwise
         def key?(name)
-          !$ir.getItems(name).empty?
+          !$ir.get(name).nil?
         end
         alias_method :include?, :key?
         # @deprecated

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

@@ -226,10 +226,7 @@ module OpenHAB
 
             # @deprecated OH3.4 - the Property tag had an ID of "MeasurementProperty" in OH3.4.
             # This was corrected in OH4.
-            # Make sure we compare against pre-release versions
-            if id == "Property" && Gem::Version.new(Core::VERSION) < Gem::Version.new("4.0.0.M1")
-              id = "MeasurementProperty"
-            end
+            id = "MeasurementProperty" if id == "Property" && Core.version < Core::V4_0
 
             # @deprecated OH3.4 missing registry
             if Provider.registry

data/lib/openhab/core/profile_factory.rb

@@ -15,7 +15,12 @@ module OpenHAB
       include Singleton
 
       class Profile
-        include org.openhab.core.thing.profiles.StateProfile
+        # @deprecated OH 4.0 only include TimeSeriesProfile in OH 4.1, because it extends StateProfile
+        if OpenHAB::Core.version >= OpenHAB::Core::V4_1
+          include org.openhab.core.thing.profiles.TimeSeriesProfile
+        else
+          include org.openhab.core.thing.profiles.StateProfile
+        end
 
         def initialize(callback, context, uid, thread_locals, block)
           unless callback.class.ancestors.include?(Things::ProfileCallback)
@@ -64,6 +69,14 @@ module OpenHAB
           process_event(:state_from_item, state: state)
         end
 
+        # @deprecated OH 4.0 guard is only needed for < OH 4.1
+        if OpenHAB::Core.version >= OpenHAB::Core::V4_1
+          # @!visibility private
+          def onTimeSeriesFromHandler(time_series)
+            process_event(:time_series_from_handler, time_series: time_series)
+          end
+        end
+
         private
 
         def process_event(event, **params)
@@ -77,6 +90,8 @@ module OpenHAB
           params[:channel_uid] = @callback.link.linked_uid
           params[:state] ||= nil
           params[:command] ||= nil
+          # @deprecated OH 4.0 guard is only needed for < OH 4.1
+          params[:time_series] ||= nil if OpenHAB::Core.version >= OpenHAB::Core::V4_1
 
           kwargs = {}
           @block.parameters.each do |(param_type, name)|

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

@@ -132,7 +132,9 @@ module OpenHAB
           builder = DSL::Sitemaps::Builder.new(self, builder_proxy, update: update)
           if block.arity == 1
             builder_proxy.__setobj__(builder)
-            yield builder_proxy
+            DSL::ThreadLocal.thread_local(openhab_create_dummy_items: true) do
+              yield builder_proxy
+            end
           else
             builder.instance_eval(&block)
           end

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

@@ -58,7 +58,7 @@ module OpenHAB
         end
 
         # @deprecated OH3.4 this whole section is not needed in OH4+. Also see Thing#config_eql?
-        if Gem::Version.new(Core::VERSION) < Gem::Version.new("4.0.0")
+        if Core.version < Core::V4_0
           # @!visibility private
           module ChannelComparable
             # @!visibility private

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

@@ -40,6 +40,11 @@ module OpenHAB
           state = link.item.format_update(state)
           super(state)
         end
+
+        # @!method send_time_series(time_series)
+        #   Send a time series to the framework.
+        #   @param [TimeSeries] time_series
+        #   @since openHAB 4.1
       end
     end
   end

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

@@ -165,6 +165,12 @@ module OpenHAB
           ThingType.registry.get_thing_type(thing_type_uid)
         end
 
+        # @!attribute [r] bridge
+        # @return [Thing, nil]
+        def bridge
+          bridge_uid && EntityLookup.lookup_thing(bridge_uid)
+        end
+
         # @return [String]
         def inspect
           r = "#<OpenHAB::Core::Things::Thing #{uid}"

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

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# @deprecated OH4.0 this guard is not needed on OH4.1
+return unless OpenHAB::Core.version >= OpenHAB::Core::V4_1
+
+require "forwardable"
+
+module OpenHAB
+  module Core
+    module Types
+      TimeSeries = org.openhab.core.types.TimeSeries
+
+      #
+      # {TimeSeries} is used to transport a set of states together with their timestamp.
+      #
+      # The states are sorted chronologically. The entries can be accessed like an array.
+      #
+      # @since openHAB 4.1
+      #
+      # @example
+      #   time_series = TimeSeries.new # defaults to :add policy
+      #                           .add(Time.at(2), DecimalType.new(2))
+      #                           .add(Time.at(1), DecimalType.new(1))
+      #                           .add(Time.at(3), DecimalType.new(3))
+      #   logger.info "first entry: #{time_series.first.state}" # => 1
+      #   logger.info "last entry: #{time_series.last.state}" # => 3
+      #   logger.info "second entry: #{time_series[1].state}" # => 2
+      #   logger.info "sum: #{time_series.sum(&:state)}" # => 6
+      #
+      # @see DSL::Rules::BuilderDSL#time_series_updated #time_series_updated rule trigger
+      #
+      class TimeSeries
+        extend Forwardable
+
+        # @!attribute [r] policy
+        #   Returns the persistence policy of this series.
+        #   @see org.openhab.core.types.TimeSeries#getPolicy()
+        #   @return [org.openhab.core.types.TimeSeries.Policy]
+
+        # @!attribute [r] begin
+        #   Returns the timestamp of the first element in this series.
+        #   @return [Instant]
+
+        # @!attribute [r] end
+        #   Returns the timestamp of the last element in this series.
+        #   @return [Instant]
+
+        # @!attribute [r] size
+        #   Returns the number of elements in this series.
+        #   @return [Integer]
+
+        #
+        # Create a new instance of TimeSeries
+        #
+        # @param [:add, :replace, org.openhab.core.types.TimeSeries.Policy] policy
+        #   The persistence policy of this series.
+        #
+        def initialize(policy = :replace)
+          policy = Policy.value_of(policy.to_s.upcase) if policy.is_a?(Symbol)
+          super
+        end
+
+        # Returns true if the series' policy is `ADD`.
+        # @return [true,false]
+        def add?
+          policy == Policy::ADD
+        end
+
+        # Returns true if the series' policy is `REPLACE`.
+        # @return [true,false]
+        def replace?
+          policy == Policy::REPLACE
+        end
+
+        # @!visibility private
+        def inspect
+          "#<OpenHAB::Core::Types::TimeSeries " \
+            "policy=#{policy} " \
+            "begin=#{self.begin} " \
+            "end=#{self.end} " \
+            "size=#{size}>"
+        end
+
+        #
+        # Returns the content of this series.
+        # @return [Array<org.openhab.core.types.TimeSeries.Entry>]
+        #
+        def states
+          get_states.to_array.to_a.freeze
+        end
+
+        # rename raw methods so we can overwrite them
+        # @!visibility private
+        alias_method :add_instant, :add
+
+        #
+        # Adds a new element to this series.
+        #
+        # Elements can be added in an arbitrary order and are sorted chronologically.
+        #
+        # @note This method returns self so it can be chained, unlike the Java version.
+        #
+        # @param [Instant, #to_zoned_date_time, #to_instant] instant An instant for the given state.
+        # @param [State] state The State at the given timestamp.
+        # @return [self]
+        #
+        def add(instant, state)
+          instant = instant.to_zoned_date_time if instant.respond_to?(:to_zoned_date_time)
+          instant = instant.to_instant if instant.respond_to?(:to_instant)
+          add_instant(instant, state)
+          self
+        end
+
+        # any method that exists on Array gets forwarded to states
+        delegate (Array.instance_methods - instance_methods) => :states
+      end
+    end
+  end
+end
+
+TimeSeries = OpenHAB::Core::Types::TimeSeries unless Object.const_defined?(:TimeSeries)

data/lib/openhab/core.rb

@@ -7,7 +7,20 @@ module OpenHAB
     # @return [String]
     VERSION = org.openhab.core.OpenHAB.version.freeze
 
-    raise "`openhab-scripting` requires openHAB >= 3.4.0" unless Gem::Version.new(VERSION) >= Gem::Version.new("3.4.0")
+    # @!visibility private
+    V4_0 = Gem::Version.new("4.0.0").freeze
+    # @!visibility private
+    V4_1 = Gem::Version.new("4.1.0").freeze
+    # @!visibility private
+    V4_2 = Gem::Version.new("4.2.0").freeze
+
+    # @return [Gem::Version] Returns the current openHAB version as a Gem::Version object
+    # @!visibility private
+    def self.version
+      @version ||= Gem::Version.new(VERSION).freeze
+    end
+
+    raise "`openhab-scripting` requires openHAB >= 3.4.0" unless version >= Gem::Version.new("3.4.0")
 
     # @return [Integer] Number of seconds to wait between checks for automation manager
     CHECK_DELAY = 10

data/lib/openhab/core_ext/java/instant.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module CoreExt
+    module Java
+      java_import java.time.Instant
+
+      # Extensions to {java.time.Instant}
+      class Instant < java.lang.Object; end
+    end
+  end
+end
+
+Instant = OpenHAB::CoreExt::Java::Instant unless Object.const_defined?(:Instant)

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

@@ -1089,7 +1089,7 @@ module OpenHAB
               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})")
+            logger.trace { "Creating changed trigger for entity(#{item}), to(#{to.inspect}), from(#{from.inspect})" }
 
             Array.wrap(from).each do |from_state|
               Array.wrap(to).each do |to_state|
@@ -1381,7 +1381,7 @@ module OpenHAB
           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}")
+            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
@@ -1480,7 +1480,7 @@ module OpenHAB
               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}"
+              logger.trace { "Creating received command trigger for items #{item.inspect} and commands #{cmd.inspect}" }
 
               command_trigger.trigger(item: item, command: cmd, attach: attach)
             end
@@ -1699,7 +1699,7 @@ module OpenHAB
         #   end
         #
         def trigger(type, attach: nil, **configuration)
-          logger.trace("Creating trigger (#{type}) with configuration(#{configuration})")
+          logger.trace { "Creating trigger (#{type}) with configuration(#{configuration})" }
           Triggers::Trigger.new(rule_triggers: @rule_triggers)
                            .append_trigger(type: type, config: configuration, attach: attach)
         end
@@ -1802,13 +1802,48 @@ module OpenHAB
               raise ArgumentError, "items must be an Item, GroupItem::Members, Thing, or ThingUID"
             end
 
-            logger.trace("Creating updated trigger for item(#{item}) to(#{to})")
+            logger.trace { "Creating updated trigger for item(#{item}) to(#{to})" }
             [to].flatten.map do |to_state|
               updated.trigger(item: item, to: to_state, attach: attach)
             end
           end.flatten
         end
 
+        #
+        # Creates a time series updated trigger
+        #
+        # The `event` passed to run blocks will be a {OpenHAB::Core::Events::ItemTimeSeriesUpdatedEvent}
+        #
+        # @param [Item] items Items to create trigger for.
+        # @param [Object] attach Object to be attached to the trigger.
+        # @return [void]
+        #
+        # @since openHAB 4.1
+        # @see Core::Types::TimeSeries TimeSeries
+        # @see Core::Items::GenericItem#time_series= GenericItem#time_series=
+        #
+        # @example
+        #   rule 'Execute rule when item time series is updated' do
+        #     time_series_updated MyItem
+        #     run do |event|
+        #       logger.info("Item time series updated: #{event.item.name}.")
+        #       logger.info("  TimeSeries size: #{event.time_series.size}, policy: #{event.time_series.policy}")
+        #       event.time_series.each do |entry|
+        #         timestamp = entry.timestamp.to_time.strftime("%Y-%m-%d %H:%M:%S")
+        #         logger.info("    Entry: #{timestamp}: State: #{entry.state}")
+        #       end
+        #     end
+        #   end
+        #
+        def time_series_updated(*items, attach: nil)
+          @ruby_triggers << [:time_series_updated, items]
+          items.map do |item|
+            raise ArgumentError, "items must be an Item or GroupItem::Members" unless item.is_a?(Core::Items::Item)
+
+            event("openhab/items/#{item.name}/timeseriesupdated", types: "ItemTimeSeriesUpdatedEvent", attach: attach)
+          end
+        end
+
         #
         # Create a trigger to watch a path
         #
@@ -1987,7 +2022,7 @@ module OpenHAB
           elsif !execution_blocks?
             logger.warn "Rule '#{uid}' has no execution blocks, not creating rule"
           elsif !enabled
-            logger.trace "Rule '#{uid}' marked as disabled, not creating rule."
+            logger.trace { "Rule '#{uid}' marked as disabled, not creating rule." }
           else
             return true
           end
@@ -2024,7 +2059,7 @@ module OpenHAB
             duplicate_index += 1
             rule.uid = "#{base_uid} (#{duplicate_index})"
           end
-          logger.trace("Adding rule: #{rule}")
+          logger.trace { "Adding rule: #{rule}" }
           unmanaged_rule = Core.automation_manager.add_unmanaged_rule(rule)
           provider.add(unmanaged_rule)
           unmanaged_rule

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

@@ -64,6 +64,8 @@ module OpenHAB
               infer_rule_name_from_item_registry_trigger(trigger)
             when :thing_added, :thing_removed, :thing_updated
               infer_rule_name_from_thing_trigger(trigger)
+            when :time_series_updated
+              infer_rule_name_from_time_series_trigger(items)
             when :on_start
               infer_rule_name_from_on_start_trigger(items)
             end
@@ -136,6 +138,11 @@ module OpenHAB
             }[trigger]
           end
 
+          # formulate a readable rule name from a time series updated trigger
+          def infer_rule_name_from_time_series_trigger(items)
+            "#{format_array(items.map(&:name))} time series updated"
+          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)})" }

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

@@ -20,29 +20,46 @@ module OpenHAB
         class << self
           # @!visibility private
           # @!macro def_terse_rule
-          #   @!method $1(*args, name :nil, id: nil, on_load: false, **kwargs, &block)
+          #   @!method $1(
+          #     *args,
+          #     id: nil,
+          #     name :nil,
+          #     description: nil,
+          #     tag: nil,
+          #     tags: nil,
+          #     on_load: false,
+          #     **kwargs,
+          #     &block)
           #   Create a new rule with a $1 trigger.
-          #   @param name [String] The name for the rule.
           #   @param id [String] The ID for the rule.
+          #   @param name [String] The name for the rule.
+          #   @param description [String, nil] The description for the rule.
+          #   @param tag [String, Symbol, Semantics::Tag, Array<String, Symbol, Semantics::Tag>, nil]
+          #     Tags to assign to the script
+          #   @param tags [String, Symbol, Semantics::Tag, Array<String, Symbol, Semantics::Tag>, nil]
+          #     Fluent alias for `tag`
           #   @param on_load [true, false] If the rule should _also_ trigger immediately when the script loads.
           #   @yield The execution block for the rule.
           #   @return [void]
           #   @see BuilderDSL#$1
           def def_terse_rule(trigger)
             class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
-              def #{trigger}(*args, name: nil, id: nil, on_load: false, **kwargs, &block)     # def changed(*args, name: nil, id: nil, on_load: false, **kwargs, &block)
-                raise ArgumentError, "Block is required" unless block                         #   raise ArgumentError, "Block is required" unless block
-                                                                                              #
-                id ||= NameInference.infer_rule_id_from_block(block)                          #   id ||= NameInference.infer_rule_id_from_block(block)
-                script = block.source rescue nil                                              #   script = block.source rescue nil
-                caller_binding = block.binding                                                #   caller_binding = block.binding
-                rule name, id: id, script: script, binding: caller_binding do                 #   rule name, id: id, script: script, binding: caller_binding do
-                  self.on_load if on_load                                                     #     self.on_load if on_load
-                  #{trigger}(*args, **kwargs)                                                 #     changed(*args, **kwargs)
-                  run(&block)                                                                 #     run(&block)
-                end                                                                           #   end
-              end                                                                             # end
-              module_function #{trigger.inspect}                                              # module_function :changed
+              def #{trigger}(*args, id: nil, name: nil, description: nil,       # def changed(*args, id: nil, name: nil, description: nil,
+                  tag: nil, tags: nil, on_load: false, **kwargs, &block)        #     tag: nil, tags: nil, on_load: false, **kwargs, &block)
+                raise ArgumentError, "Block is required" unless block           #   raise ArgumentError, "Block is required" unless block
+                                                                                #
+                id ||= NameInference.infer_rule_id_from_block(block)            #   id ||= NameInference.infer_rule_id_from_block(block)
+                script = block.source rescue nil                                #   script = block.source rescue nil
+                caller_binding = block.binding                                  #   caller_binding = block.binding
+                rule name, id: id, script: script, binding: caller_binding do   #   rule name, id: id, script: script, binding: caller_binding do
+                  self.on_load if on_load                                       #     self.on_load if on_load
+                  self.description(description) if description                  #     self.description(description) if description
+                  self.tags(*Array.wrap(tag), *Array.wrap(tags))                #     self.tags(*Array.wrap(tag), *Array.wrap(tags))
+                  #{trigger}(*args, **kwargs)                                   #     changed(*args, **kwargs)
+                  run(&block)                                                   #     run(&block)
+                end                                                             #   end
+              end                                                               # end
+              module_function #{trigger.inspect}                                # module_function :changed
             RUBY
           end
         end

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

@@ -12,7 +12,8 @@ module OpenHAB
         #
         class Cron < Trigger
           # Trigger ID for Cron Triggers
-          CRON_TRIGGER_MODULE_ID = if Gem::Version.new(OpenHAB::Core::VERSION) >= Gem::Version.new("4.0.0")
+          # @deprecated OH 3.4
+          CRON_TRIGGER_MODULE_ID = if OpenHAB::Core.version >= OpenHAB::Core::V4_0
                                      "timer.GenericCronTrigger"
                                    else
                                      # @deprecated OH3.4 We need to use a custom CronTrigger handler
@@ -211,7 +212,7 @@ module OpenHAB
           #
           def trigger(config:, attach:)
             # @deprecated OH3.4 needs a custom CronTriggerHandlerFactory
-            if Gem::Version.new(OpenHAB::Core::VERSION) < Gem::Version.new("4.0.0")
+            if OpenHAB::Core.version < OpenHAB::Core::V4_0
               CronHandler::CronTriggerHandlerFactory.instance # ensure it's registered
             end
             append_trigger(type: CRON_TRIGGER_MODULE_ID, config: config, attach: attach)

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

@@ -1,120 +1,118 @@
 # frozen_string_literal: true
 
 # @deprecated OH3.4 this module is not needed in OH4+
-if Gem::Version.new(OpenHAB::Core::VERSION) < Gem::Version.new("4.0.0")
-
-  require "singleton"
-
-  require_relative "cron"
-
-  module OpenHAB
-    module DSL
-      module Rules
-        module Triggers
-          # @!visibility private
-          #
-          # Cron trigger handler that provides trigger ID
-          #
-          module CronHandler
-            # Cron Trigger Handler that provides trigger IDs
-            # Unfortunatly because the CronTriggerHandler in openHAB core is marked internal
-            # the entire thing must be recreated here
-            class CronTriggerHandler < org.openhab.core.automation.handler.BaseTriggerModuleHandler
-              include org.openhab.core.scheduler.SchedulerRunnable
-              include org.openhab.core.automation.handler.TimeBasedTriggerHandler
-
-              # Provides access to protected fields
-              field_accessor :callback
-
-              # Creates a new CronTriggerHandler
-              # @param [org.openhab.core.automation.Trigger] trigger openHAB trigger associated with handler
-              #
-              def initialize(trigger)
-                @trigger = trigger
-                @scheduler = OSGi.service("org.openhab.core.scheduler.CronScheduler")
-                @schedule = nil
-                @expression = trigger.configuration.get("cronExpression")
-                super(trigger)
-              end
+return unless OpenHAB::Core.version < OpenHAB::Core::V4_0
+
+require "singleton"
+
+require_relative "cron"
+
+module OpenHAB
+  module DSL
+    module Rules
+      module Triggers
+        # @!visibility private
+        #
+        # Cron trigger handler that provides trigger ID
+        #
+        module CronHandler
+          # Cron Trigger Handler that provides trigger IDs
+          # Unfortunatly because the CronTriggerHandler in openHAB core is marked internal
+          # the entire thing must be recreated here
+          class CronTriggerHandler < org.openhab.core.automation.handler.BaseTriggerModuleHandler
+            include org.openhab.core.scheduler.SchedulerRunnable
+            include org.openhab.core.automation.handler.TimeBasedTriggerHandler
+
+            # Provides access to protected fields
+            field_accessor :callback
+
+            # Creates a new CronTriggerHandler
+            # @param [org.openhab.core.automation.Trigger] trigger openHAB trigger associated with handler
+            #
+            def initialize(trigger)
+              @trigger = trigger
+              @scheduler = OSGi.service("org.openhab.core.scheduler.CronScheduler")
+              @schedule = nil
+              @expression = trigger.configuration.get("cronExpression")
+              super(trigger)
+            end
 
-              #
-              # Set the callback to execute when cron trigger fires
-              # @param [Object] callback to run
-              #
-              def setCallback(callback) # rubocop:disable Naming/MethodName
-                synchronized do
-                  super(callback)
-                  @schedule = @scheduler.schedule(self, @expression)
-                  logger.trace("Scheduled cron job '#{@expression}' for trigger '#{@trigger.id}'.")
-                end
+            #
+            # Set the callback to execute when cron trigger fires
+            # @param [Object] callback to run
+            #
+            def setCallback(callback) # rubocop:disable Naming/MethodName
+              synchronized do
+                super(callback)
+                @schedule = @scheduler.schedule(self, @expression)
+                logger.trace("Scheduled cron job '#{@expression}' for trigger '#{@trigger.id}'.")
               end
+            end
 
-              #
-              # Get the temporal adjuster
-              # @return [CronAdjuster]
-              #
-              def getTemporalAdjuster # rubocop:disable Naming/MethodName
-                org.openhab.core.scheduler.CronAdjuster.new(@expression)
-              end
+            #
+            # Get the temporal adjuster
+            # @return [CronAdjuster]
+            #
+            def getTemporalAdjuster # rubocop:disable Naming/MethodName
+              org.openhab.core.scheduler.CronAdjuster.new(@expression)
+            end
 
-              #
-              # Execute the callback
-              #
-              def run
-                callback&.triggered(@trigger, { "module" => @trigger.id })
-              end
+            #
+            # Execute the callback
+            #
+            def run
+              callback&.triggered(@trigger, { "module" => @trigger.id })
+            end
 
-              #
-              # Dispose of the handler
-              # cancel the cron scheduled task
-              #
-              def dispose
-                synchronized do
-                  super
-                  return unless @schedule
+            #
+            # Dispose of the handler
+            # cancel the cron scheduled task
+            #
+            def dispose
+              synchronized do
+                super
+                return unless @schedule
 
-                  @schedule.cancel(true)
-                  @schedule = nil
-                end
-                logger.trace("cancelled job for trigger '#{@trigger.id}'.")
+                @schedule.cancel(true)
+                @schedule = nil
               end
+              logger.trace("cancelled job for trigger '#{@trigger.id}'.")
             end
+          end
 
-            # Implements the ScriptedTriggerHandlerFactory interface to create a new Cron Trigger Handler
-            class CronTriggerHandlerFactory
-              include Singleton
-              include org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory # rubocop:disable Layout/LineLength
-
-              def initialize
-                Core.automation_manager.add_trigger_handler(
-                  Cron::CRON_TRIGGER_MODULE_ID,
-                  self
-                )
-
-                Core.automation_manager.add_trigger_type(org.openhab.core.automation.type.TriggerType.new(
-                                                           Cron::CRON_TRIGGER_MODULE_ID,
-                                                           nil,
-                                                           "A specific instant occurs",
-                                                           "Triggers when the specified instant occurs",
-                                                           nil,
-                                                           org.openhab.core.automation.Visibility::VISIBLE,
-                                                           nil
-                                                         ))
-                logger.trace("Added script cron trigger handler")
-              end
+          # Implements the ScriptedTriggerHandlerFactory interface to create a new Cron Trigger Handler
+          class CronTriggerHandlerFactory
+            include Singleton
+            include org.openhab.core.automation.module.script.rulesupport.shared.factories.ScriptedTriggerHandlerFactory
+
+            def initialize
+              Core.automation_manager.add_trigger_handler(
+                Cron::CRON_TRIGGER_MODULE_ID,
+                self
+              )
+
+              Core.automation_manager.add_trigger_type(org.openhab.core.automation.type.TriggerType.new(
+                                                         Cron::CRON_TRIGGER_MODULE_ID,
+                                                         nil,
+                                                         "A specific instant occurs",
+                                                         "Triggers when the specified instant occurs",
+                                                         nil,
+                                                         org.openhab.core.automation.Visibility::VISIBLE,
+                                                         nil
+                                                       ))
+              logger.trace("Added script cron trigger handler")
+            end
 
-              # Invoked by openHAB core to get a trigger handler for the supplied trigger
-              # @param [org.openhab.core.automation.Trigger] trigger
-              #
-              # @return [WatchTriggerHandler] trigger handler for supplied trigger
-              def get(trigger)
-                CronTriggerHandler.new(trigger)
-              end
+            # Invoked by openHAB core to get a trigger handler for the supplied trigger
+            # @param [org.openhab.core.automation.Trigger] trigger
+            #
+            # @return [CronTriggerHandler] trigger handler for supplied trigger
+            def get(trigger)
+              CronTriggerHandler.new(trigger)
             end
           end
         end
       end
     end
   end
-
 end

data/lib/openhab/dsl/rules/triggers/watch/watch_handler.rb

@@ -310,7 +310,7 @@ module OpenHAB
               logger.trace("Added watch trigger handler")
             end
 
-            # Invoked by openHAB core to get a trigger handler for the supllied trigger
+            # Invoked by openHAB core to get a trigger handler for the supplied trigger
             # @param [org.openhab.core.automation.Trigger] trigger
             #
             # @return [WatchTriggerHandler] trigger handler for supplied trigger

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

@@ -144,7 +144,7 @@ module OpenHAB
           if @builder_proxy
             old_obj = @builder_proxy.__getobj__
             @builder_proxy.__setobj__(self)
-            begin
+            DSL::ThreadLocal.thread_local(openhab_create_dummy_items: true) do
               yield @builder_proxy
             ensure
               @builder_proxy.__setobj__(old_obj)

data/lib/openhab/dsl/version.rb

@@ -4,6 +4,6 @@ module OpenHAB
   module DSL
     # Version of openHAB helper libraries
     # @return [String]
-    VERSION = "5.16.0"
+    VERSION = "5.17.0"
   end
 end

data/lib/openhab/dsl.rb

@@ -84,14 +84,17 @@ module OpenHAB
     # @param [String, nil] label The label for the profile. When nil, the profile will not be visible in the UI.
     # @param [org.openhab.core.config.core.ConfigDescription, nil] config_description
     #   The configuration description for the profile so that it can be configured in the UI.
-    # @yield [event, command: nil, state: nil, callback:, link:, item:, channel_uid:, configuration:, context:]
+    # @yield [event, command: nil, state: nil, time_series: nil, callback:, link:, item:, channel_uid:, configuration:, context:]
     #   All keyword params are optional. Any that aren't defined won't be passed.
-    # @yieldparam [:command_from_item, :state_from_item, :command_from_handler, :state_from_handler] event
+    # @yieldparam [:command_from_item, :state_from_item, :command_from_handler, :state_from_handler, :time_series_from_handler] event
     #   The event that needs to be processed.
     # @yieldparam [Command, nil] command
     #   The command being sent for `:command_from_item` and `:command_from_handler` events.
     # @yieldparam [State, nil] state
     #   The state being sent for `:state_from_item` and `:state_from_handler` events.
+    # @yieldparam [TimeSeries] time_series
+    #   The time series for `:time_series_from_handler` events.
+    #   Only available since openHAB 4.1.
     # @yieldparam [Core::Things::ProfileCallback] callback
     #   The callback to be used to customize the action taken.
     # @yieldparam [Core::Things::ItemChannelLink] link
@@ -105,6 +108,7 @@ module OpenHAB
     #
     # @see org.openhab.core.thing.profiles.Profile
     # @see org.openhab.core.thing.profiles.StateProfile
+    # @see org.openhab.core.thing.profiles.TimeSeriesProfile
     #
     # @example Vetoing a command
     #   profile(:veto_closing_shades) do |event, item:, command:|

data/lib/openhab/rspec/mocks/synchronous_executor.rb

@@ -21,7 +21,8 @@ module OpenHAB
         attr_accessor :main_thread
 
         def initialize
-          super(1)
+          # Allocate a (hopefully) big enough pool size to accommodate scheduled tasks
+          super(10)
         end
 
         def submit(runnable)

data/lib/openhab/rspec/mocks/thing_handler.rb

@@ -37,6 +37,10 @@ module OpenHAB
           callback&.state_updated(channel_uid, command) if command.is_a?(Core::Types::State)
         end
 
+        def send_time_series(channel_uid, time_series)
+          @callback&.send_time_series(channel_uid, time_series)
+        end
+
         def set_callback(callback)
           @callback = callback
         end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.16.0
+  version: 5.17.0
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-01-10 00:00:00.000000000 Z
+date: 2024-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -258,6 +258,7 @@ files:
 - lib/openhab/core/events/item_state_changed_event.rb
 - lib/openhab/core/events/item_state_event.rb
 - lib/openhab/core/events/item_state_updated_event.rb
+- lib/openhab/core/events/item_time_series_updated_event.rb
 - lib/openhab/core/events/thing_status_info_event.rb
 - lib/openhab/core/events/timer_event.rb
 - lib/openhab/core/items.rb
@@ -348,6 +349,7 @@ files:
 - lib/openhab/core/types/rewind_fastforward_type.rb
 - lib/openhab/core/types/stop_move_type.rb
 - lib/openhab/core/types/string_type.rb
+- lib/openhab/core/types/time_series.rb
 - lib/openhab/core/types/type.rb
 - lib/openhab/core/types/un_def_type.rb
 - lib/openhab/core/types/up_down_type.rb
@@ -357,6 +359,7 @@ files:
 - lib/openhab/core_ext/ephemeris.rb
 - lib/openhab/core_ext/java/class.rb
 - lib/openhab/core_ext/java/duration.rb
+- lib/openhab/core_ext/java/instant.rb
 - lib/openhab/core_ext/java/list.rb
 - lib/openhab/core_ext/java/local_date.rb
 - lib/openhab/core_ext/java/local_time.rb
@@ -482,7 +485,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.4
+rubygems_version: 3.5.5
 signing_key: 
 specification_version: 4
 summary: JRuby Helper Libraries for openHAB Scripting