Class: LIFX::LAN::Client

Inherits:
Object
  • Object
show all
Extended by:
Forwardable
Includes:
RequiredKeywordArguments
Defined in:
lib/lifx/lan/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



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

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:



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

def context
  @context
end

Class Method Details

.lan ⇒ Client

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

Returns:

  • (Client) —

    A LAN LIFX::Client



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

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:



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

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:



60
61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/lifx/lan/client.rb', line 60

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



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

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

#lights ⇒ LightCollection

Returns Lights available to the client.

Returns:

See Also:

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


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

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



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

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.



75
76
77
 
# File 'lib/lifx/lan/client.rb', line 75

def refresh
  @context.refresh
end

#stop ⇒ Object

Stops everything and cleans up.



144
145
146
 
# File 'lib/lifx/lan/client.rb', line 144

def stop
  context.stop
end

#stop_discovery ⇒ Object 



44
45
46
 
# File 'lib/lifx/lan/client.rb', line 44

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



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

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:



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

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::LAN::Client.[NetworkContext[NetworkContext#tags]


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

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::LAN::Client.[NetworkContext[NetworkContext#unused_tags]


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

def unused_tags
  context.unused_tags
end