Module: OpenHAB::Core::Items::Item

Includes:
Persistence, Semantics, DSL::Items::Ensure::Item, DSL::Items::TimedCommand
Included in:
GenericItem
Defined in:
lib/openhab/core/items/item.rb

Overview

The core features of an openHAB item.

Constant Summary

Constants included from Semantics

Semantics::Equipment, Semantics::Location, Semantics::Point, Semantics::Property, Semantics::Tag

Constants included from Persistence

Persistence::HistoricState

Instance Attribute Summary collapse

Attributes included from Semantics

#equipment, #equipment_type, #location, #location_type, #point_type, #property_type, #semantic_type

Instance Method Summary collapse

Methods included from Semantics

add, #equipment?, #location?, lookup, #point?, #points, remove, #semantic?, tags

Methods included from DSL::Items::Ensure::Ensurable

#ensure

Methods included from Persistence

#average_between, #average_since, #average_until, #changed_between?, #changed_since?, #changed_until?, #count_between, #count_since, #count_state_changes_between, #count_state_changes_since, #count_state_changes_until, #count_until, #delta_between, #delta_since, #delta_until, #deviation_between, #deviation_since, #deviation_until, #evolution_rate, #evolution_rate_between, #evolution_rate_since, #evolution_rate_until, #historic_state, #last_change, #last_update, #maximum_between, #maximum_since, #maximum_until, #median_between, #median_since, #median_until, #minimum_between, #minimum_since, #minimum_until, #next_change, #next_state, #next_update, #persist, #persisted_state, #previous_state, #remove_all_states_between, #remove_all_states_since, #remove_all_states_until, #riemann_sum_between, #riemann_sum_since, #riemann_sum_until, #sum_between, #sum_since, #sum_until, #updated_between?, #updated_since?, #updated_until?, #variance_between, #variance_since, #variance_until

Instance Attribute Details

#accepted_command_types ⇒ Array<Class> (readonly)

Returns An array of Commands that can be sent as commands to this item.

Returns:

  • (Array<Class>) —

    An array of Commands that can be sent as commands to this item




# File 'lib/openhab/core/items/item.rb', line 61

#accepted_data_types ⇒ Array<Class> (readonly)

Returns An array of States that can be sent as commands to this item.

Returns:

  • (Array<Class>) —

    An array of States that can be sent as commands to this item




# File 'lib/openhab/core/items/item.rb', line 64

#all_groups ⇒ Array<GroupItem> (readonly)

Returns all groups that this item is a part of, as well as those groups’ groups, recursively

Returns:



261
262
263
264
265
266
267
268
269
270
271
272
273
 
# File 'lib/openhab/core/items/item.rb', line 261

def all_groups
  result = []
  new_groups = Set.new(groups)

  until new_groups.empty?
    result.concat(new_groups.to_a)
    new_groups.replace(new_groups.flat_map(&:groups))
    # remove any groups we already have in the result to avoid loops
    new_groups.subtract(result)
  end

  result
end

#channel ⇒ Things::Channel? (readonly)

Return the channel this item is linked to. If an item is linked to more than one channel, this method only returns the first channel.

Returns:



461
462
463
 
# File 'lib/openhab/core/items/item.rb', line 461

def channel
  channel_uids.first&.channel
end

#channel_uid ⇒ Things::ChannelUID? (readonly)

Return the UID of the channel this item is linked to. If an item is linked to more than one channel, this method only returns the first channel.

Returns:



444
445
446
 
# File 'lib/openhab/core/items/item.rb', line 444

def channel_uid
  channel_uids.first
end

#channel_uids ⇒ Array<Things::ChannelUID> (readonly)

Return the UIDs of all of the channels this item is linked to.

Returns:



452
453
454
 
# File 'lib/openhab/core/items/item.rb', line 452

def channel_uids
  Things::Links::Provider.registry.get_bound_channels(name)
end

#channels ⇒ Array<Things::Channel> (readonly)

Return all of the channels this item is linked to.

Returns:



469
470
471
 
# File 'lib/openhab/core/items/item.rb', line 469

def channels
  channel_uids.map(&:channel)
end

#command_description ⇒ Types::CommandDescription? (readonly)

Returns:




# File 'lib/openhab/core/items/item.rb', line 70

#formatted_state ⇒ String (readonly)

Format the item’s state according to its state description

This may include running a transformation.

Examples:

