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

Included in:
GenericItem
Defined in:
lib/openhab/core/items/item.rb

Overview

The core features of an openHAB item.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#accepted_command_typesArray<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 43

#accepted_data_typesArray<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 46

#all_groupsArray<GroupItem> (readonly)

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

Returns:



92
93
94
95
96
97
98
99
100
101
102
103
104
# File 'lib/openhab/core/items/item.rb', line 92

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

#channelThings::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:



295
296
297
# File 'lib/openhab/core/items/item.rb', line 295

def channel
  channel_uids.first&.channel
end

#channel_uidThings::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:



278
279
280
# File 'lib/openhab/core/items/item.rb', line 278

def channel_uid
  channel_uids.first
end

#channel_uidsArray<Things::ChannelUID> (readonly)

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



286
287
288
# File 'lib/openhab/core/items/item.rb', line 286

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

#channelsArray<Things::Channel> (readonly)

Return all of the channels this item is linked to.

Returns:



303
304
305
# File 'lib/openhab/core/items/item.rb', line 303

def channels
  channel_uids.map(&:channel)
end

#groupsArray<GroupItem> (readonly)

Returns all groups that this item is part of

Returns:



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

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

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:



322
323
324
# File 'lib/openhab/core/items/item.rb', line 322

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

#metadataMetadata::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:

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:



223
224
225
# File 'lib/openhab/core/items/item.rb', line 223

def metadata
  @metadata ||= Metadata::NamespaceHash.new(name)
end

#nameString (readonly)

The item's name.

Returns:

  • (String)


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

#providerorg.openhab.core.common.registry.Provider? (readonly)

Returns the provider for this item.

Returns:



409
410
411
# File 'lib/openhab/core/items/item.rb', line 409

def provider
  Provider.registry.provider_for(self)
end

#thingThings::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:



259
260
261
# File 'lib/openhab/core/items/item.rb', line 259

def thing
  all_linked_things.first
end

#thingsArray<Things::Thing> (readonly) Also known as: all_linked_things

Returns all of the item's linked things.

Returns:



268
269
270
# File 'lib/openhab/core/items/item.rb', line 268

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)


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

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)


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

def_type_predicate(:color)

#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)


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

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)


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

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)


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

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)


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

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)


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

def_type_predicate(:image)

#inspectString

Returns:

  • (String)


397
398
399
400
401
402
403
404
405
# File 'lib/openhab/core/items/item.rb', line 397

def inspect
  s = "#<OpenHAB::Core::Items::#{type}Item#{type_details} #{name} #{label.inspect} state=#{raw_state.inspect}"
  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

Overloads:

  • #linkThings::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:



360
361
362
363
364
365
366
367
368
369
370
371
372
# File 'lib/openhab/core/items/item.rb', line 360

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)


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

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)


78
79
80
81
82
83
# File 'lib/openhab/core/items/item.rb', line 78

def member_of?(*groups)
  groups.map! do |group|
    group.is_a?(GroupItem) ? group.name : group
  end
  !(group_names & groups).empty?
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)


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

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)


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

def_type_predicate(:player)

#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)


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

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)


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

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)


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

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)


240
241
242
243
244
245
246
247
248
249
250
251
252
# File 'lib/openhab/core/items/item.rb', line 240

def tagged?(*tags)
  tags.map! do |tag|
    # @deprecated OH3.4
    if tag.is_a?(Module)
      tag.simple_name
    elsif defined?(Semantics::SemanticTag) && tag.is_a?(Semantics::SemanticTag)
      tag.name
    else
      tag
    end
  end
  !(self.tags.to_a & tags).empty?
end

#to_sString

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

Returns:

  • (String)


54
55
56
# File 'lib/openhab/core/items/item.rb', line 54

def to_s
  label || name
end

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:



385
386
387
388
389
390
391
392
393
394
# File 'lib/openhab/core/items/item.rb', line 385

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