Class: LIFX::Client

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
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

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



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

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

Instance Attribute Details

#context ⇒ NetworkContext (readonly)

Refers to the client's network context.

Returns:



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

def context
  @context
end

Class Method Details

.lan ⇒ Client

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

#discover ⇒ Client

This method tells the NetworkContext to look for devices asynchronously.

Returns:



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

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:



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

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



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

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

#lights ⇒ LightCollection

Returns Lights available to the client.

Returns:

See Also:

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


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

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



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

def purge_unused_tags!
  context.purge_unused_tags!
end

#refresh ⇒ void

This method returns an undefined value.

Sends a request to refresh devices and tags.



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

def refresh
  @context.refresh
end

#stop ⇒ Object

Stops everything and cleans up.



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

def stop
  context.stop
end

#sync { ... } ⇒ 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



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

def sync(&block)
  @context.sync(&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:



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

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

#tags ⇒ Array<String>

Returns All tags visible to the client.

Returns:

  • (Array<String>) —

    All tags visible to the client

See Also:

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


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

def tags
  context.tags
end

#unused_tags ⇒ Array<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]


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

def unused_tags
  context.unused_tags
end