logger.info(Exterior_WindDirection.formatted_state) # => "NE (36°)"

Returns:

  • (String) —

    The formatted state



105
106
107
 
# File 'lib/openhab/core/items/item.rb', line 105

def formatted_state
  Item.item_states_event_builder.get_display_state(self)
end

#groups ⇒ Array<GroupItem> (readonly)

Returns all groups that this item is part of

Returns:



234
235
236
 
# File 'lib/openhab/core/items/item.rb', line 234

def groups
  group_names.filter_map { |name| EntityLookup.lookup_item(name) }
end

#last_state ⇒ State (readonly)

Returns The previous state of the item.

Returns:

  • (State) —

    The previous state of the item.

Since:

  • openHAB 5.0




# File 'lib/openhab/core/items/item.rb', line 73

#last_state_change ⇒ ZonedDateTime (readonly)

Returns The time of the last state change.

Returns:

Since:

  • openHAB 5.0




# File 'lib/openhab/core/items/item.rb', line 77

#last_state_update ⇒ ZonedDateTime (readonly)

Returns The time of the last state update.

Returns:

Since:

  • openHAB 5.0




# File 'lib/openhab/core/items/item.rb', line 81

#links ⇒ ItemChannelLinks (readonly)

Returns all of the item’s links (channels and link configurations).

Examples:

Get the configuration of the first link

LivingRoom_Light_Power.links.first.configuration

Remove all managed links

LivingRoom_Light_Power.links.clear

Returns:

See Also:



488
489
490
 
# File 'lib/openhab/core/items/item.rb', line 488

def links
  ItemChannelLinks.new(name, Things::Links::Provider.registry.get_links(name))
end

#metadata ⇒ Metadata::NamespaceHash (readonly)

Access to the item’s metadata.

Both the return value of this method as well as the individual namespaces can be treated as Hashes.

Examples assume the following items:

