openhab-scripting 5.21.0 → 5.22.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 756e126e160f646932df226702f4174537f335211766d9eba33c2d44cf1c1c70
-  data.tar.gz: 6afda8cddcc7a0fd916fe061a2eb2dab4621d46cdcef75138b4c524db05b669d
+  metadata.gz: b2c5b8b2a28cbbda196f66340982141af673362693181e88588e89f9c4b1da29
+  data.tar.gz: 6a0483d0d94ae2a9492870e8089efd0b2a1afc400337d790a271b6fd9ca05ae3
 SHA512:
-  metadata.gz: c57f40667e47bacb3c2a2cc62f6fce829413cf832502e1f743cb82fbbc0e5a962800907b27261bea5513020612a8f7652378a7817aa6b0d924c88220ccca7328
-  data.tar.gz: 769878c8db809e0ed1815605551fc964de147329209e89517cab012a782b84e8a21e46fa445f3167723eea4f2454bd290a767991e39cfdb6495c742c874d295e
+  metadata.gz: 2115e707e47980b212827203b1401aeceb90c3c11fd0b8e91494581f12e728f4bc68d46c7f3b2991ff63a6f3db68ee45eb0b617e1a94ae642f6b2267de797f8c
+  data.tar.gz: ba2fd9524d6387287cbde50a8ff6cbc449069889836ced9e5b8cb79d8c7e3a4fe029804387d4866fed7b56b79e6aaba1584180fadc61d424555e0c755666cbbd

