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 



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.



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



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.



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 }

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.

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

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.

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.



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



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.

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.

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.

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