“‘xtend Switch Item1 { namespace1=“value” [ config1=“foo”, config2=“bar” ] } String StringItem1 “`

Examples:

Check namespace’s existence

Item1.metadata["namespace"].nil?
Item1.metadata.key?("namespace")

Access item’s metadata value

Item1.metadata["namespace1"].value

Access namespace1’s configuration

Item1.metadata["namespace1"]["config1"]

Safely search for the specified value - no errors are raised, only nil returned if a key in the chain doesn’t exist

Item1.metadata.dig("namespace1", "config1") # => "foo"
Item1.metadata.dig("namespace2", "config1") # => nil

Set item’s metadata value, preserving its config

# Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
Item1.metadata["namespace1"].value = "new value"
# Item1's metadata after: {"namespace1"=>["new value", {"config1"=>"foo", "config2"=>"bar"]}}

Set item’s metadata config, preserving its value

# Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
Item1.metadata["namespace1"].replace({ "scooby"=>"doo" })
# Item1's metadata after: {"namespace1"=>["value", {scooby="doo"}]}

Set a namespace to a new value and config in one line

# Item1's metadata before: {"namespace1"=>"value", {"config1"=>"foo", "config2"=>"bar"}}
Item1.metadata["namespace1"] = "new value", { "scooby"=>"doo" }
# Item1's metadata after: {"namespace1"=>["new value", {scooby="doo"}]}

Set item’s metadata value and clear its previous config

# Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
Item1.metadata["namespace1"] = "new value"
# Item1's metadata after: {"namespace1"=>"value" }

Set item’s metadata config, set its value to nil, and wiping out previous config

# Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
Item1.metadata["namespace1"] = { "newconfig"=>"value" }
# Item1's metadata after: {"namespace1"=>{"config1"=>"foo", "config2"=>"bar"}}

Update namespace1’s specific configuration, preserving its value and other config

# Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
Item1.metadata["namespace1"]["config1"] = "doo"
# Item1's metadata will be: {"namespace1"=>["value", {"config1"=>"doo", "config2"=>"bar"}]}

Add a new configuration to namespace1

# Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
Item1.metadata["namespace1"]["config3"] = "boo"
# Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar", config3="boo"}]}

Delete a config

# Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
Item1.metadata["namespace1"].delete("config2")
# Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo"}]}

Add a namespace and set it to a value

# Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
Item1.metadata["namespace2"] = "qx"
# Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace2"=>"qx"}

Add a namespace and set it to a value and config

# Item1's metadata before: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
Item1.metadata["namespace2"] = "qx", { "config1"=>"doo" }
# Item1's metadata after: {"namespace1"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace2"=>["qx", {"config1"=>"doo"}]}

Enumerate Item1’s namespaces

Item1.metadata.each { |namespace, metadata| logger.info("Item1's namespace: #{namespace}=#{metadata}") }

Add metadata from a hash

Item1.metadata.merge!({"namespace1"=>{"foo", {"config1"=>"baz"} ], "namespace2"=>{"qux", {"config"=>"quu"} ]})

Merge Item2’s metadata into Item1’s metadata

Item1.metadata.merge!(Item2.metadata)

Delete a namespace

Item1.metadata.delete("namespace1")

Delete all metadata of the item

Item1.metadata.clear

Does this item have any metadata?

Item1.metadata.any?

Store another item’s state

StringItem1.update "TEST"
Item1.metadata["other_state"] = StringItem1.state

Store event’s state

rule "save event state" do
  changed StringItem1
  run { |event| Item1.metadata["last_event"] = event.was }
end

If the namespace already exists: Update the value of a namespace but preserve its config; otherwise create a new namespace with the given value and nil config.

Item1.metadata["namespace"] = "value", Item1.metadata["namespace"]

Copy another namespace

# Item1's metadata before: {"namespace2"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}
Item1.metadata["namespace"] = Item1.metadata["namespace2"]
# Item1's metadata after: {"namespace2"=>["value", {"config1"=>"foo", "config2"=>"bar"}], "namespace"=>["value", {"config1"=>"foo", "config2"=>"bar"}]}

Returns:



392
393
394
 
# File 'lib/openhab/core/items/item.rb', line 392

def metadata
  Metadata::NamespaceHash.new(name)
end

#name ⇒ String (readonly)

The item’s name.

Returns:

  • (String) 



# File 'lib/openhab/core/items/item.rb', line 57

#provider ⇒ org.openhab.core.common.registry.Provider? (readonly)

Returns the provider for this item.

Returns:

  • (org.openhab.core.common.registry.Provider, nil) —

    Returns the provider for this item.



581
582
583
 
# File 'lib/openhab/core/items/item.rb', line 581

def provider
  Provider.registry.provider_for(self)
end

#state_description ⇒ Types::StateDescription? (readonly)

Returns:




# File 'lib/openhab/core/items/item.rb', line 67

#thing ⇒ Things::Thing? (readonly) Also known as: linked_thing

Return the item’s thing if this item is linked with a thing. If an item is linked to more than one channel, this method only returns the first thing.

Returns:



425
426
427
 
# File 'lib/openhab/core/items/item.rb', line 425

def thing
  all_linked_things.first
end

#things ⇒ Array<Things::Thing> (readonly) Also known as: all_linked_things

Returns all of the item’s linked things.

Returns:



434
435
436
 
# File 'lib/openhab/core/items/item.rb', line 434

def things
  Things::Links::Provider.registry.get_bound_things(name).map { |thing| Things::Proxy.new(thing) }
end

Instance Method Details

#call_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a call item.

Check if the item is a call item.

Returns:

  • (true, false) 


602
 
# File 'lib/openhab/core/items/item.rb', line 602

def_type_predicate(:call)

#color_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a color item.

Check if the item is a color item.

Returns:

  • (true, false) 


603
 
# File 'lib/openhab/core/items/item.rb', line 603

def_type_predicate(:color)

#command(command, source: nil) ⇒ self? Also known as: command!, <<

Send a command to this item

When this method is chained after the ensure method, or issued inside an ensure_states block, or after 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.

Examples:

Sending a Command to an item

MySwitch.command(ON) # The preferred method is `MySwitch.on`
Garage_Door.command(DOWN) # The preferred method is `Garage_Door.down`
SetTemperature.command 20 | "°C"

Sending a plain number to a NumberItem

SetTemperature.command(22.5) # if it accepts a DecimalType

Sending a string to a dimensioned NumberItem

SetTemperature.command("22.5 °C") # The string will be parsed and converted to a QuantityType

Parameters:

  • command (Command, #to_s) —

    command to send to the item. When given a Command argument, it will be passed directly. Otherwise, the result of ‘#to_s` will be parsed into a Command.

  • source (String, nil) (defaults to: nil) —

    Optional string to identify what sent the event.

