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.

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

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

#categoryString 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_stateString (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

#labelString

The item's descriptive label.

Returns:

  • (String)


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

#nameString (readonly)

The item's name.

Returns:

  • (String)


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

#raw_stateState (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

#stateState? (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 &. 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

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

The item's tags

Overloads:

  • #tagsArray<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

#refreshItem

Send the REFRESH command to the item

Returns:



# 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