Class: OpenHAB::Core::Items::GenericItem

Inherits:
Object
  • Object
show all
Includes:
Item, Persistence, Semantics, DSL::Items::Ensure::Item, DSL::Items::TimedCommand
Defined in:
lib/openhab/core/items/generic_item.rb

Overview

The abstract base class for all items.

See Also:

  • orgorg.openhaborg.openhab.coreorg.openhab.core.itemsorg.openhab.core.items.GenericItem

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

Attributes included from Item

#accepted_command_types, #accepted_data_types, #all_groups, #channel, #channel_uid, #channel_uids, #channels, #groups, #links, #metadata, #provider, #thing, #things

Instance Method Summary collapse

Methods included from Semantics

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

Methods included from Item

#call_item?, #color_item?, #contact_item?, #date_time_item?, #dimmer_item?, #group_item?, #image_item?, #inspect, #link, #location_item?, #member_of?, #number_item?, #player_item?, #rollershutter_item?, #string_item?, #switch_item?, #tagged?, #to_s, #unlink

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, #sum_between, #sum_since, #sum_until, #updated_between?, #updated_since?, #updated_until?, #variance_between, #variance_since, #variance_until

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

#ensure

Instance Attribute Details

#category ⇒ String Also known as: icon

The item’s category (icon).

Returns:

  • (String) 


313
314
315
316
317
318
319
320
321
 
# File 'lib/openhab/core/items/generic_item.rb', line 313

def category=(value)
  modify do
    value = value&.to_s
    next if category == value

    @modified = true
    set_category(value)
  end
end

#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



103
104
105
 
# File 'lib/openhab/core/items/generic_item.rb', line 103

def formatted_state
  GenericItem.item_states_event_builder.get_display_state(self)
end

#label ⇒ String

The item’s descriptive label.

Returns:

  • (String) 



# File 'lib/openhab/core/items/generic_item.rb', line 66

#name ⇒ String (readonly)

The item’s name.

Returns:

  • (String) 



# File 'lib/openhab/core/items/generic_item.rb', line 62

#raw_state ⇒ State (readonly)

Get the raw item state.

The state of the item, including possibly NULL or UNDEF

Returns:



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

alias_method :raw_state, :state

#state ⇒ State? (readonly)

Returns openHAB item state if state is not UNDEF or NULL, nil otherwise. This makes it easy to use with the [Ruby safe navigation operator ‘&.`](docs.ruby-lang.org/en/master/syntax/calling_methods_rdoc.html#label-Safe+Navigation+Operator) Use #undef? or #null? to check for those states.

Returns:



115
116
117
 
# File 'lib/openhab/core/items/generic_item.rb', line 115

def state
  raw_state if state?
end

#tags ⇒ Array<String> #tags=(values) ⇒ void

The item’s tags

Overloads:

  • #tags ⇒ Array<String>

    Returns the item’s tags.

    Returns:

  • #tags=(values) ⇒ void

    This method returns an undefined value.

    Sets the item’s tags.

    To remove all tags, assign an empty array or nil.

    Parameters:

Returns:



337
338
339
340
341
342
343
344
345
346
 
# File 'lib/openhab/core/items/generic_item.rb', line 337

def tags=(values)
  modify do
    values = DSL::Items::ItemBuilder.normalize_tags(*values)
    next if values.to_set == tags.to_set

    @modified = true
    remove_all_tags
    add_tags(values)
  end
end

Instance Method Details

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



160
161
162
163
164
165
166
167
168
169
 
# File 'lib/openhab/core/items/generic_item.rb', line 160

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

#modify(force: false) { ... } ⇒ Object

Defers notifying openHAB of modifications to multiple attributes until the block is complete.

Examples:

Modify label and tags for an item

MySwitch.modify do
  MySwitch.label = "New Label"
  MySwitch.tags = :labeled
end

Parameters:

  • force (true, false) (defaults to: false) —

    When true, allow modifications to file-based items. Normally a FrozenError is raised when attempting to modify file-based items, since they will then be out-of-sync with the definition on disk. Advanced users may do this knowingly and intentionally though, so an escape hatch is provided to allow runtime modifications.

Yields:

Returns:

  • (Object) —

    the block’s return value

Raises:

  • (ArgumentError) 


274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
 
# File 'lib/openhab/core/items/generic_item.rb', line 274

def modify(force: false)
  raise ArgumentError, "you must pass a block to modify" unless block_given?
  return yield if instance_variable_defined?(:@modifying) && @modifying

  begin
    provider = self.provider
    if provider && !provider.is_a?(org.openhab.core.common.registry.ManagedProvider)
      raise FrozenError, "Cannot modify item #{name} from provider #{provider.inspect}." unless force

      provider = nil
      logger.debug { "Forcing modifications to non-managed item #{name}" }
    end
    @modified = false
    @modifying = true

    r = yield

    provider&.update(self) if @modified
    r
  ensure
    @modifying = false
  end
end

#null? ⇒ true, false

Check if the item state == NULL

Returns:

  • (true, false) 



# File 'lib/openhab/core/items/generic_item.rb', line 119

#refresh ⇒ Item

Send the REFRESH command to the item

Returns:

  • (Item) —

    ‘self`




# File 'lib/openhab/core/items/generic_item.rb', line 179

#state? ⇒ true, false

Check if the item has a state (not UNDEF or NULL)

Returns:

  • (true, false) 


88
89
90
 
# File 'lib/openhab/core/items/generic_item.rb', line 88

def state?
  !raw_state.is_a?(Types::UnDefType)
end

#time_series=(time_series) ⇒ void

This method returns an undefined value.

Set a new time series.

This will trigger a time_series_updated event.

Parameters:

Since:

  • openHAB 4.1




# File 'lib/openhab/core/items/generic_item.rb', line 245

#undef? ⇒ true, false

Check if the item state == UNDEF

Returns:

  • (true, false) 



# File 'lib/openhab/core/items/generic_item.rb', line 123

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



207
208
209
210
211
212
 
# File 'lib/openhab/core/items/generic_item.rb', line 207

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