Returns:

  • (self, nil) —

    nil when ‘ensure` is in effect and the item was already in the same state, otherwise the item.

See Also:



142
143
144
145
146
147
148
149
150
151
 
# File 'lib/openhab/core/items/item.rb', line 142

def command(command, source: nil)
  command = format_command(command)
  logger.trace { "Sending Command #{command} to #{name}" }
  if source
    Events.publisher.post(Events::ItemEventFactory.create_command_event(name, command, source.to_s))
  else
    $events.send_command(self, command)
  end
  Proxy.new(self)
end

#contact_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a contact item.

Check if the item is a contact item.

Returns:

  • (true, false) 


604
 
# File 'lib/openhab/core/items/item.rb', line 604

def_type_predicate(:contact)

#date_time_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a date_time item.

Check if the item is a date_time item.

Returns:

  • (true, false) 


605
 
# File 'lib/openhab/core/items/item.rb', line 605

def_type_predicate(:date_time)

#dimmer_item? ⇒ true, false

Note:

Color items are also considered dimmer items.

Note:

If the item is a group item, it will also return true if the base item is a dimmer item.

Check if the item is a dimmer item.

Returns:

  • (true, false) 


607
 
# File 'lib/openhab/core/items/item.rb', line 607

def_type_predicate(:dimmer)

#group_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a group item.

Check if the item is a group item.

Returns:

  • (true, false) 


608
 
# File 'lib/openhab/core/items/item.rb', line 608

def_type_predicate(:group)

#image_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a image item.

Check if the item is a image item.

Returns:

  • (true, false) 


609
 
# File 'lib/openhab/core/items/item.rb', line 609

def_type_predicate(:image)

#inspect ⇒ String

Returns:

  • (String) 


563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
 
# File 'lib/openhab/core/items/item.rb', line 563

def inspect
  s = "#<OpenHAB::Core::Items::#{type}Item#{type_details} #{name} #{label.inspect} state=#{raw_state.inspect}"
  # @deprecated OH 4.3 Remove if guard when dropping support for OH 4.3
  if respond_to?(:last_state)
    s += " last_state=#{last_state.inspect}" if last_state
    s += " last_state_update=#{last_state_update}" if last_state_update
    s += " last_state_change=#{last_state_change}" if last_state_change
  end
  s += " category=#{category.inspect}" if category
  s += " tags=#{tags.to_a.inspect}" unless tags.empty?
  s += " groups=#{group_names}" unless group_names.empty?
  meta = metadata.to_h
  s += " metadata=#{meta.inspect}" unless meta.empty?
  "#{s}>"
end

#link ⇒ Things::ItemChannelLink? #link(channel, config = {}) ⇒ Things::ItemChannelLink

Overloads:

  • #link ⇒ Things::ItemChannelLink?

    Returns the item’s link. If an item is linked to more than one channel, this method only returns the first link.

    Returns:

  • #link(channel, config = {}) ⇒ Things::ItemChannelLink

    Links the item to a channel.

    Examples:

    Link an item to a channel

    LivingRoom_Light_Power.link("mqtt:topic:livingroom-light:power")

    Link to a Thing’s channel

    LivingRoom_Light_Power.link(things["mqtt:topic:livingroom-light"].channels["power"])

    Specify a link configuration

    High_Temperature_Alert.link(
  "mqtt:topic:outdoor-thermometer:temperature",
  profile: "system:hysteresis",
  lower: "29 °C",
  upper: "30 °C")

    Parameters:

    Returns:

    See Also:

Returns:



526
527
528
529
530
531
532
533
534
535
536
537
538
 
# File 'lib/openhab/core/items/item.rb', line 526

def link(channel = nil, config = nil)
  return Things::Links::Provider.registry.get_links(name).first if channel.nil? && config.nil?

  config ||= {}
  Core::Things::Links::Provider.create_link(self, channel, config).tap do |new_link|
    provider = Core::Things::Links::Provider.current
    if !(current_link = provider.get(new_link.uid))
      provider.add(new_link)
    elsif current_link.configuration != config
      provider.update(new_link)
    end
  end
end

#location_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a location item.

Check if the item is a location item.

Returns:

  • (true, false) 


610
 
# File 'lib/openhab/core/items/item.rb', line 610

def_type_predicate(:location)

#member_of?(*groups) ⇒ true, false

Checks if this item is a member of at least one of the given groups.

Examples:

event.item.member_of?(gFullOn)

Parameters:

  • groups (String, GroupItem) —

    the group to check membership in

Returns:

  • (true, false) 


247
248
249
250
251
252
 
# File 'lib/openhab/core/items/item.rb', line 247

def member_of?(*groups)
  groups.map! do |group|
    group.is_a?(GroupItem) ? group.name : group
  end
  !!group_names.intersect?(groups)
end

#number_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a number item.

Check if the item is a number item.

Returns:

  • (true, false) 


611
 
# File 'lib/openhab/core/items/item.rb', line 611

def_type_predicate(:number)

#player_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a player item.

Check if the item is a player item.

Returns:

  • (true, false) 


612
 
# File 'lib/openhab/core/items/item.rb', line 612

def_type_predicate(:player)

#refresh ⇒ Item

Send the REFRESH command to the item

Returns:

  • (Item) —

    ‘self`




