lifx 0.0.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9cdb2d3a2365da0d3411c5fcea5763a749ea723e
-  data.tar.gz: 7bb97947fe58342b0355bd67775016d05ac7635f
+  metadata.gz: 357ce53a9c5e511833c6917f09d72396d203df38
+  data.tar.gz: 135ecdc739e64aaf4615702eedb273f9c3cb570e
 SHA512:
-  metadata.gz: ad5318cf0898bc5d07e6bc0e8a5818c2fff94f2dd3485e5d47d12f5e1d3aaa14966eb20436b0a56d17b1cd7a9a3fa61e7699f8ab1a196abf3cafb32437e42faf
-  data.tar.gz: 67edd75288e6fb22a5fc614473bf4c8b912e51c06874c8eaffe09170fbda73439a9220aa0d398d2d5cbd92dc02ed697dff63ac3e812097f3601d7f5828fd5dcc
+  metadata.gz: 7d2ad759de8697cf02de2914782742315be5c545678bae5b848e9dfeb13acc945823b78a1145f82df308e2dec308c31ec01aae6601c67262632cf64f36f56867
+  data.tar.gz: 212a318bab27a3f967971364e8384daa82842334a3b8f9327de66c12e3e01309b9b2d015f9c650dea8e0e91ea1cbf63a7ed3b2e722fc47186889b21f908506a4

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown

data/Gemfile

@@ -1,4 +1,14 @@
 source 'https://rubygems.org'
 
+group :development do
+  gem 'redcarpet'
+  gem 'erubis'
+  gem 'ruby-prof'
+  gem 'pry-byebug'
+  gem 'pry-rescue'
+  gem 'pry-stack_explorer'
+  gem 'yard'
+end
+
 # Specify your gem's dependencies in lifx.gemspec
 gemspec

data/LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2013 LIFX Labs
+Copyright (c) 2014 LIFX Labs
 
 MIT License
 

data/README.md

@@ -1,29 +1,87 @@
 # LIFX
 