data/lib/openhab/core/actions/notification.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Actions
+      #
+      # Provides methods for {https://next.openhab.org/addons/integrations/openhabcloud/#cloud-notification-actions
+      # openHAB Cloud Notification Actions}.
+      #
+      class Notification
+        class << self
+          #
+          # Send a notification using
+          # {https://next.openhab.org/addons/integrations/openhabcloud/#cloud-notification-actions
+          # openHAB Cloud Notification Action}.
+          #
+          # @param msg [String] The message to send.
+          # @param email [String, nil] The email address to send to. If `nil`, the message will be broadcasted.
+          # @param icon [String, Symbol, nil] The icon name
+          #   (as described in {https://www.openhab.org/docs/configuration/items.html#icons Items}).
+          # @param tag [String, Symbol, nil] a name to group the type or severity of the notification.
+          # @param severity [String, Symbol, nil] Deprecated - an alias for `tag` for backwards compatibility.
+          # @param title [String, nil] The title of the notification.
+          #   When `nil`, it defaults to `openHAB` inside the Android and iOS apps.
+          # @param id [String, nil] An optional reference ID which can then be used
+          #   to {hide} or update the notification.
+          #   Subsequent notifications using the same reference ID will
+          #   update/overwrite the existing notification with the same ID.
+          # @param on_click [String, nil] The action to be performed when the user clicks on the notification.
+          #   Specified using the {https://next.openhab.org/addons/integrations/openhabcloud/#action-syntax
+          #   action syntax}.
+          # @param attachment [String, nil] The URL of the media attachment to be displayed with the notification.
+          #   This URL must be reachable by the push notification client.
+          # @param buttons [Array<String>, Hash<String, String>, nil] Buttons to include in the notification.
+          #   - In array form, each element is specified as `Title=$action`, where `$action` follows the
+          #   {https://next.openhab.org/addons/integrations/openhabcloud/#action-syntax action syntax}.
+          #   - In hash form, the keys are the button titles and the values are the actions.
+          #
+          #   The maximum number of buttons is 3.
+          # @return [void]
+          #
+          # @note The parameters `title`, `id`, `on_click`, `attachment`, and `buttons` were added in openHAB 4.2.
+          #
+          # @see https://www.openhab.org/addons/integrations/openhabcloud/
+          #
+          # @example Send a broadcast notification via openHAB Cloud
+          #   rule "Send an alert" do
+          #     changed Alarm_Triggered, to: ON
+          #     run { Notification.send "Red Alert!" }
+          #   end
+          #
+          # @example Provide action buttons in a notification
+          #   rule "Doorbell" do
+          #     changed Doorbell, to: ON
+          #     run do
+          #       Notification.send "Someone pressed the doorbell!",
+          #         title: "Doorbell",
+          #         attachment: "http://myserver.local/cameras/frontdoor.jpg",
+          #         buttons: {
+          #           "Show Camera" => "ui:/basicui/app?w=0001&sitemap=cameras",
+          #           "Unlock Door" => "command:FrontDoor_Lock:OFF"
+          #         }
+          #     end
+          #   end
+          #
+          def send(
+            msg,
+            email: nil,
+            icon: nil,
+            tag: nil,
+            severity: nil,
+            id: nil,
+            title: nil,
+            on_click: nil,
+            attachment: nil,
+            buttons: nil
+          )
+            unless Actions.const_defined?(:NotificationAction)
+              raise NotImplementedError, "NotificationAction is not available. Please install the openHAB Cloud addon."
+            end
+
+            args = []
+            if email
+              args.push(:send_notification, email)
+            else
+              args.push(:send_broadcast_notification)
+            end
+            tag ||= severity
+            args.push(msg.to_s, icon&.to_s, tag&.to_s)
+
+            # @!deprecated OH 4.1
+            if Core.version >= Core::V4_2
+              buttons ||= []
+              buttons = buttons.map { |title, action| "#{title}=#{action}" } if buttons.is_a?(Hash)
+              raise ArgumentError, "buttons must contain (0..3) elements." unless (0..3).cover?(buttons.size)
+
+              args.push(title&.to_s,
+                        id&.to_s,
+                        on_click&.to_s,
+                        attachment&.to_s,
+                        buttons[0]&.to_s,
+                        buttons[1]&.to_s,
+                        buttons[2]&.to_s)
+            end
+
+            NotificationAction.__send__(*args)
+          end
+
+          #
+          # Hide a notification by ID or tag.
+          #
+          # Either the `id` or `tag` parameter must be provided.
+          # When both are provided, two calls will be made to the NotificationAction:
+          # - Notifications matching the `id` will be hidden, and
+          # - Notifications matching the `tag` will be hidden, independently from the given tag.
+          #
+          # @param email [String, nil] The email address to hide notifications for.
+          #   If nil, hide broadcast notifications.
+          # @param id [String, nil] hide notifications associated with the given reference ID.
+          # @param tag [String, nil] hide notifications associated with the given tag.
+          # @return [void]
+          #
+          def hide(email: nil, id: nil, tag: nil)
+            unless Actions.const_defined?(:NotificationAction)
+              raise NotImplementedError, "NotificationAction is not available. Please install the openHAB Cloud addon."
+            end
+
+            raise ArgumentError, "Either id or tag must be provided." unless id || tag
+
+            args = []
+            if email
+              args.push(email)
+              notification = :notification
+            else
+              notification = :broadcast_notification
+            end
+
+            NotificationAction.__send__(:"hide_#{notification}_by_reference_id", *args, id) if id
+            NotificationAction.__send__(:"hide_#{notification}_by_tag", *args, tag) if tag
+          end
+
+          #
+          # Sends a log notification.
+          #
+          # Log notifications do not trigger a notification on the device.
+          #
+          # @param msg [String] The message to send.
+          # @param icon [String, Symbol, nil] The icon name
+          # @param tag [String, Symbol, nil] a name to group the type or severity of the notification.
+          # @return [void]
+          #
+          def log(msg, icon: nil, tag: nil)
+            NotificationAction.send_log_notification(msg.to_s, icon&.to_s, tag&.to_s)
+          end
+        end
+
+        Object.const_set(name.split("::").last, self)
+      end
+    end
+  end
+end

data/lib/openhab/core/actions.rb

@@ -17,9 +17,8 @@ module OpenHAB
     # * {Voice}
     #
     # From add-ons, e.g.:
-    # * NotificationAction (from
-    #   [openHAB Cloud Connector](https://www.openhab.org/addons/integrations/openhabcloud/);
-    #   see {notify notify})
+    # * {Notification NotificationAction} from
+    #   [openHAB Cloud Connector](https://www.openhab.org/addons/integrations/openhabcloud/)
     #
     # Thing-specific actions can be accessed from the {Things::Thing Thing} object.
     # See {Things::Thing#actions Thing#actions}.
@@ -51,85 +50,12 @@ module OpenHAB
       module_function
 
       #
-      # Send a notification using
-      # {https://next.openhab.org/addons/integrations/openhabcloud/#cloud-notification-actions
-      # openHAB Cloud Notification Action}.
+      # @!method notify(msg, email: nil, icon: nil, tag: nil, severity: nil, id: nil, title: nil, on_click: nil, attachment: nil, buttons: nil)
+      # @deprecated Use {Notification.send Notification.send} instead.
       #