# File 'lib/openhab/core/items/item.rb', line 161

#rollershutter_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a rollershutter item.

Check if the item is a rollershutter item.

Returns:

  • (true, false) 


613
 
# File 'lib/openhab/core/items/item.rb', line 613

def_type_predicate(:rollershutter)

#string_item? ⇒ true, false

Note:

If the item is a group item, it will also return true if the base item is a string item.

Check if the item is a string item.

Returns:

  • (true, false) 


614
 
# File 'lib/openhab/core/items/item.rb', line 614

def_type_predicate(:string)

#switch_item? ⇒ true, false

Note:

Color and dimmer items are also considered switch items.

Note:

If the item is a group item, it will also return true if the base item is a switch item.

Check if the item is a switch item.

Returns:

  • (true, false) 


616
 
# File 'lib/openhab/core/items/item.rb', line 616

def_type_predicate(:switch)

#tagged?(*tags) ⇒ true, false

Checks if this item has at least one of the given tags.

Examples:

event.item.tagged?("Setpoint")
event.item.tagged?(Semantics::Switch)

Parameters:

  • tags (String, Module) —

    the tag(s) to check

Returns:

  • (true, false) 


409
410
411
412
413
414
415
416
417
418
 
# File 'lib/openhab/core/items/item.rb', line 409

def tagged?(*tags)
  tags.map! do |tag|
    if tag.is_a?(Semantics::SemanticTag)
      tag.name
    else
      tag
    end
  end
  !!self.tags.to_a.intersect?(tags)
end

#to_s ⇒ String

The item’s label if one is defined, otherwise its #name.

Returns:

  • (String) 


90
91
92
 
# File 'lib/openhab/core/items/item.rb', line 90

def to_s
  label || name
end

#unlink(channel) ⇒ Things::ItemChannelLink?

Removes a link to a channel from managed link providers.

Parameters:

Returns:

Raises:

  • (FrozenError) —

    if the link is not managed by a managed link provider.

See Also:



551
552
553
554
555
556
557
558
559
560
 
# File 'lib/openhab/core/items/item.rb', line 551

def unlink(channel)
  link_to_delete = Things::Links::Provider.create_link(self, channel, {})
  provider = Things::Links::Provider.registry.provider_for(link_to_delete.uid)
  unless provider.is_a?(ManagedProvider)
    raise FrozenError,
          "Cannot remove the link #{link_to_delete.uid} from non-managed provider #{provider.inspect}"
  end

  provider.remove(link_to_delete.uid)
end

#update(state) ⇒ self? Also known as: update!

Send an update to this item

Examples:

Updating to a State

DoorStatus.update(OPEN)
InsideTemperature.update 20 | "°C"

Updating to NULL, the two following are equivalent:

DoorStatus.update(nil)
DoorStatus.update(NULL)

Updating with a plain number

PeopleCount.update(5) # A plain NumberItem

Updating with a string to a dimensioned NumberItem

InsideTemperature.update("22.5 °C") # The string will be parsed and converted to a QuantityType

Parameters:

  • state (State, #to_s, nil) —

    the state to update the item. When given a State argument, it will be passed directly. Otherwise, the result of ‘#to_s` will be parsed into a State first. If `nil` is passed, the item will be updated to NULL.

Returns:

  • (self, nil) —

    nil when ‘ensure` is in effect and the item was already in the same state, otherwise the item.



189
190
191
192
193
194
 
# File 'lib/openhab/core/items/item.rb', line 189

def update(state)
  state = format_update(state)
  logger.trace { "Sending Update #{state} to #{name}" }
  $events.post_update(self, state)
  Proxy.new(self)
end