openHAB

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

#all_states_between, #all_states_since, #all_states_until, #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:



249
250
251
252
253
254
255
256
257
258
259
260
261
 
# File 'lib/openhab/core/items/item.rb', line 249

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:



449
450
451
 
# File 'lib/openhab/core/items/item.rb', line 449

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:



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

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:



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

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:



457
458
459
 
# File 'lib/openhab/core/items/item.rb', line 457

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



93
94
95
 
# File 'lib/openhab/core/items/item.rb', line 93

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:



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

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

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



476
477
478
 
# File 'lib/openhab/core/items/item.rb', line 476

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:

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:



380
381
382
 
# File 'lib/openhab/core/items/item.rb', line 380

def metadata
  @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:



563
564
565
 
# File 'lib/openhab/core/items/item.rb', line 563

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:



413
414
415
 
# File 'lib/openhab/core/items/item.rb', line 413

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:



422
423
424
 
# File 'lib/openhab/core/items/item.rb', line 422

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) 


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

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) 


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

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:



130
131
132
133
134
135
136
137
138
139
 
# File 'lib/openhab/core/items/item.rb', line 130

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) 


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

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) 


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

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) 


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

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) 


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

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) 


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

def_type_predicate(:image)

#inspect ⇒ String

Returns:

  • (String) 


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

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

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



514
515
516
517
518
519
520
521
522
523
524
525
526
 
# File 'lib/openhab/core/items/item.rb', line 514

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) 


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

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) 


235
236
237
238
239
240
 
# File 'lib/openhab/core/items/item.rb', line 235

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) 


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

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) 


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

def_type_predicate(:player)

#refresh ⇒ Item

Send the REFRESH command to the item

Returns:




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

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


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

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) 


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

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) 


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

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) 


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

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) 


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

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:



539
540
541
542
543
544
545
546
547
548
 
# File 'lib/openhab/core/items/item.rb', line 539

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.



177
178
179
180
181
182
 
# File 'lib/openhab/core/items/item.rb', line 177

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