lifx-lan 0.1.0

data/lib/lifx-lan.rb

@@ -0,0 +1,27 @@
+require "lifx/lan/version"
+require "bindata"
+require "bindata_ext/bool"
+require "bindata_ext/record"
+
+require "lifx/lan/required_keyword_arguments"
+require "lifx/lan/utilities"
+require "lifx/lan/logging"
+
+require "lifx/lan/thread"
+
+require "lifx/lan/protocol/payload"
+%w(device light sensor wan wifi message).each { |f| require "lifx/lan/protocol/#{f}" }
+require "lifx/lan/protocol/type"
+require "lifx/lan/message"
+require "lifx/lan/transport"
+
+require "lifx/lan/config"
+require "lifx/lan/client"
+
+module LIFX
+  module LAN
+    NULL_SITE_ID = "000000000000"
+
+    class TimeoutError < StandardError; end
+  end
+end

data/lib/lifx/lan/client.rb

@@ -0,0 +1,149 @@
+require 'socket'
+require 'timeout'
+
+require 'lifx/lan/network_context'
+require 'lifx/lan/light_collection'
+
+module LIFX
+  module LAN
+    # {LIFX::LAN::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(transport_manager: TransportManager::LAN.new)
+        end
+      end
+
+      extend Forwardable
+      include Utilities
+      include RequiredKeywordArguments
+
+      # Refers to the client's network context.
+      # @return [NetworkContext] Enclosed network context
+      attr_reader :context
+
+      # @param transport_manager: [TransportManager] Specify the {TransportManager}
+      def initialize(transport_manager: required!('transport_manager'))
+        @context = NetworkContext.new(transport_manager: transport_manager)
+      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
+
+      def stop_discovery
+        @context.stop_discovery
+      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,
+          action_interval: 1 do
+          discover
+          refresh
+        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(**kwargs, &block)
+        @context.sync(**kwargs, &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 [TimeoutError] if `timeout:` was exceeded while waiting for send queue to flush
+      # @return [void]
+      def flush(timeout: nil)
+        context.flush(timeout: timeout)
+      end
+
+      # Stops everything and cleans up.
+      def stop
+        context.stop
+      end
+    end
+  end
+end

data/lib/lifx/lan/color.rb

@@ -0,0 +1,199 @@
+module LIFX
+  module LAN
+    module Colors
+      DEFAULT_KELVIN = 3500
+
+      {
+        red: 0,
+        orange: 36,
+        yellow: 60,
+        green: 120,
+        cyan: 195,
+        blue: 250,
+        purple: 280,
+        pink: 325
+      }.each do |color, hue|
+        define_method(color) do |saturation: 1.0, brightness: 1.0, kelvin: DEFAULT_KELVIN|
+          Color.new(hue, saturation, brightness, kelvin)
+        end
+      end
+
+      # Helper to create a white {Color}
+      # @param brightness: [Float] Valid range: `0..1`
+      # @param kelvin: [Integer] Valid range: `2500..9000`
+      # @return [Color]
+      def white(brightness: 1.0, kelvin: DEFAULT_KELVIN)
+        Color.new(0, 0, brightness, kelvin)
+      end
+
+      # Helper to create a random {Color}
+      def random_color(hue: rand(360), saturation: rand, brightness: rand, kelvin: DEFAULT_KELVIN)
+        Color.new(hue, saturation, brightness, kelvin)
+      end
+    end
+
+    # LIFX::Color represents a color intervally by HSBK (Hue, Saturation, Brightness/Value, Kelvin).
+    # It has methods to construct a LIFX::Color instance from various color representations.
+    class Color < Struct.new(:hue, :saturation, :brightness, :kelvin)
+      extend Colors
+      UINT16_MAX = 65535
+      KELVIN_MIN = 2500
+      KELVIN_MAX = 9000
+
+      class << self
+        # Helper method to create from HSB/HSV
+        # @param hue [Float] Valid range: `0..360`
+        # @param saturation [Float] Valid range: `0..1`
+        # @param brightness [Float] Valid range: `0..1`
+        # @return [Color]
+        def hsb(hue, saturation, brightness)
+          new(hue, saturation, brightness, DEFAULT_KELVIN)
+        end
+        alias_method :hsv, :hsb
+
+        # Helper method to create from HSBK/HSVK
+        # @param hue [Float] Valid range: `0..360`
+        # @param saturation [Float] Valid range: `0..1`
+        # @param brightness [Float] Valid range: `0..1`
+        # @param kelvin [Integer] Valid range: `2500..9000`
+        # @return [Color]
+        def hsbk(hue, saturation, brightness, kelvin)
+          new(hue, saturation, brightness, kelvin)
+        end
+
+        # Helper method to create from HSL
+        # @param hue [Float] Valid range: `0..360`
+        # @param saturation [Float] Valid range: `0..1`
+        # @param luminance [Float] Valid range: `0..1`
+        # @return [Color]
+        def hsl(hue, saturation, luminance)
+          # From: http://ariya.blogspot.com.au/2008/07/converting-between-hsl-and-hsv.html
+          l = luminance * 2
+          saturation *= (l <= 1) ? l : 2 - l
+          brightness = (l + saturation) / 2
+          saturation = (2 * saturation) / (l + saturation)
+          new(hue, saturation, brightness, DEFAULT_KELVIN)
+        end
+
+        # Helper method to create from RGB.
+        # @note RGB is not the recommended way to create colors
+        # @param r [Integer] Red. Valid range: `0..255`
+        # @param g [Integer] Green. Valid range: `0..255`
+        # @param b [Integer] Blue. Valid range: `0..255`
+        # @return [Color]
+        def rgb(r, g, b)
+          r = r / 255.0
+          g = g / 255.0
+          b = b / 255.0
+
+          max = [r, g, b].max
+          min = [r, g, b].min
+
+          h = s = v = max
+          d = max - min
+          s = max.zero? ? 0 : d / max
+
+          if max == min
+            h = 0
+          else
+            case max
+            when r
+              h = (g - b) / d + (g < b ? 6 : 0)
+            when g
+              h = (b - r) / d + 2
+            when b
+              h = (r - g) / d + 4
+            end
+            h = h * 60
+          end
+
+          new(h, s, v, DEFAULT_KELVIN)
+        end
+
+        # Creates an instance from a {Protocol::Light::Hsbk} struct
+        # @api private
+        # @param hsbk [Protocol::Light::Hsbk]
+        # @return [Color]
+        def from_struct(hsbk)
+          new(
+            (hsbk.hue.to_f / UINT16_MAX) * 360,
+            (hsbk.saturation.to_f / UINT16_MAX),
+            (hsbk.brightness.to_f / UINT16_MAX),
+            hsbk.kelvin
+          )
+        end
+      end
+
+      def initialize(hue, saturation, brightness, kelvin)
+        hue = hue % 360
+        super(hue, saturation, brightness, kelvin)
+      end
+
+      # Returns a new Color with the hue changed while keeping other attributes
+      # @param hue [Float] Hue in degrees. `0..360`
+      # @return [Color]
+      def with_hue(hue)
+        Color.new(hue, saturation, brightness, kelvin)
+      end
+
+      # Returns a new Color with the saturaiton changed while keeping other attributes
+      # @param saturaiton [Float] Saturation as float. `0..1`
+      # @return [Color]
+      def with_saturation(saturation)
+        Color.new(hue, saturation, brightness, kelvin)
+      end
+
+      # Returns a new Color with the brightness changed while keeping other attributes
+      # @param brightness [Float] Brightness as float. `0..1`
+      # @return [Color]
+      def with_brightness(brightness)
+        Color.new(hue, saturation, brightness, kelvin)
+      end
+
+      # Returns a new Color with the kelvin changed while keeping other attributes
+      # @param kelvin [Integer] Kelvin. `2500..9000`
+      # @return [Color]
+      def with_kelvin(kelvin)
+        Color.new(hue, saturation, brightness, kelvin)
+      end
+
+      # Returns a struct for use by the protocol
+      # @api private
+      # @return [Protocol::Light::Hsbk]
+      def to_hsbk
+        Protocol::Light::Hsbk.new(
+          hue: (hue / 360.0 * UINT16_MAX).to_i,
+          saturation: (saturation * UINT16_MAX).to_i,
+          brightness: (brightness * UINT16_MAX).to_i,
+          kelvin: [KELVIN_MIN, kelvin.to_i, KELVIN_MAX].sort[1]
+        )
+      end
+
+      # Returns hue, saturation, brightness and kelvin in an array
+      # @return [Array<Float, Float, Float, Integer>]
+      def to_a
+        [hue, saturation, brightness, kelvin]
+      end
+
+      DEFAULT_SIMILAR_THRESHOLD = 0.001 # 0.1% variance
+      # Checks if colours are equal to 0.1% variance
+      # @param other [Color] Color to compare to
+      # @param threshold: [Float] 0..1. Threshold to consider it similar
+      # @return [Boolean]
+      def similar_to?(other, threshold: DEFAULT_SIMILAR_THRESHOLD)
+        return false unless other.is_a?(Color)
+        conditions = []
+
+        conditions << (((hue - other.hue).abs < (threshold * 360)) || begin
+          # FIXME: Surely there's a better way.
+          hues = [hue, other.hue].sort
+          hues[0] += 360
+          (hues[0] - hues[1]).abs < (threshold * 360)
+        end)
+        conditions << ((saturation - other.saturation).abs < threshold)
+        conditions << ((brightness - other.brightness).abs < threshold)
+        conditions.all?
+      end
+    end
+  end
+end

data/lib/lifx/lan/config.rb

@@ -0,0 +1,17 @@
+require 'configatron/core'
+require 'logger'
+module LIFX
+  module LAN
+    Config = Configatron::Store.new
+
+    Config.default_duration = 1
+    Config.message_wait_timeout = 3
+    Config.message_retry_interval = 0.5
+    Config.broadcast_ip = '255.255.255.255'
+    Config.allowed_transports = [:udp, :tcp]
+    Config.log_invalid_messages = true
+    Config.logger = Logger.new(STDERR).tap do |logger|
+      logger.level = Logger::WARN
+    end
+  end
+end

data/lib/lifx/lan/firmware.rb

@@ -0,0 +1,60 @@
+require 'time'
+
+module LIFX
+  module LAN
+    # LIFX::LAN::Firmware handles decoding firmware payloads
+    # @private
+    class Firmware < Struct.new(:build_time, :major, :minor)
+      include Comparable
+
+      def initialize(payload)
+        self.build_time = decode_time(payload.build)
+        self.major  = (payload.version >> 0x10)
+        self.minor  = (payload.version &  0xFF)
+      end
+
+      def to_s
+        "#<Firmware version=#{self.major}.#{self.minor}>"
+      end
+      alias_method :inspect, :to_s
+
+      def <=>(obj)
+        case obj
+        when String
+          major, minor = obj.split('.', 2).map(&:to_i)
+          [self.major, self.minor] <=> [major, minor]
+        when Firmware
+          [self.major, self.minor] <=> [obj.major, obj.minor]
+        else
+          nil
+        end
+      end
+
+
+      protected
+
+      def decode_time(int)
+        if int < 1300000000000000000
+          year   = byte(int, 56) + 2000
+          month  = bytes(int, 48, 40, 32).map(&:chr).join
+          day    = byte(int, 24)
+          hour   = byte(int, 16)
+          min    = byte(int,  8)
+          sec    = byte(int,  0)
+          # Don't want to pull in DateTime just for DateTime.new
+          Time.parse("%s %d %04d, %02d:%02d:%02d" % [month, day, year, hour, min, sec])
+        else
+          Time.at(int / 1000000000)
+        end
+      end
+
+      def byte(n, pos)
+        0xFF & (n >> pos)
+      end
+
+      def bytes(n, *range)
+        range.map {|r| byte(n, r)}
+      end
+    end
+  end
+end