openHAB

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:

Defined Under Namespace

Classes: HistoricState

Instance Method Summary collapse

Instance Method Details

#all_states_between(start, finish, service = nil) ⇒ Array<HistoricState>

Returns all the states 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:

Since:

  • openHAB 4.0



300
301
302
303
304
305
 
# File 'lib/openhab/core/items/persistence.rb', line 300

%i[persist last_update].each do |method|
  define_method(method) do |service = nil|
    service ||= persistence_service
    Actions::PersistenceExtensions.public_send(method, self, service&.to_s)
  end
end

#all_states_since(timestamp, service = nil) ⇒ Array<HistoricState>

Returns all the states 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:

Since:

  • openHAB 4.0




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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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




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

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

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

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

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

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

#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



318
319
320
321
322
 
# File 'lib/openhab/core/items/persistence.rb', line 318

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 155

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




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

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

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

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

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




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