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

The item's category.

Returns:

  • (String)


308
309
310
311
312
313
314
315
316
# File 'lib/openhab/core/items/generic_item.rb', line 308

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:



330
331
332
333
334
335
336
337
338
339
# File 'lib/openhab/core/items/generic_item.rb', line 330

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) ⇒ 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.

Returns:

  • (self, nil)

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

See Also:



159
160
161
162
163
164
# File 'lib/openhab/core/items/generic_item.rb', line 159

def command(command)
  command = format_command(command)
  logger.trace "Sending Command #{command} to #{name}"
  $events.send_command(self, command)
  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)


269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
# File 'lib/openhab/core/items/generic_item.rb', line 269

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 174

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

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



202
203
204
205
206
207
# File 'lib/openhab/core/items/generic_item.rb', line 202

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