Module: OpenHAB::Core::Items::Persistence

Included in:

GenericItem

Defined in:

lib/openhab/core/items/persistence.rb

Overview

Items extensions to support openHAB’s Persistence feature.

Examples:

The following examples are based on these items

Number        UV_Index
Number:Power  Power_Usage "Power Usage [%.2f W]"

Getting persistence data from the system default persistence service

UV_Index.average_since(1.hour.ago)      # returns a DecimalType
Power_Usage.average_since(12.hours.ago) # returns a QuantityType that corresponds to the item's type

Querying a non-default persistence service

UV_Index.average_since(1.hour.ago, :influxdb)
Power_Usage.average_since(12.hours.ago, :rrd4j)

Comparison using Quantity

# Because Power_Usage has a unit, the return value
# from average_since is a QuantityType which can be
# compared against a string with quantity
if Power_Usage.average_since(15.minutes.ago) > 5 | "kW"
  logger.info("The power usage exceeded its 15 min average)
end

HistoricState

max = Power_Usage.maximum_since(LocalTime::MIDNIGHT)
logger.info("Max power usage today: #{max}, at: #{max.timestamp})

See Also:

• Persistence Block

Defined Under Namespace

Classes: HistoricState

Instance Method Summary

• #average_between(start, finish, service = nil) ⇒ DecimalType, ...

  Returns the average value of the item’s state between two points in time.

• #average_since(timestamp, service = nil) ⇒ DecimalType, ...

  Returns the average value of the item’s state since the given time.

• #changed_between?(start, finish, service = nil) ⇒ true, false

  Whether the item’s state changed between two points in time.

• #changed_since?(timestamp, service = nil) ⇒ true, false

  Whether the item’s state has changed since the given time.

• #count_between(start, finish, service = nil) ⇒ Integer

  Returns the number of available historic data points between two points in time.

• #count_since(timestamp, service = nil) ⇒ Integer

  Returns the number of available historic data points from a point in time until now.

• #count_state_changes_between(start, finish, service = nil) ⇒ Integer (also: #state_changes_between)

  Returns the number of changes in historic data points between two points in time.

• #count_state_changes_since(timestamp, service = nil) ⇒ Integer (also: #state_changes_since)

  Returns the number of changes in historic data points from a point in time until now.

• #delta_between(start, finish, service = nil) ⇒ DecimalType, ...

  Returns the difference value of the item’s state between two points in time.

• #delta_since(timestamp, service = nil) ⇒ DecimalType, ...

  Returns the difference value of the item’s state since the given time.

• #deviation_between(start, finish, service = nil) ⇒ DecimalType, ...

  Returns the standard deviation of the item’s state between two points in time.

• #deviation_since(timestamp, service = nil) ⇒ DecimalType, ...

  Returns the standard deviation of the item’s state since the given time.

• #evolution_rate(timestamp, service = nil) ⇒ DecimalType, ...

  Returns the evolution rate of the item’s state.

• #historic_state(timestamp, service = nil) ⇒ HistoricState^?

  Returns the the item’s state at the given time.

• #last_update(service = nil) ⇒ ZonedDateTime^?

  Returns the time the item was last updated.

• #maximum_between(start, finish, service = nil) ⇒ HistoricState^?

  Returns the maximum value of the item’s state between two points in time.

• #maximum_since(timestamp, service = nil) ⇒ HistoricState^?

  Returns the maximum value of the item’s state since the given time.

• #minimum_between(start, finish, service = nil) ⇒ HistoricState^?

  Returns the minimum value of the item’s state between two points in time.

• #minimum_since(timestamp, service = nil) ⇒ HistoricState^?

  Returns the minimum value of the item’s state since the given time.

• #persist(service = nil) ⇒ void

  Persists the state of the item.

• #previous_state(service = nil, skip_equal: false) ⇒ HistoricState^?

  Return the previous state of the item.

• #sum_between(start, finish, service = nil) ⇒ DecimalType, ...

  Returns the sum of the item’s state between two points in time.

• #sum_since(timestamp, service = nil) ⇒ DecimalType, ...

  Returns the sum of the item’s state since the given time.

• #updated_between?(start, finish, service = nil) ⇒ true, false

  Whether the item’s state was updated between two points in time.

• #updated_since?(timestamp, service = nil) ⇒ true, false

  Whether the item’s state has been updated since the given time.

• #variance_between(start, finish, service = nil) ⇒ DecimalType, ...

  Returns the variance of the item’s state between two points in time.

• #variance_since(timestamp, service = nil) ⇒ DecimalType, ...

  Returns the variance of the item’s state since the given time.

Instance Method Details

#average_between(start, finish, service = nil) ⇒ DecimalType, ...

Returns the average value of the item’s state between two points in time

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (DecimalType, QuantityType, nil) —

  The average value between ‘start` and `finish`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 108

#average_since(timestamp, service = nil) ⇒ DecimalType, ...

Returns the average value of the item’s state since the given time

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (DecimalType, QuantityType, nil) —

  The average value since ‘timestamp`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 101

#changed_between?(start, finish, service = nil) ⇒ true, false

Whether the item’s state changed between two points in time

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (true, false) —

  True if the item’s state changed between ‘start` and `finish`, False otherwise.

# File 'lib/openhab/core/items/persistence.rb', line 182

#changed_since?(timestamp, service = nil) ⇒ true, false

Whether the item’s state has changed since the given time

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (true, false) —

  True if the item’s state has changed since the given ‘timestamp`, False otherwise.

# File 'lib/openhab/core/items/persistence.rb', line 176

#count_between(start, finish, service = nil) ⇒ Integer

Returns the number of available historic data points between two points in time.

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (Integer) —

  The number of values persisted for this item.

# File 'lib/openhab/core/items/persistence.rb', line 263

#count_since(timestamp, service = nil) ⇒ Integer

Returns the number of available historic data points from a point in time until now.

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (Integer) —

  The number of values persisted for this item.

# File 'lib/openhab/core/items/persistence.rb', line 257

#count_state_changes_between(start, finish, service = nil) ⇒ Integer Also known as: state_changes_between

Returns the number of changes in historic data points between two points in time.

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (Integer) —

  The number of values persisted for this item.

# File 'lib/openhab/core/items/persistence.rb', line 276

#count_state_changes_since(timestamp, service = nil) ⇒ Integer Also known as: state_changes_since

Returns the number of changes in historic data points from a point in time until now.

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (Integer) —

  The number of values persisted for this item.

# File 'lib/openhab/core/items/persistence.rb', line 270

#delta_between(start, finish, service = nil) ⇒ DecimalType, ...

Returns the difference value of the item’s state between two points in time

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (DecimalType, QuantityType, nil) —

  The difference value between ‘start` and `finish`, or nil if no previous state could be found.

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

#delta_since(timestamp, service = nil) ⇒ DecimalType, ...

Returns the difference value of the item’s state since the given time

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (DecimalType, QuantityType, nil) —

  The difference value since ‘timestamp`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 116

#deviation_between(start, finish, service = nil) ⇒ DecimalType, ...

Returns the standard deviation of the item’s state between two points in time

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (DecimalType, QuantityType, nil) —

  The standard deviation between ‘start` and `finish`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 138

#deviation_since(timestamp, service = nil) ⇒ DecimalType, ...

Returns the standard deviation of the item’s state since the given time

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (DecimalType, QuantityType, nil) —

  The standard deviation since ‘timestamp`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 131

#evolution_rate(timestamp, service = nil) ⇒ DecimalType, ... #evolution_rate(start, finish, service = nil) ⇒ DecimalType, ...

Returns the evolution rate of the item’s state

Overloads:

• #evolution_rate(timestamp, service = nil) ⇒ DecimalType, ...

  Returns the evolution rate of the item’s state since the given time

  Parameters:

  • timestamp (#to_zoned_date_time) —

    The point in time from which to search

  • service (Symbol, String) (defaults to: nil) —

    An optional persistence id instead of the default persistence service.

  Returns:

  • (DecimalType, QuantityType, nil) —

    The evolution rate since ‘timestamp`, or nil if no previous state could be found.

• #evolution_rate(start, finish, service = nil) ⇒ DecimalType, ...

  Returns the evolution rate of the item’s state between two points in time

  Parameters:

  • start (#to_zoned_date_time) —

    The point in time from which to search

  • finish (#to_zoned_date_time) —

    The point in time to which to search

  • service (Symbol, String) (defaults to: nil) —

    An optional persistence id instead of the default persistence service.

  Returns:

  • (DecimalType, QuantityType, nil) —

    The evolution rate between ‘start` and `finish`, or nil if no previous state could be found.

Returns:

• (DecimalType, QuantityType, nil) —

  The evolution rate since ‘timestamp`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 189

#historic_state(timestamp, service = nil) ⇒ HistoricState^?

Returns the the item’s state at the given time

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time at which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (HistoricState, nil) —

  The item’s state at ‘timestamp`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 207

#last_update(service = nil) ⇒ ZonedDateTime^?

Returns the time the item was last updated.

Parameters:

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (ZonedDateTime, nil) —

  The timestamp of the last update

# File 'lib/openhab/core/items/persistence.rb', line 96

#maximum_between(start, finish, service = nil) ⇒ HistoricState^?

Returns the maximum value of the item’s state between two points in time

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (HistoricState, nil) —

  The maximum value between ‘start` and `finish`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 221

#maximum_since(timestamp, service = nil) ⇒ HistoricState^?

Returns the maximum value of the item’s state since the given time

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (HistoricState, nil) —

  The maximum value since ‘timestamp`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 214

#minimum_between(start, finish, service = nil) ⇒ HistoricState^?

Returns the minimum value of the item’s state between two points in time

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (HistoricState, nil) —

  The minimum value between ‘start` and `finish`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 236

#minimum_since(timestamp, service = nil) ⇒ HistoricState^?

Returns the minimum value of the item’s state since the given time

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (HistoricState, nil) —

  The minimum value since ‘timestamp`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 229

#persist(service = nil) ⇒ void

This method returns an undefined value.

Persists the state of the item

Parameters:

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

# File 'lib/openhab/core/items/persistence.rb', line 91

#previous_state(service = nil, skip_equal: false) ⇒ HistoricState^?

Return the previous state of the item

Parameters:

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

  if true, skips equal state values and searches the first state not equal the current state

• service (String) (defaults to: nil) —

  the name of the PersistenceService to use

Returns:

• (HistoricState, nil) —

  the previous state or nil if no previous state could be found, or if the default persistence service is not configured or does not refer to a valid service

# File 'lib/openhab/core/items/persistence.rb', line 316

def previous_state(service = nil, skip_equal: false)
  service ||= persistence_service
  result = Actions::PersistenceExtensions.previous_state(self, skip_equal, service&.to_s)
  HistoricState.new(quantify(result.state), result) if result
end

#sum_between(start, finish, service = nil) ⇒ DecimalType, ...

Returns the sum of the item’s state between two points in time

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (DecimalType, QuantityType, nil) —

  The sum between ‘start` and `finish`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 153

#sum_since(timestamp, service = nil) ⇒ DecimalType, ...

Returns the sum of the item’s state since the given time

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (DecimalType, QuantityType, nil) —

  The sum since ‘timestamp`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 146

#updated_between?(start, finish, service = nil) ⇒ true, false

Whether the item’s state was updated between two points in time

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (true, false) —

  True if the item’s state was updated between ‘start` and `finish`, False otherwise.

# File 'lib/openhab/core/items/persistence.rb', line 250

#updated_since?(timestamp, service = nil) ⇒ true, false

Whether the item’s state has been updated since the given time

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (true, false) —

  True if the item’s state has been updated since the given ‘timestamp`, False otherwise.

# File 'lib/openhab/core/items/persistence.rb', line 244

#variance_between(start, finish, service = nil) ⇒ DecimalType, ...

Returns the variance of the item’s state between two points in time

Parameters:

• start (#to_zoned_date_time) —

  The point in time from which to search

• finish (#to_zoned_date_time) —

  The point in time to which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (DecimalType, QuantityType, nil) —

  The variance between ‘start` and `finish`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 168

#variance_since(timestamp, service = nil) ⇒ DecimalType, ...

Returns the variance of the item’s state since the given time

Parameters:

• timestamp (#to_zoned_date_time) —

  The point in time from which to search

• service (Symbol, String) (defaults to: nil) —

  An optional persistence id instead of the default persistence service.

Returns:

• (DecimalType, QuantityType, nil) —

  The variance since ‘timestamp`, or nil if no previous state could be found.

# File 'lib/openhab/core/items/persistence.rb', line 161