-      # @param msg [String] The message to send.
-      # @param email [String, nil] The email address to send to. If `nil`, the message will be broadcast.
-      # @param icon [String, Symbol, nil] The icon name
-      #   (as described in {https://next.openhab.org/docs/configuration/items.html#icons Items}).
-      # @param severity [String, Symbol, nil] A description of the severity of the incident.
-      # @param title [String, nil] The title of the notification.
-      #   When `nil`, it defaults to `openHAB` inside the Android and iOS apps.
-      # @param on_click [String, nil] The action to be performed when the user clicks on the notification.
-      #   Specified using the {https://next.openhab.org/addons/integrations/openhabcloud/#action-syntax action syntax}.
-      # @param attachment [String, nil] The URL of the media attachment to be displayed with the notification.
-      #   This URL must be reachable by the push notification client.
-      # @param buttons [Array<String>, Hash<String, String>, nil] Buttons to include in the notification.
-      #   - In array form, each element is specified as `Title=$action`, where `$action` follows the
-      #   {https://next.openhab.org/addons/integrations/openhabcloud/#action-syntax action syntax}.
-      #   - In hash form, the keys are the button titles and the values are the actions.
-      #
-      #   The maximum number of buttons is 3.
-      # @return [void]
-      #
-      # @note The parameters `title`, `on_click`, `attachment`, and `buttons` were added in openHAB 4.2.
-      #
-      # @see https://www.openhab.org/addons/integrations/openhabcloud/
-      #
-      # @example Send a broadcast notification via openHAB Cloud
-      #   rule "Send an alert" do
-      #     changed Alarm_Triggered, to: ON
-      #     run { notify "Red Alert!" }
-      #   end
-      #
-      # @example Provide action buttons in a notification
-      #   rule "Doorbell" do
-      #     changed Doorbell, to: ON
-      #     run do
-      #       notify "Someone pressed the doorbell!",
-      #         title: "Doorbell",
-      #         attachment: "http://myserver.local/cameras/frontdoor.jpg",
-      #         buttons: {
-      #           "Show Camera" => "ui:/basicui/app?w=0001&sitemap=cameras",
-      #           "Unlock Door" => "command:FrontDoor_Lock:OFF"
-      #         }
-      #     end
-      #   end
-      #
-      def notify(
-        msg,
-        email: nil,
-        icon: nil,
-        severity: nil,
-        title: nil,
-        on_click: nil,
-        attachment: nil,
-        buttons: nil
-      )
-        unless Actions.const_defined?(:NotificationAction)
-          raise NotImplementedError, "NotificationAction is not available. Please install the openHAB Cloud addon."
-        end
-
-        args = []
-        if email
-          args.push(:send_notification, email)
-        else
-          args.push(:send_broadcast_notification)
-        end
-        args.push(msg.to_s, icon&.to_s, severity&.to_s)
-
-        # @!deprecated OH 4.1
-        if Core.version >= Core::V4_2
-          buttons ||= []
-          buttons = buttons.map { |title, action| "#{title}=#{action}" } if buttons.is_a?(Hash)
-          raise ArgumentError, "buttons must contain (0..3) elements." unless (0..3).cover?(buttons.size)
-
-          args.push(title&.to_s, on_click&.to_s, attachment&.to_s, buttons[0]&.to_s, buttons[1]&.to_s, buttons[2]&.to_s)
-        end
-
-        NotificationAction.__send__(*args)
+      def notify(*args, **kwargs)
+        logger.warn("`notify` method is deprecated. Use `Notification.send` instead.")
+        Notification.send(*args, **kwargs)
       end
     end
   end

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

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module OpenHAB
+  module Core
+    module Events
+      java_import org.openhab.core.thing.link.events.AbstractItemChannelLinkRegistryEvent,
+                  org.openhab.core.thing.link.events.ItemChannelLinkAddedEvent,
+                  org.openhab.core.thing.link.events.ItemChannelLinkRemovedEvent
+
+      #
+      # The {AbstractEvent} sent when an {Things::ItemChannelLink} is added or removed
+      # from its registry.
+      #
+      # @!attribute [r] link
+      #   @return [DTO::ItemChannelLinkDTO] The link that triggered this event.
+      #
+      class AbstractItemChannelLinkRegistryEvent < AbstractEvent; end
+
+      #
+      # The {AbstractEvent} sent with an `channel_linked` trigger.
+      #
+      class ItemChannelLinkAddedEvent < AbstractItemChannelLinkRegistryEvent; end
+
+      #
+      # The {AbstractEvent} sent with an `channel_unlinked` trigger.
+      #
+      class ItemChannelLinkRemovedEvent < AbstractItemChannelLinkRegistryEvent; end
+    end
+  end
+end

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

@@ -25,6 +25,9 @@ module OpenHAB
       #
       # The {AbstractEvent} sent with an `item_updated` trigger.
       #
