Class: LIFX::Client

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
RequiredKeywordArguments
Defined in:
lib/lifx/client.rb

Overview

Client is the top level interface to the library. It mainly maps methods to the backing NetworkContext instance.

Defined Under Namespace

Classes: DiscoveryTimeout

Constant Summary collapse

DISCOVERY_DEFAULT_TIMEOUT =

Default timeout in seconds for discovery

10

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from RequiredKeywordArguments

#required!

Constructor Details

#initialize(transport_manager: required!('transport_manager')) ⇒ Client

Returns a new instance of Client

Parameters:

  • transport_manager: (TransportManager) (defaults to: required!('transport_manager'))

    Specify the TransportManager



30
31
32
# File 'lib/lifx/client.rb', line 30

def initialize(transport_manager: required!('transport_manager'))
  @context = NetworkContext.new(transport_manager: transport_manager)
end

Instance Attribute Details

#contextNetworkContext (readonly)

Refers to the client's network context.

Returns:



27
28
29
# File 'lib/lifx/client.rb', line 27

def context
  @context
end

Class Method Details

.lanClient

Returns a LIFX::Client set up for accessing devices on the LAN

Returns:

  • (Client)

    A LAN LIFX::Client



16
17
18
# File 'lib/lifx/client.rb', line 16

def lan
  @lan ||= new(transport_manager: TransportManager::LAN.new)
end

Instance Method Details

#discoverClient

This method tells the NetworkContext to look for devices asynchronously.

Returns:



39
40
41
# File 'lib/lifx/client.rb', line 39

def discover
  @context.discover
end

#discover!(timeout: DISCOVERY_DEFAULT_TIMEOUT, condition_interval: 0.1) {|Client| ... } ⇒ Client

This method tells the NetworkContext to look for devices, and will block until there's at least one device.

Examples:

Wait until at least three lights have been found

client.discover! { |c| c.lights.count >= 3 }

Parameters:

  • timeout: (Numeric) (defaults to: DISCOVERY_DEFAULT_TIMEOUT)

    How long to try to wait for before returning

  • condition_interval: (Numeric) (defaults to: 0.1)

    Seconds between evaluating the block

Yields:

  • (Client)

    This block is evaluated every condition_interval seconds. If true, method returns. If no block is supplied, it will block until it finds at least one light.

Returns:

Raises:



55
56
57
58
59
60
61
62
63
64
65
66
# File 'lib/lifx/client.rb', line 55

def discover!(timeout: DISCOVERY_DEFAULT_TIMEOUT, condition_interval: 0.1, &block)
  block ||= -> { self.lights.count > 0 }
  try_until -> { block.arity == 1 ? block.call(self) : block.call },
    timeout: timeout,
    timeout_exception: DiscoveryTimeout,
    condition_interval: condition_interval,
    action_interval: 1 do
    discover
    refresh
  end
  self
end

#flush(timeout: nil) ⇒ void

This method returns an undefined value.

Blocks until all messages have been sent to the gateways

Parameters:

  • timeout: (Numeric) (defaults to: nil)

    When specified, flush will wait timeout: seconds before throwing Timeout::Error

Raises:

  • (TimeoutError)

    if timeout: was exceeded while waiting for send queue to flush



134
135
136
# File 'lib/lifx/client.rb', line 134

def flush(timeout: nil)
  context.flush(timeout: timeout)
end

#lightsLightCollection

Returns Lights available to the client

Returns:

See Also:

  • LIFX::Client.[NetworkContext[NetworkContext#lights]


106
107
108
# File 'lib/lifx/client.rb', line 106

def lights
  context.lights
end

#purge_unused_tags!Array<String>

Purges unused tags from the system. Should only use when all devices are on the network, otherwise offline devices using their tags will not be tagged correctly.

Returns:

  • (Array<String>)

    Tags that were purged



126
127
128
# File 'lib/lifx/client.rb', line 126

def purge_unused_tags!
  context.purge_unused_tags!
end

#refreshvoid

This method returns an undefined value.

Sends a request to refresh devices and tags.



70
71
72
# File 'lib/lifx/client.rb', line 70

def refresh
  @context.refresh
end

#stopObject

Stops everything and cleans up.



139
140
141
# File 'lib/lifx/client.rb', line 139

def stop
  context.stop
end

#sync(**kwargs) { ... } ⇒ Float

Note:

This method is in alpha and might go away. Use tags for better group messaging.

This method takes a block consisting of multiple asynchronous color or power changing targets and it will try to schedule them so they run at the same time.

You cannot nest sync calls, nor call synchronous methods inside a sync block.

Due to messaging rate constraints, the amount of messages determine the delay before the commands are executed. This method also assumes all the lights have the same time.

Examples:

This example sets all the lights to a random colour at the same time.

client.sync do
  client.lights.each do |light|
    light.set_color(rand(4) * 90, 1, 1)
  end
end

Yields:

  • Block of commands to synchronize

Returns:

  • (Float)

    Number of seconds until commands are executed



91
92
93
# File 'lib/lifx/client.rb', line 91

def sync(**kwargs, &block)
  @context.sync(**kwargs, &block)
end

#sync!(&block) ⇒ Float

This is the same as #sync, except it will block until the commands have been executed.

Returns:

  • (Float)

    Number of seconds slept

See Also:



98
99
100
101
102
# File 'lib/lifx/client.rb', line 98

def sync!(&block)
  sync(&block).tap do |delay|
    sleep(delay)
  end
end

#tagsArray<String>

Returns All tags visible to the client

Returns:

  • (Array<String>)

    All tags visible to the client

See Also:

  • LIFX::Client.[NetworkContext[NetworkContext#tags]


112
113
114
# File 'lib/lifx/client.rb', line 112

def tags
  context.tags
end

#unused_tagsArray<String>

Returns Tags that are currently unused by known devices

Returns:

  • (Array<String>)

    Tags that are currently unused by known devices

See Also:

  • LIFX::Client.[NetworkContext[NetworkContext#unused_tags]


118
119
120
# File 'lib/lifx/client.rb', line 118

def unused_tags
  context.unused_tags
end