-A gem for LIFX bulbs.
+This gem allows you to control your [LIFX](http://lifx.co) lights.
+
+It handles discovery, gateway connections, tags, and provides a object-based API
+for talking to Lights.
+
+Due to the nature of the current protocol, some methods are asynchronous.
+
+This gem is in an early beta state. Expect breaking API changes.
+
+## Requirements
+
+* Ruby 2.1.1
+* Bundler
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'lifx'
+```ruby
+gem 'lifx', git: "git@github.com:LIFX/lifx-gem.git"
+```
 
 And then execute:
 
-    $ bundle
+```shell
+$ bundle
+```
+
+## Usage
 
-Or install it yourself as:
+```ruby
+client = LIFX::Client.lan                  # Talk to bulbs on the LAN
+client.discover! do |c|                    # Discover lights. Blocks until a light with the label 'Office' is found
+  c.lights.with_label('Office')
+end
+                                           # Blocks for a default of 10 seconds or until a light is found
+client.lights.turn_on                      # Tell all lights to turn on
+light = client.lights.with_label('Office') # Get light with label 'Office'
 
-    $ gem install lifx
+# Set the Office light to pale green over 5 seconds
+green = LIFX::Color.green(saturation: 0.5)
+light.set_color(green, duration: 5)        # Light#set_color is asynchronous
 
-## Usage
+sleep 5                                    # Wait for light to finish changing
+light.set_label('My Office')
+
+light.add_tag('Offices')                   # Add tag to light
+
+client.lights.with_tag('Offices').turn_off
+
+client.flush                               # Wait until all the packets have been sent
+```
+
+## Documentation
+
+Documentation is available at http://rubydoc.info/gems/lifx. Please note that undocumented classes/methods and classes/methods marked private are not intended for public use.
+
+## Examples
+
+Examples are located in the `examples/` folder.
+
+* [travis-build-light](examples/travis-build-light/build-light.rb): Changes the colour of a light based on the build status of a project on Travis.
+* [auto-off](examples/auto-off/auto-off.rb): Turns a light off after X seconds of it being detected turned on.
+* [identify](examples/identify/identify.rb): Use divide-and-conquer search algorithm to identify a light visually.
+
+## Useful utilities
+
+* [lifx-console](http://github.com/chendo/lifx-console): A Pry-enabled REPL to play with LIFX easily.
+* [lifx-http](http://github.com/chendo/lifx-http): A HTTP API for LIFX.
+
+## Testing
+
+Run with `bundle exec rspec`.
+
+The integration specs rely on a least one device tagged with `Test` to function. At this point, they can fail occasionally due to the async nature of the protocol, and there's not much coverage at the moment as the architecture is still in flux.
+
+A more comprehensive test suite is in the works.
+
+## Feedback
 
-TODO: Write usage instructions here
+Please file an issue for general feedback, bugs, clarification, examples, etc etc. Feel free to hit me up on Twitter, too: [@chendo](https://twitter.com/chendo).
 
-## Contributing
+## License
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+MIT. See `LICENSE.txt`

data/Rakefile

@@ -1 +1,13 @@
 require "bundler/gem_tasks"
+
+task :console do
+  require "lifx"
+  require "pry"
+  if ENV['DEBUG']
+    LIFX::Config.logger = Yell.new(STDERR)
+  end
+  LIFX::Client.lan.discover! do |c|
+    c.lights.count > 0
+  end
+  LIFX::Client.lan.pry
+end

data/bin/lifx-console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# LIFX Console
+$LOAD_PATH << File.join(File.dirname(__FILE__), "..", "lib")
+require 'lifx'
+require 'rubygems'
+begin
+  require 'pry'
+rescue LoadError
+  $stderr.puts("You must have pry installed to use lifx-console. gem install pry")
+end
+
+c = LIFX::Client.lan
+c.discover!
+c.extend(LIFX::Colors)
+c.pry

data/bin/lifx-snoop

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+# lifx-snoop is a utility that snoops on LIFX UDP traffic on both the broadcast port
+# and the peer broadcast port.
+#
+# Usage:
+#   lifx-snoop [regexp, ...]
+#
+# By default, it will show all messages. Any arguments passed in will become
+# regular expressions, which will then match on the string representation of the
+# message.
+#
+# Example:
+#   lifx-snoop Light::Get                      # Shows only Light::Get messages
+#   lifx-snoop Light::State site=d073d5000000  # Shows only Light::State messages matching site d073d5000000
+
+$LOAD_PATH << File.join(File.dirname(__FILE__), "..", "lib")
+require 'lifx'
+require 'time'
+
+matchers = ARGV.map do |arg|
+  Regexp.new(arg, Regexp::IGNORECASE)
+end
+
+if matchers.empty?
+  matchers << //
+end
+
+begin
+  light_udp = LIFX::Transport::UDP.new('0.0.0.0', 56700)
+  light_udp.add_observer(self) do |message:, ip:, transport:|
+    if matchers.all? { |m| message.to_s =~ m }
+      puts "#{Time.now.iso8601(5)} BROADCAST: #{ip} #{message}"
+    end
+  end
+  light_udp.listen
+
+  peer_udp = LIFX::Transport::UDP.new('0.0.0.0', 56750)
+  peer_udp.add_observer(self) do |message:, ip:, transport:|
+    if matchers.all? { |m| message.to_s =~ m }
+      puts "#{Time.now.iso8601(5)} PEER:      #{ip} #{message}"
+    end
+  end
+  peer_udp.listen
+rescue LIFX::Message::UnsupportedProtocolVersion
+end
+
+puts "Listening on 56700 and 56750..."
+puts "^C to quit."
+
+sleep

data/examples/auto-off/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem 'lifx', path: '../../'

data/examples/auto-off/auto-off.rb

@@ -0,0 +1,35 @@
+# Auto-off script
+# 
+# This script will turn a light off after 10 seconds when it has detected it has turned on.
+# To run: bundle; bundle ruby auto-off.rb [light label]
+
+require 'bundler'
+Bundler.require
+
+AUTO_OFF_DELAY = 10
+
+label = ARGV.first
+lifx = LIFX::Client.lan
+lifx.discover! do
+  label ? lifx.lights.with_label(label) : lifx.lights.first
+end
+
+light = label ? lifx.lights.with_label(label) : lifx.lights.first
+
+puts "#{light} will be automatically turned off after #{AUTO_OFF_DELAY} seconds"
+
+thr = Thread.new do
+  loop do
+    if light.on? && !(@off_thr && @off_thr.alive?)
+      puts "Light detected on. Turning off in #{AUTO_OFF_DELAY}"
+      @off_thr = Thread.new do
+        sleep AUTO_OFF_DELAY
+        light.turn_off
+        puts "Turning off"
+      end
+    end
+    sleep 1
+  end
+end
+
+thr.join

data/examples/identify/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem 'lifx', path: '../../'

data/examples/identify/identify.rb

@@ -0,0 +1,70 @@
+# Identify
+#
+# This example uses a divide and conquer search algorithm to identify a light visually.
+# It will set all lights to white, then partition them by colour.
+# On each iteration, it will ask you what colour the bulb you're trying to identify is showing
+# until it narrows it down to a single bulb.
+# Please note it does not restore the light state before identification.
+
+require 'bundler'
+Bundler.require
+
+COLOURS = {
+  'red' => [0, 1, 1],
+  'yellow' => [50, 1, 1],
+  'green' => [120, 1, 1],
+  'blue' => [220, 1, 1]
+}
+
+LIFX::Config.logger = Yell.new(STDERR, :level => :error)
+c = LIFX::Client.lan
+c.discover
+5.times do
+  c.lights.refresh
+  c.flush
+  sleep 1
+  puts "Lights found: #{c.lights.count}"
+end
+
+
+def partition(list, partitions)
+  [].tap do |array|
+    list.each_slice((list.count / partitions.to_f).ceil) do |chunk|
+      array << chunk
+    end
+  end
+end
+
+lights = c.lights.to_a
+mapping = {}
+
+while lights.count > 1
+  puts "Searching through #{lights.count} lights..."
+  c.lights.set_color(LIFX::Color.white)
+  partitions = partition(lights, COLOURS.values.count)
+  COLOURS.keys.each_with_index do |color_name, index|
+    color = LIFX::Color.hsb(*COLOURS[color_name])
+    mapping[color_name] = partitions[index]
+    next if partitions[index].nil?
+    partitions[index].each do |l|
+      l.set_color(color, duration: 0)
+    end
+  end
+  puts "Waiting for flush."
+  c.flush
+  puts "What colour is the bulb you're trying to identify? (#{COLOURS.keys.join(', ')})"
+  resp = gets.strip
+  if mapping.has_key?(resp)
+    lights = mapping[resp]
+  else
+    puts "Colour not found. Iterating again"
+  end
+end
+
+if lights.count == 1
+  puts "Light identified: #{lights.first}"
+else
+  puts "No bulbs found."
+end
+
+c.flush

data/examples/travis-build-light/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem 'lifx', path: '../../'
+gem 'travis'

data/examples/travis-build-light/build-light.rb

@@ -0,0 +1,57 @@
+# A Travis CI Build Light
+#
+# To run: bundle; bundle ruby build-light.rb [user/repo]
+# Please note this doesn't have error handling yet.
+
+require 'bundler'
+Bundler.require
+
+lifx = LIFX::Client.lan
+lifx.discover!
+sleep 2 # Wait for tag data to come back
+
+light = if lifx.tags.include?('Build Light')
+  lights = lifx.lights.with_tag('Build Light')
+  if lights.empty?
+    puts "No lights in the Build Light tag, using the first light found."
+    lifx.lights.first
+  else
+    lights
+  end
+else
+  lifx.lights.first
+end
+
+if !light
+  puts "No LIFX lights found."
+  exit 1
+end
+
+puts "Using light(s): #{light}"
+repo_path = ARGV.first || 'rails/rails'
+
+repo = Travis::Repository.find(repo_path)
+puts "Watching repository #{repo.slug}"
+
+def update_light(light, repository)
+  color = case repository.color
+  when 'green'
+    LIFX::Color.hsb(120, 1, 1)  
+  when 'yellow'
+    LIFX::Color.hsb(60, 1, 1)  
+  when 'red'
+    LIFX::Color.hsb(0, 1, 1)
+  end
+
+  light.turn_on!
+  light.set_color(color, duration: 0.2)
+  puts "#{Time.now}: Build ##{repository.last_build.number} is #{repository.color}."
+end
+
+update_light(light, repo)
+
+Travis.listen(repo) do |stream|
+  stream.on('build:started', 'build:finished') do |event|
+    update_light(light, event.repository)
+  end
+end

data/lib/bindata_ext/bool.rb

@@ -0,0 +1,29 @@
+module BinData
+  class Bool < Primitive
+    uint8 :_value
+
+    def get
+      (self._value || 0) > 0
+    end
+
+    def set(value)
+      self._value = value ? 1 : 0
+    end
+  end
+
+  class BoolBit1 < Primitive
+    bit1le :_value
+
+    def get
+      (self._value || 0) > 0
+    end
+
+    def set(value)
+      self._value = value ? 1 : 0
+    end
+
+    def !
+      !get
+    end
+  end
+end

data/lib/bindata_ext/record.rb

@@ -0,0 +1,11 @@
+require 'stringio'
+BinData::Record
+module BinData
+  class Record
+    def pack
+      s = StringIO.new
+      write(s)
+      s.string.b
+    end
+  end
+end

data/lib/lifx/client.rb

@@ -0,0 +1,136 @@
+require 'socket'
+require 'timeout'
+require 'yell'
+
+require 'lifx/network_context'
+require 'lifx/light_collection'
+
+module LIFX
+  # {LIFX::Client} is the top level interface to the library. It mainly maps
+  # methods to the backing {NetworkContext} instance.
+  class Client
+
+    class << self
+      # Returns a {Client} set up for accessing devices on the LAN
+      #
+      # @return [Client] A LAN LIFX::Client
+      def lan
+        @lan ||= new
+      end
+    end
+
+    extend Forwardable
+    include Utilities
+
+    # Refers to the client's network context.
+    # @return [NetworkContext] Enclosed network context
+    attr_reader :context
+
+    # @param transport: [:lan] Specify which transport to use
+    def initialize(transport: :lan)
+      @context = NetworkContext.new(transport: transport)
+    end
+
+    # Default timeout in seconds for discovery
+    DISCOVERY_DEFAULT_TIMEOUT = 10
+
+    # This method tells the {NetworkContext} to look for devices asynchronously.
+    # @return [Client] self
+    def discover
+      @context.discover
+    end
+
+    class DiscoveryTimeout < Timeout::Error; end
+    # This method tells the {NetworkContext} to look for devices, and will block
+    # until there's at least one device.
+    #
+    # @example Wait until at least three lights have been found
+    #   client.discover! { |c| c.lights.count >= 3 }
+    # 
+    # @param timeout: [Numeric] How long to try to wait for before returning
+    # @param condition_interval: [Numeric] Seconds between evaluating the block
+    # @yield [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.
+    # @raise [DiscoveryTimeout] If discovery times out
+    # @return [Client] self
+    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
+
+    # Sends a request to refresh devices and tags.
+    # @return [void]
+    def refresh
+      @context.refresh
+    end
+
+    # 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.
+    # @example 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
+    #
+    # @note This method is in alpha and might go away. Use tags for better group messaging.
+    # @yield Block of commands to synchronize
+    # @return [Float] Number of seconds until commands are executed
+    def sync(&block)
+      @context.sync(&block)
+    end
+
+    # This is the same as {#sync}, except it will block until the commands have been executed.
+    # @see #sync
+    # @return [Float] Number of seconds slept
+    def sync!(&block)
+      sync(&block).tap do |delay|
+        sleep(delay)
+      end
+    end
+
+    # @return [LightCollection] Lights available to the client
+    # @see [NetworkContext#lights]
+    def lights
+      context.lights
+    end
+
+    # @return [Array<String>] All tags visible to the client
+    # @see [NetworkContext#tags]
+    def tags
+      context.tags
+    end
+
+    # @return [Array<String>] Tags that are currently unused by known devices
+    # @see [NetworkContext#unused_tags]
+    def unused_tags
+      context.unused_tags
+    end
+
+    # 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.
+    # @return [Array<String>] Tags that were purged
+    def purge_unused_tags!
+      context.purge_unused_tags!
+    end
+
+    # Blocks until all messages have been sent to the gateways
+    # @param timeout: [Numeric] When specified, flush will wait `timeout:` seconds before throwing `Timeout::Error`
+    # @raise [Timeout::Error] if `timeout:` was exceeded while waiting for send queue to flush
+    # @return [void]
+    def flush(timeout: nil)
+      context.flush(timeout: timeout)
+    end
+  end
+end