+      # @!attribute [r] old_item
+      #   @return [DTO::ItemDTO] the old item before the update.
+      #
       class ItemUpdatedEvent < AbstractItemRegistryEvent; end
 
       #

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

@@ -28,6 +28,9 @@ module OpenHAB
       # The {AbstractEvent} sent with a
       # {DSL::Rules::BuilderDSL#thing_updated thing_updated trigger}.
       #
+      # @!attribute [r] old_thing
+      #   @return [DTO::AbstractThingDTO] the old thing before the update.
+      #
       class ThingUpdatedEvent < AbstractThingRegistryEvent; end
 
       #

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

@@ -0,0 +1,20 @@
+# 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
+      java_import org.openhab.core.events.system.StartlevelEvent
+
+      #
+      # The {AbstractEvent} sent when the system start level changed.
+      #
+      # @!attribute [r] startlevel
+      #   @return [Integer] The new start level.
+      #
+      class StartlevelEvent < AbstractEvent; end
+    end
+  end
+end

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

@@ -25,6 +25,31 @@ module OpenHAB
       #   UV_Index.average_since(1.hour.ago, :influxdb)
       #   Power_Usage.average_since(12.hours.ago, :rrd4j)
       #
+      # @example Time of day shortcuts
+      #   # Persistence methods accept any object that responds to #to_zoned_date_time, which includes
+      #   # LocalTime, LocalDate, and Ruby's Time, Date, and DateTime.
+      #   # This allows for easy querying of start of day
+      #   logger.info Power_Usage.average_since(LocalTime::MIDNIGHT)
+      #   logger.info Power_Usage.average_since(LocalDate.now)
+      #   # Ruby's Date can be used too
+      #   logger.info Power_Usage.average_since(Date.today)
+      #
+      #   # Yesterday
+      #   logger.info Power_Usage.average_between(Date.today - 1, Date.today)
+      #   # or
+      #   logger.info Power_Usage.average_between(LocalDate.now - 1, LocalDate.now)
+      #
+      #   # When passing the local time, today's date is assumed
+      #   logger.info Power_Usage.average_between(LocalTime.parse("4pm"), LocalTime.parse("9pm"))
+      #   # or
+      #   logger.info Power_Usage.average_between(Time.parse("4pm"), Time.parse("9pm"))
+      #
+      #   # Beware that Date, LocalDate, and LocalTime arithmetics will produce the same type, so
+      #   Power_Usage.average_between(LocalTime.parse("4pm") - 1.day, LocalTime.parse("9pm") - 1.day)
+      #   # Will still give you TODAY's data between 4pm and 9pm
+      #   # To get yesterday's data, use Time.parse, i.e.
+      #   Power_Usage.average_between(Time.parse("4pm") - 1.day, Time.parse("9pm") - 1.day)
+      #
       # @example Comparison using Quantity
       #   # Because Power_Usage has a unit, the return value
       #   # from average_since is a QuantityType
@@ -42,10 +67,17 @@ module OpenHAB
         #
         # A wrapper for {org.openhab.core.persistence.HistoricItem HistoricItem} that delegates to its state.
         #
+        # A {PersistedState} object can be directly used in arithmetic operations with {State} and
+        # other {PersistedState} objects.
+        #
         # @example
         #   max = Power_Usage.maximum_since(LocalTime::MIDNIGHT)
         #   logger.info "Highest power usage: #{max} occurred at #{max.timestamp}" if max > 5 | "kW"
         #
+        # @example Arithmetic operations
+        #   todays_rate = Energy_Prices.persisted_state(Date.today) # Energy_Prices' unit is "<CURRENCY>/kWh"
+        #   todays_cost = Daily_Energy_Consumption.state * todays_rate
+        #
         class PersistedState < SimpleDelegator
           extend Forwardable
 
@@ -65,6 +97,11 @@ module OpenHAB
             @historic_item = historic_item
             super(state || historic_item.state)
           end
+
+          # @!visibility private
+          def inspect
+            "#<#{self.class} #{state} at: #{timestamp} item: #{name}>"
+          end
         end
 
         # @deprecated Use {PersistedState} instead

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

@@ -146,8 +146,8 @@ module OpenHAB
             #   elsif other.is_a?(java.math.BigDecimal)
             #     self.class.new(to_big_decimal.add(other))
             #   elsif other.respond_to?(:to_d)
