Class: OpenHAB::DSL::Items::ItemBuilder

Inherits:
Object
  • Object
show all
Includes:
Core::EntityLookup
Defined in:
lib/openhab/dsl/items/builder.rb

Overview

The ItemBuilder DSL allows you to customize an Item

Direct Known Subclasses

GroupItemBuilder

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Core::EntityLookup

#items, #method_missing, #things

Constructor Details

#initialize(type, name = nil, label = nil, provider:, dimension: nil, unit: nil, format: nil, range: nil, step: nil, read_only: nil, command_options: nil, state_options: nil, icon: nil, group: nil, groups: nil, tag: nil, tags: nil, autoupdate: nil, thing: nil, channel: nil, channels: nil, expire: nil, alexa: nil, ga: nil, homekit: nil, matter: nil, metadata: nil, state: nil) ⇒ ItemBuilder

Returns a new instance of ItemBuilder.

Parameters:

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

    The unit dimension for a NumberItem (see #dimension) Note the dimension must be properly capitalized.

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

    The unit for a NumberItem (see #unit)

  • format (String, nil) (defaults to: nil) —

    The formatting pattern for the item’s state (see #format)

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

    The icon to be associated with the item (see #icon)

  • group (String, GroupItem, GroupItemBuilder, Array<String, GroupItem, GroupItemBuilder>, nil) (defaults to: nil) —

    Group(s) to which this item should be added (see #group).

  • groups (String, GroupItem, GroupItemBuilder, Array<String, GroupItem, GroupItemBuilder>, nil) (defaults to: nil) —

    Fluent alias for group.

  • tag (String, Symbol, Semantics::Tag, Array<String, Symbol, Semantics::Tag>, nil) (defaults to: nil) —

    Tag(s) to apply to this item (see #tag).

  • tags (String, Symbol, Semantics::Tag, Array<String, Symbol, Semantics::Tag>, nil) (defaults to: nil) —

    Fluent alias for tag.

  • autoupdate (true, false, nil) (defaults to: nil) —

    Autoupdate setting (see #autoupdate)

  • thing (String, Core::Things::Thing, Core::Things::ThingUID, DSL::Things::Builder::ThingBuilder, nil) (defaults to: nil) —

    A Thing to be used as the base for the channel.

  • channel (String, Symbol, Core::Things::ChannelUID, Core::Things::Channel, nil) (defaults to: nil) —

    Channel to link the item to (see #channel).

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

    An expiration specification (see #expire).

  • alexa (String, Symbol, Array<(String, Hash<String, Object>)>, nil) (defaults to: nil) —

    Alexa metadata (see #alexa)

  • ga (String, Symbol, Array<(String, Hash<String, Object>)>, nil) (defaults to: nil) —

    Google Assistant metadata (see #ga)

  • homekit (String, Symbol, Array<(String, Hash<String, Object>)>, nil) (defaults to: nil) —

    Homekit metadata (see #homekit)

  • matter (String, Symbol, Array<(String, Hash<String, Object>)>, nil) (defaults to: nil) —

    Matter metadata (see #matter)

  • metadata (Hash<String, Hash>) (defaults to: nil) —

    Generic metadata (see #metadata)

  • state (State) (defaults to: nil) —

    Initial state

Raises:

  • (ArgumentError) 


323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
 
# File 'lib/openhab/dsl/items/builder.rb', line 323

def initialize(type,
               name = nil,
               label = nil,
               provider:,
               dimension: nil,
               unit: nil,
               format: nil,
               range: nil,
               step: nil,
               read_only: nil,
               command_options: nil,
               state_options: nil,
               icon: nil,
               group: nil,
               groups: nil,
               tag: nil,
               tags: nil,
               autoupdate: nil,
               thing: nil,
               channel: nil,
               channels: nil,
               expire: nil,
               alexa: nil,
               ga: nil, # rubocop:disable Naming/MethodParameterName
               homekit: nil,
               matter: nil,
               metadata: nil,
               state: nil)
  raise ArgumentError, "`name` cannot be nil" if name.nil?

  if dimension
    raise ArgumentError, "`dimension` can only be specified with NumberItem" unless type == :number

    begin
      org.openhab.core.types.util.UnitUtils.parse_dimension(dimension.to_s)
    rescue java.lang.IllegalArgumentException
      raise ArgumentError, "Invalid dimension '#{dimension}'"
    end
  end

  name = name.name if name.respond_to?(:name)
  if provider.is_a?(GroupItemBuilder)
    name = "#{provider.name_base}#{name}"
    label = "#{provider.label_base}#{label}".strip if label
  end
  @provider = provider
  @type = type
  @name = name.to_s
  @label = label
  @dimension = dimension
  @format = format
  @range = range
  @step = step
  @read_only = read_only
  @command_options = command_options
  @state_options = state_options
  self.unit = unit
  @icon = icon
  @groups = []
  @tags = []
  @metadata = Core::Items::Metadata::NamespaceHash.new
  @metadata.merge!(metadata) if metadata
  @autoupdate = autoupdate
  @channels = []
  @thing = thing
  @expire = nil
  if expire
    expire = Array(expire)
    expire_config = expire.pop if expire.last.is_a?(Hash)
    expire_config ||= {}
    self.expire(*expire, **expire_config)
  end
  self.alexa(alexa) if alexa
  self.ga(ga) if ga
  self.homekit(homekit) if homekit
  self.matter(matter) if matter
  self.state = state

  self.group(*group)
  self.groups(*groups)

  self.tag(*tag)
  self.tags(*tags)

  self.channel(*channel)
  self.channels(*channels)
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class OpenHAB::Core::EntityLookup

Instance Attribute Details

#autoupdate ⇒ true, ...

Autoupdate setting

Returns:

  • (true, false, nil) 


253
254
255
 
# File 'lib/openhab/dsl/items/builder.rb', line 253

def autoupdate
  @autoupdate
end

#channels=(value) ⇒ Array<String, Symbol, Core::Things::ChannelUID, Core::Things::Channel, Array>

Returns Channel to link the item to.

Returns:




# File 'lib/openhab/dsl/items/builder.rb', line 268

#command_options ⇒ Hash, ...

A list of valid commands If a hash, keys are commands, and values are labels

Returns:



243
244
245
 
# File 'lib/openhab/dsl/items/builder.rb', line 243

def command_options
  @command_options
end

#dimension ⇒ String?

Unit dimension (for number items only)

If #unit is provided, and #dimension is not, it will be inferred.

Returns:

  • (String, nil) 


219
220
221
 
# File 'lib/openhab/dsl/items/builder.rb', line 219

def dimension
  @dimension
end

#format ⇒ String?

The formatting pattern for the item’s state

If #unit is provided, and #format is not, it will be inferred.

Returns:

  • (String, nil) 


229
230
231
 
# File 'lib/openhab/dsl/items/builder.rb', line 229

def format
  @format
end

#groups=(value) ⇒ Array<String, GroupItem>

Returns Groups to which this item should be added.

Returns:

  • (Array<String, GroupItem>) —

    Groups to which this item should be added




# File 'lib/openhab/dsl/items/builder.rb', line 272

#icon ⇒ Symbol, ...

The icon to be associated with the item

Returns:



250
251
252
 
# File 'lib/openhab/dsl/items/builder.rb', line 250

def icon
  @icon
end

#label ⇒ String?

Item label

Returns:

  • (String, nil) 


213
214
215
 
# File 'lib/openhab/dsl/items/builder.rb', line 213

def label
  @label
end

#metadata ⇒ Core::Items::Metadata::NamespaceHash (readonly)

Returns:



258
259
260
 
# File 'lib/openhab/dsl/items/builder.rb', line 258

def metadata
  @metadata
end

#name ⇒ String

Item name

Returns:

  • (String) 


210
211
212
 
# File 'lib/openhab/dsl/items/builder.rb', line 210

def name
  @name
end

#range ⇒ Range?

The valid range for a number item

Returns:



232
233
234
 
# File 'lib/openhab/dsl/items/builder.rb', line 232

def range
  @range
end

#read_only ⇒ true, ... Also known as: read_only?

If the item is read-only, and does not accept commands

Returns:

  • (true, false, nil) 


238
239
240
 
# File 'lib/openhab/dsl/items/builder.rb', line 238

def read_only
  @read_only
end

#state ⇒ Core::Types::State

Initial state

If #state is set to a QuantityType, and #unit is not set, it will be inferred.

Returns:



264
265
266
 
# File 'lib/openhab/dsl/items/builder.rb', line 264

def state
  @state
end

#state_options ⇒ Hash, ...

A list of valid states If a hash, keys are commands, and values are labels

Returns:



247
248
249
 
# File 'lib/openhab/dsl/items/builder.rb', line 247

def state_options
  @state_options
end

#step ⇒ Number?

The step size for a number item

Returns:

  • (Number, nil) 


235
236
237
 
# File 'lib/openhab/dsl/items/builder.rb', line 235

def step
  @step
end

#tags=(value) ⇒ Array<String>

Returns Tags to apply to this item.

Returns:

  • (Array<String>) —

    Tags to apply to this item




# File 'lib/openhab/dsl/items/builder.rb', line 275

#thing ⇒ String, ...

Returns Thing from which to resolve relative channel ids.

Returns:



256
257
258
 
# File 'lib/openhab/dsl/items/builder.rb', line 256

def thing
  @thing
end

#type ⇒ Symbol (readonly)

The type of this item

Examples:

type #=> :switch

Returns:



207
208
209
 
# File 'lib/openhab/dsl/items/builder.rb', line 207

def type
  @type
end

#unit ⇒ String?

Unit (for number items only)

Returns:

  • (String, nil) 


223
224
225
 
# File 'lib/openhab/dsl/items/builder.rb', line 223

def unit
  @unit
end

Instance Method Details

#alexa(value, config = nil) ⇒ void

This method returns an undefined value.

Shortcut for adding Alexa metadata

Parameters:

  • value (String, Symbol) —

    Type of Alexa endpoint

  • config (Hash, nil) (defaults to: nil) —

    Additional Alexa configuration

See Also:




# File 'lib/openhab/dsl/items/builder.rb', line 472

#channel(channel, config = {}) ⇒ Array<String, Symbol, Core::Things::ChannelUID, Core::Things::Channel, Array> #channels ⇒ Array<String, Symbol, Core::Things::ChannelUID, Core::Things::Channel, Array> #channels(*channels) ⇒ Array<String, Symbol, Core::Things::ChannelUID, Core::Things::Channel, Array> Also known as: channels

Add a channel link to this item.

Examples:

items.build do
  date_time_item Bedroom_Light_Updated do
    channel "hue:0210:1:bulb1:color", profile: "system:timestamp-update"
  end
end

Relative channel name

items.build do
  switch_item Bedroom_Light, thing: "mqtt:topic:bedroom-light", channel: :power
end

Multiple channels

items.build do
  dimmer_item DemoDimmer, channels: ["hue:0210:bridge:1:color", "knx:device:bridge:generic:controlDimmer"]
end

Multiple channels in a block

items.build do
  dimmer_item DemoDimmer do
    channel "hue:0210:bridge:1:color"
    channel "knx:device:bridge:generic:controlDimmer"
  end
end

Multiple channels with config

items.build do
  dimmer_item DemoDimmer, channels: [["hue:0210:bridge:1:color", profile: "system:follow"],
                                     "knx:device:bridge:generic:controlDimmer"]
end

Overloads:

Returns:



575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
 
# File 'lib/openhab/dsl/items/builder.rb', line 575

def channel(*channels)
  return @channels if channels.empty?

  channels = [channels] if channels.length == 2 && channels[1].is_a?(Hash)

  channels.each do |channel|
    orig_channel = channel
    channel = channel.first if channel.is_a?(Array)
    next if channel.is_a?(String) ||
            channel.is_a?(Symbol) ||
            channel.is_a?(Core::Things::ChannelUID) ||
            channel.is_a?(Core::Things::Channel)

    raise ArgumentError, "channel #{orig_channel.inspect} must be a `String`, `Symbol`, `ChannelUID`, or " \
                         "`Channel`, or a two element array with the first element those types, and the " \
                         "second element a Hash"
  end

  @channels.concat(channels)
end

#expire(duration, command: nil, state: nil, ignore_state_updates: nil, ignore_commands: nil) ⇒ void

This method returns an undefined value.

Configure item expiration

Examples:

Get the current expire setting

expire

Clear any expire setting

expire nil

Use a duration

expire 5.hours

Use a string duration

expire "5h"

Set a specific state on expiration

expire 5.minutes, NULL
expire 5.minutes, state: NULL

Send a command on expiration

expire 5.minutes, command: OFF

Specify the duration and command in the same string

expire "5h,command=OFF"

Set the expire configuration

expire 5.minutes, ignore_state_updates: true

Parameters:

  • duration (String, Duration, nil) —

    Duration after which the command or state should be applied

  • command (String, nil) (defaults to: nil) —

    Command to send on expiration

  • state (String, nil) (defaults to: nil) —

    State to set on expiration

  • ignore_state_updates (true, false) (defaults to: nil) —

    When true, state updates will not reset the expire timer

  • ignore_commands (true, false) (defaults to: nil) —

    When true, commands will not reset the expire timer

Raises:

  • (ArgumentError) 


627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
 
# File 'lib/openhab/dsl/items/builder.rb', line 627

def expire(*args, command: nil, state: nil, ignore_state_updates: nil, ignore_commands: nil)
  unless (0..2).cover?(args.length)
    raise ArgumentError,
          "wrong number of arguments (given #{args.length}, expected 0..2)"
  end
  return @expire if args.empty?

  state = args.last if args.length == 2
  raise ArgumentError, "cannot provide both command and state" if command && state

  duration = args.first
  return @expire = nil if duration.nil?

  duration = duration.to_s[2..].downcase if duration.is_a?(Duration)
  state = "'#{state}'" if state.respond_to?(:to_str) && type == :string

  value = duration
  value += ",state=#{state}" if state
  value += ",command=#{command}" if command

  config = { ignoreStateUpdates: ignore_state_updates, ignoreCommands: ignore_commands }
  config.compact!
  @expire = [value, config]
end

#ga(value, config = nil) ⇒ void

This method returns an undefined value.

Shortcut for adding Google Assistant metadata

Parameters:

  • value (String, Symbol) —

    Type of Google Assistant endpoint

  • config (Hash, nil) (defaults to: nil) —

    Additional Google Assistant configuration

See Also:




# File 'lib/openhab/dsl/items/builder.rb', line 483

#group(group) ⇒ Array<String, GroupItemBulder, GroupItem> #groups ⇒ Array<String, GroupItemBulder, GroupItem> #groups(*groups) ⇒ Array<String, GroupItemBulder, GroupItem> Also known as: groups

Add this item to a group

Overloads:

Returns:



459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/openhab/dsl/items/builder.rb', line 459

def group(*groups)
  return @groups if groups.empty?

  unless groups.all? do |group|
           group.is_a?(String) || group.is_a?(Core::Items::GroupItem) || group.is_a?(GroupItemBuilder)
         end
    raise ArgumentError, "`group` must be a `GroupItem`, `GroupItemBuilder`, or a `String`"
  end

  @groups.concat(groups)
end

#homekit(value, config = nil) ⇒ void

This method returns an undefined value.

Shortcut for adding Homekit metadata

Parameters:

  • value (String, Symbol) —

    Type of Homekit accessory or characteristic

  • config (Hash, nil) (defaults to: nil) —

    Additional Homekit configuration

See Also:




# File 'lib/openhab/dsl/items/builder.rb', line 494

#inspect ⇒ String

Returns:

  • (String) 


734
735
736
737
738
739
740
741
 
# File 'lib/openhab/dsl/items/builder.rb', line 734

def inspect
  s = "#<OpenHAB::Core::Items::#{inspect_type}ItemBuilder#{type_details} #{name} #{label.inspect}"
  s += " category=#{icon.inspect}" if icon
  s += " tags=#{tags.inspect}" unless tags.empty?
  s += " groups=#{groups.map { |g| g.respond_to?(:name) ? g.name : g }.inspect}" unless groups.empty?
  s += " metadata=#{metadata.to_h.inspect}" unless metadata.empty?
  "#{s}>"
end

#matter(value, config = nil) ⇒ void

This method returns an undefined value.

Shortcut for adding Matter metadata

Parameters:

  • value (String, Symbol) —

    Matter device type or attribute(s)

  • config (Hash, nil) (defaults to: nil) —

    Additional Matter configuration

See Also:



516
517
518
519
520
521
 
# File 'lib/openhab/dsl/items/builder.rb', line 516

i[alexa ga homekit matter].each do |shortcut|
  define_method(shortcut) do |value = nil, config = nil|
    value, config = value if value.is_a?(Array)
    metadata[shortcut] = [value, config]
  end
end

#tag(tag) ⇒ Array<String> #tags ⇒ Array<String> #tags(*tags) ⇒ Array<String> Also known as: tags

Tag item

Overloads:

  • #tag(tag) ⇒ Array<String>

    Parameters:

    • tag (String, Symbol, Semantics::Tag)

    Returns:

  • #tags ⇒ Array<String>

    Returns:

  • #tags(*tags) ⇒ Array<String>

    Parameters:

    • tags (String, Symbol, Semantics::Tag)

    Returns:

Returns:



436
437
438
439
440
 
# File 'lib/openhab/dsl/items/builder.rb', line 436

def tag(*tags)
  return @tags if tags.empty?

  @tags.concat(Tags.normalize(*tags))
end

#to_s ⇒ String

The item’s label if one is defined, otherwise its name.

Returns:

  • (String) 


416
417
418
 
# File 'lib/openhab/dsl/items/builder.rb', line 416

def to_s
  label || name
end