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

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

Instance Method Summary collapse

Methods included from Semantics

#equipment?, #location?, #point?, #points, #semantic?

Methods included from Item

#inspect, #member_of?, #provider, #tagged?, #thing, #things, #to_s

Methods included from Persistence

#average_between, #average_since, #changed_between?, #changed_since?, #count_between, #count_since, #count_state_changes_between, #count_state_changes_since, #delta_between, #delta_since, #deviation_between, #deviation_since, #evolution_rate, #historic_state, #last_update, #maximum_between, #maximum_since, #minimum_between, #minimum_since, #persist, #previous_state, #sum_between, #sum_since, #updated_between?, #updated_since?, #variance_between, #variance_since

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

#ensure

Instance Attribute Details

#categoryString

The item's category.

Returns:

  • (String)


255
256
257
258
259
260
261
262
263
# File 'lib/openhab/core/items/generic_item.rb', line 255

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)


85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
# File 'lib/openhab/core/items/generic_item.rb', line 85

def formatted_state
  # use to_string, not to_s, to get the original openHAB toString(), instead of any overrides
  # the JRuby library has defined
  raw_state_string = raw_state.to_string

  return raw_state_string unless (pattern = state_description&.pattern)

  transformed_state_string = org.openhab.core.transform.TransformationHelper.transform(OSGi.bundle_context,
                                                                                       pattern,
                                                                                       raw_state_string)
  return state.format(pattern) if transformed_state_string.nil? || transformed_state_string == raw_state_string

  transformed_state_string
rescue org.openhab.core.transform.TransformationException
  raw_state_string
end

#labelString

The item's descriptive label.

Returns:

  • (String)


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

#nameString (readonly)

The item's name.

Returns:

  • (String)


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

#raw_stateState (readonly)

Get the raw item state.

The state of the item, including possibly NULL or UNDEF

Returns:



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

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:



110
111
112
# File 'lib/openhab/core/items/generic_item.rb', line 110

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:



277
278
279
280
281
282
283
284
285
286
# File 'lib/openhab/core/items/generic_item.rb', line 277

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

Send a command to this item

When this method is chained after the ensure method, or issued inside an ensure_states block, the command will only be sent if the item is not already in the same state.

Parameters:

  • command (Command)

    command to send to the item

Returns:

  • (self, nil)

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

See Also:



137
138
139
140
141
142
# File 'lib/openhab/core/items/generic_item.rb', line 137

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)


216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
# File 'lib/openhab/core/items/generic_item.rb', line 216

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 114

#refreshItem

Send the REFRESH command to the item

Returns:



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

#state?true, false

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

Returns:

  • (true, false)


70
71
72
# File 'lib/openhab/core/items/generic_item.rb', line 70

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

#undef?true, false

Check if the item state == UNDEF

Returns:

  • (true, false)


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

#update(state) ⇒ self?

Send an update to this item

Parameters:

Returns:

  • (self, nil)

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



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

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