-            #     result = to_d + other
-            #     # result could already be a QuantityType
+            #     result = to_d + other.to_d
+            #     # result could already be a NumericType
             #     result = self.class.new(result) unless result.is_a?(NumericType)
             #     result
             #   elsif other.respond_to?(:coerce) && (lhs, rhs = other.coerce(to_d))
@@ -163,8 +163,8 @@ module OpenHAB
                 elsif other.is_a?(java.math.BigDecimal)
                   self.class.new(to_big_decimal.#{java_op}(other, java.math.MathContext::DECIMAL128))
                 elsif other.respond_to?(:to_d)
-                  result = to_d #{ruby_op} other
-                  # result could already be a QuantityType
+                  result = to_d #{ruby_op} other.to_d
+                  # result could already be a NumericType
                   result = self.class.new(result) unless result.is_a?(NumericType)
                   result
                 elsif other.respond_to?(:coerce) && (lhs, rhs = other.coerce(to_d))

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

@@ -179,6 +179,7 @@ module OpenHAB
           class_eval( # rubocop:disable Style/DocumentDynamicEvalDefinition https://github.com/rubocop/rubocop/issues/10179
             # def +(other)
             #   logger.trace("#{self} + #{other} (#{other.class})")
+            #   other = other.state if other.is_a?(Core::Items::Persistence::PersistedState)
             #   if other.is_a?(QuantityType)
             #     add_quantity(other)
             #   elsif (thread_unit = DSL.unit(dimension))
@@ -203,6 +204,7 @@ module OpenHAB
             <<~RUBY, __FILE__, __LINE__ + 1
               def #{ruby_op}(other)
                 logger.trace("\#{self} #{ruby_op} \#{other} (\#{other.class})")
+                other = other.state if other.is_a?(Core::Items::Persistence::PersistedState)
                 if other.is_a?(QuantityType)
                   #{java_op}_quantity(other)
                 elsif (thread_unit = DSL.unit(dimension))
@@ -235,6 +237,7 @@ module OpenHAB
           class_eval( # rubocop:disable Style/DocumentDynamicEvalDefinition https://github.com/rubocop/rubocop/issues/10179
             # def *(other)
             #   logger.trace("#{self} * #{other} (#{other.class})")
+            #   other = other.state if other.is_a?(Core::Items::Persistence::PersistedState)
             #   if other.is_a?(QuantityType)
             #     multiply_quantity(other)
             #   elsif other.is_a?(DecimalType)
@@ -252,6 +255,7 @@ module OpenHAB
             <<~RUBY, __FILE__, __LINE__ + 1
               def #{ruby_op}(other)
                 logger.trace("\#{self} #{ruby_op} \#{other} (\#{other.class})")
+                other = other.state if other.is_a?(Core::Items::Persistence::PersistedState)
                 if other.is_a?(QuantityType)
                   #{java_op}_quantity(other).unitize
                 elsif other.is_a?(DecimalType)

data/lib/openhab/core.rb

@@ -15,9 +15,10 @@ module OpenHAB
     V4_2 = Gem::Version.new("4.2.0").freeze
 
     # @return [Gem::Version] Returns the current openHAB version as a Gem::Version object
+    #   Note, this strips off snapshots, milestones and RC versions and returns the release version.
     # @!visibility private
     def self.version
-      @version ||= Gem::Version.new(VERSION).freeze
+      @version ||= Gem::Version.new(VERSION).release.freeze
     end
 
     raise "`openhab-scripting` requires openHAB >= 3.4.0" unless version >= Gem::Version.new("3.4.0")

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

@@ -89,6 +89,7 @@ module OpenHAB
         # @param [Command] command to send to object
         # @param [Duration] for duration for item to be in command state
         # @param [Command] on_expire Command to send when duration expires
+        # @param [true, false] only_when_ensured if true, only start the timed command if the command was ensured
         # @yield If a block is provided, `on_expire` is ignored and the block
         #   is expected to set the item to the desired state or carry out some
         #   other action.
@@ -104,27 +105,46 @@ module OpenHAB
         # @example
         #   Dimmer.on(for: 5.minutes) { |event| Dimmer.off if Light.on? }
         #
-        def command(command, for: nil, on_expire: nil, &block)
+        # @example Only start a timed command if the command was ensured
+        #   rule "Motion Detected" do
+        #     received_command Motion_Sensor, command: ON
+        #     run do
+        #       # Start the timer only if the command was ensured
+        #       # i.e. the light was off before the command was sent
+        #       # but if the timer was already started, extend it
+        #       FrontPorchLight.ensure.on for: 30.minutes, only_when_ensured: true
+        #     end
+        #   end
+        #
+        def command(command, for: nil, on_expire: nil, only_when_ensured: false, &block)
           duration = binding.local_variable_get(:for)
           return super(command) unless duration
 
           on_expire = block if block
 
+          create_ensured_timed_command = proc do
+            on_expire ||= default_on_expire(command)
+            if only_when_ensured
+              DSL.ensure_states do
+                create_timed_command(command, duration: duration, on_expire: on_expire) if super(command)
+              end
+            else
+              super(command)
+              create_timed_command(command, duration: duration, on_expire: on_expire)
+            end
+          end
+
           TimedCommand.timed_commands.compute(self) do |_key, timed_command_details|
             if timed_command_details.nil?
               # no prior timed command
-              on_expire ||= default_on_expire(command)
-              super(command)
-              create_timed_command(command, duration: duration, on_expire: on_expire)
+              create_ensured_timed_command.call
             else
               timed_command_details.mutex.synchronize do
                 if timed_command_details.resolution
                   # timed command that finished, but hadn't removed itself from the map yet
                   # (it doesn't do so under the mutex to prevent a deadlock).
                   # just create a new one
-                  on_expire ||= default_on_expire(command)
-                  super(command)
-                  create_timed_command(command, duration: duration, on_expire: on_expire)
+                  create_ensured_timed_command.call
                 else
                   # timed command still pending; reset it
                   logger.trace "Outstanding Timed Command #{timed_command_details} encountered - rescheduling"
@@ -132,7 +152,7 @@ module OpenHAB
                   timed_command_details.timer.reschedule(duration)
                   # disable the cancel rule while we send the new command
                   DSL.rules[timed_command_details.rule_uid].disable
-                  super(command)
+                  super(command) # This returns nil when "ensured"
                   DSL.rules[timed_command_details.rule_uid].enable
                   timed_command_details
                 end

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

@@ -135,7 +135,7 @@ module OpenHAB
         #   # return the script object into a variable
         #   door_check = script "Check all doors", id: "door_check", tags: :security do
         #     open_doors = gDoors.members.select(&:open?).map(&:label).join(", ")
-        #     notify("The following doors are open: #{open_doors}") unless open_doors.empty?
+        #     Notification.send("The following doors are open: #{open_doors}") unless open_doors.empty?
         #   end
         #
         #   # run is an alias of trigger
@@ -145,7 +145,7 @@ module OpenHAB
         #   # This script expects to be called with `message` as context/parameter
         #   DESTINATION_EMAIL = "myemail@example.com"
         #   script "Send Notifications", id: "send_alert" do
-        #     notify(message)
+        #     Notification.send(message)
         #     things["mail:smtp:local"].send_mail(DESTINATION_EMAIL, "OpenHAB Alert", message)
         #   end
         #
@@ -744,7 +744,7 @@ module OpenHAB
         #     changed Door_State
         #     debounce_for 10.minutes
         #     only_if { Door_State.open? }
-        #     run { notify("The Door has been open for 10 minutes!") }
+        #     run { Notification.send("The Door has been open for 10 minutes!") }
         #   end
         #
         def debounce_for(debounce_time)
@@ -898,6 +898,8 @@ module OpenHAB
         # supports one or more channels with one or more triggers. `thing` is an optional
         # parameter that makes it easier to set triggers on multiple channels on the same thing.
         #
+        # The `event` passed to run blocks will be a {Core::Events::ChannelTriggeredEvent}.
+        #
         # @param [String, Core::Things::Channel, Core::Things::ChannelUID] channels
         #   channels to create triggers for in form of 'binding_id:type_id:thing_id#channel_id'
         #   or 'channel_id' if thing is provided.
@@ -992,6 +994,8 @@ module OpenHAB
         #
         # Creates a channel linked trigger
         #
+        # The `event` passed to run blocks will be an {Core::Events::ItemChannelLinkAddedEvent}.
+        #
         # @param [Item, String, nil] item The item to create a trigger for. If nil, all items are matched.
         # @param [Core::Things::Channel, Core::Things::ChannelUID, String, nil] channel
         #   The channel to create a trigger for. If nil, all channels are matched.
@@ -1016,6 +1020,8 @@ module OpenHAB
         #
         # Creates a channel unlinked trigger
         #
+        # The `event` passed to run blocks will be an {Core::Events::ItemChannelLinkRemovedEvent}.
+        #
         # Note that the item or the thing it's linked to may no longer exist,
         # so if you try to access those objects they'll be nil.
         #
@@ -1054,7 +1060,7 @@ module OpenHAB
         # {Core::Events::ThingStatusInfoChangedEvent} depending on if the
         # triggering element was an item or a thing.
         #
-        # @param [Item, GroupItem::Members, Thing] items Objects to create trigger for.
+        # @param [Item, GroupItem::Members, Thing, ThingUID, Things::Registry] items Objects to create trigger for.
         # @param [State, Array<State>, #===, nil] from
         #   Only execute rule if previous state matches `from` state(s).
         # @param [State, Array<State>, #===, nil] to
@@ -1141,6 +1147,14 @@ module OpenHAB
         #     run { |event| logger.info("Thing #{event.uid} status <trigger> to #{event.status}") }
         #   end
         #
+        # @example Trigger when any Thing changes status
+        #   rule "Thing status monitoring" do
+        #     changed things, to: :offline
+        #     run do |event|
+        #       Notification.send("Thing #{event.thing.uid} is offline")
+        #     end
+        #   end
+        #
         # @example Real World Example
         #   rule "Log (or notify) when an exterior door is left open for more than 5 minutes" do
         #     changed ExteriorDoors.members, to: OPEN, for: 5.minutes
@@ -1160,11 +1174,13 @@ module OpenHAB
             case item
             when Core::Things::Thing,
                  Core::Things::ThingUID,
+                 Core::Things::Registry,
                  Core::Items::Item,
                  Core::Items::GroupItem::Members
               nil
             else
-              raise ArgumentError, "items must be an Item, GroupItem::Members, Thing, or ThingUID"
+              raise ArgumentError,
+                    "items must be an Item, GroupItem::Members, Thing, ThingUID, or Things::Registry"
             end
 
             logger.trace { "Creating changed trigger for entity(#{item}), to(#{to.inspect}), from(#{from.inspect})" }
@@ -1180,6 +1196,8 @@ module OpenHAB
         #
         # Create a cron trigger
         #
+        # The `event` passed to run blocks will be a {Core::Events::TimerEvent}.
+        #
         # @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 [Object] attach object to be attached to the trigger
@@ -1258,6 +1276,8 @@ module OpenHAB
         #
         # Create a rule that executes at the specified interval.
         #
+        # The `event` passed to run blocks will be a {Core::Events::TimerEvent}.
+        #
         # @param [String,
         #   Duration,
         #   java.time.MonthDay,
@@ -1400,6 +1420,8 @@ module OpenHAB
         #
         # Creates a trigger that executes when openHAB reaches a certain start level
         #
+        # The `event` passed to run blocks will be a {Core::Events::StartlevelEvent}.
+        #
         # 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
@@ -1570,6 +1592,8 @@ module OpenHAB
         #
         # Creates an item added trigger
         #
+        # The `event` passed to run blocks will be an {Core::Events::ItemAddedEvent}.
+        #
         # @param [String, nil] pattern The pattern to match items against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
@@ -1591,6 +1615,8 @@ module OpenHAB
         #
         # Creates an item removed trigger
         #
+        # The `event` passed to run blocks will be an {Core::Events::ItemRemovedEvent}.
+        #
         # @param [String, nil] pattern The pattern to match items against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
@@ -1612,6 +1638,8 @@ module OpenHAB
         #
         # Creates an item updated trigger
         #
+        # The `event` passed to run blocks will be an {Core::Events::ItemUpdatedEvent}.
+        #
         # @param [String, nil] pattern The pattern to match items against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
@@ -1632,6 +1660,8 @@ module OpenHAB
         #
         # Creates a thing added trigger
         #
+        # The `event` passed to run blocks will be a {Core::Events::ThingAddedEvent}.
+        #
         # @param [String, nil] pattern The pattern to match things against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
@@ -1653,6 +1683,8 @@ module OpenHAB
         #
         # Creates a thing removed trigger
         #
+        # The `event` passed to run blocks will be a {Core::Events::ThingRemovedEvent}.
+        #
         # @param [String, nil] pattern The pattern to match things against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
@@ -1674,6 +1706,8 @@ module OpenHAB
         #
         # Creates a thing updated trigger
         #
+        # The event passed to run blocks will be a {Core::Events::ThingUpdatedEvent}.
+        #
         # @param [String, nil] pattern The pattern to match things against
         # @param [Object] attach object to be attached to the trigger
         # @return [void]
@@ -1734,6 +1768,8 @@ module OpenHAB
         # To trigger just on the time portion of the item, use {every} instead, e.g.
         # `every :day, at: MyDateTimeItem`.
         #
+        # The `event` passed to run blocks will be a {Core::Events::TimerEvent}.
+        #
         # @param [Item, String, Symbol] item The item (or its name)
         # @return [void]
         #

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

@@ -79,6 +79,8 @@ module OpenHAB
                            when Core::Things::Thing,
                                 Core::Things::ThingUID
                              thing(thing: item, from: from, to: to)
+                           when Core::Things::Registry
+                             thing(thing: "*", from: from, to: to)
                            else
                              item(item: item, from: from, to: to)
                            end

data/lib/openhab/dsl/timer_manager.rb

@@ -112,11 +112,11 @@ module OpenHAB
       #
       # @example Extend an existing timer, or schedule a new one
       #   # This is technically the same functionality as just calling `after()` with an `id`,
-      #   # but allows you to performa extra steps if the timer is actually scheduled.
+      #   # but allows you to perform extra steps if the timer is actually scheduled.
       #   timers.schedule(item) do |timer|
       #     next timer.tap(&:reschedule) if timer
       #
-      #     notify("The lights were turned on")
+      #     Notification.send("The lights were turned on")
       #
       #     after(30.seconds) { item.off }
       #   end

data/lib/openhab/dsl/version.rb

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

data/lib/openhab/rspec/openhab/core/actions.rb

@@ -11,29 +11,47 @@ module OpenHAB
             email,
             msg,
             icon,
-            severity,
+            tag,
             title = nil,
+            id = nil,
             on_click = nil,
             attachment = nil,
             button1 = nil,
             button2 = nil,
             button3 = nil
           )
-            logger.debug("send_notification: #{email}, #{msg}, #{icon}, #{severity}, #{title}, #{on_click}, #{attachment}, #{button1}, #{button2}, #{button3}") # rubocop:disable Layout/LineLength
+            logger.debug("send_notification: #{email}, #{msg}, #{icon}, #{tag}, #{title}, #{id}, #{on_click}, #{attachment}, #{button1}, #{button2}, #{button3}") # rubocop:disable Layout/LineLength
           end
 
           def send_broadcast_notification(
             msg,
             icon,
-            severity,
+            tag,
             title = nil,
+            id = nil,
             on_click = nil,
             attachment = nil,
             button1 = nil,
             button2 = nil,
             button3 = nil
           )
-            logger.debug("send_broadcast_notification: #{msg}, #{icon}, #{severity}, #{title}, #{on_click}, #{attachment}, #{button1}, #{button2}, #{button3}") # rubocop:disable Layout/LineLength
+            logger.debug("send_broadcast_notification: #{msg}, #{icon}, #{tag}, #{title}, #{id}, #{on_click}, #{attachment}, #{button1}, #{button2}, #{button3}") # rubocop:disable Layout/LineLength
+          end
+
+          def hide_notification_by_reference_id(email, id)
+            logger.debug("hide_notification_by_reference_id: #{email}, #{id}")
+          end
+
+          def hide_notification_by_tag(email, tag)
+            logger.debug("hide_notification_by_tag: #{email}, #{tag}")
+          end
+
+          def hide_broadcast_notification_by_reference_id(id)
+            logger.debug("hide_broadcast_notification_by_reference_id: #{id}")
+          end
+
+          def hide_broadcast_notification_by_tag(tag)
+            logger.debug("hide_broadcast_notification_by_tag: #{tag}")
           end
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openhab-scripting
 version: !ruby/object:Gem::Version
-  version: 5.21.0
+  version: 5.22.1
 platform: ruby
 authors:
 - Brian O'Connell
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-06-28 00:00:00.000000000 Z
+date: 2024-07-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -238,6 +238,7 @@ files:
 - lib/openhab/core/actions/ephemeris.rb
 - lib/openhab/core/actions/exec.rb
 - lib/openhab/core/actions/http.rb
+- lib/openhab/core/actions/notification.rb
 - lib/openhab/core/actions/ping.rb
 - lib/openhab/core/actions/transformation.rb
 - lib/openhab/core/actions/voice.rb
@@ -250,6 +251,7 @@ files:
 - lib/openhab/core/entity_lookup.rb
 - lib/openhab/core/events.rb
 - lib/openhab/core/events/abstract_event.rb
+- lib/openhab/core/events/abstract_item_channel_link_registry_event.rb
 - lib/openhab/core/events/abstract_item_registry_event.rb
 - lib/openhab/core/events/abstract_thing_registry_event.rb
 - lib/openhab/core/events/channel_triggered_event.rb
@@ -259,6 +261,7 @@ files:
 - 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/startlevel_event.rb
 - lib/openhab/core/events/thing_status_info_event.rb
 - lib/openhab/core/events/timer_event.rb
 - lib/openhab/core/items.rb