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: :lan) ⇒ Client

Returns a new instance of Client.

Parameters:

  • transport: (:lan) (defaults to: :lan) —

    Specify which transport to use



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

def initialize(transport: :lan)
  @context = NetworkContext.new(transport: transport)
end

Instance Attribute Details

#context ⇒ NetworkContext (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

.lan ⇒ Client

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

Returns:

  • (Client) —

    A LAN LIFX::Client



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

def lan
  @lan ||= new
end

Instance Method Details

#discover ⇒ Client

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

  • (Timeout::Error) —

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



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

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]


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

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



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

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.



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

def refresh
  @context.refresh
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



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

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:



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

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]


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

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]


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

def unused_tags
  context.unused_tags
end