lifx 0.0.1 → 0.4.0

data/lib/lifx/light.rb

@@ -0,0 +1,406 @@
+require 'lifx/seen'
+require 'lifx/color'
+require 'lifx/target'
+require 'lifx/light_target'
+require 'lifx/firmware'
+
+module LIFX
+  # LIFX::Light represents a Light device
+  class Light
+    include Seen
+    include LightTarget
+    include Logging
+    include Utilities
+
+    # @return [NetworkContext] NetworkContext the Light belongs to
+    attr_reader :context
+
+    # @return [String] Device ID
+    attr_reader :id
+
+    # @param context: [NetworkContext] {NetworkContext} the Light belongs to
+    # @param id: [String] Device ID of the Light
+    # @param site_id: [String] Site ID of the Light. Avoid using when possible.
+    # @param label: [String] Label of Light to prepopulate
+    def initialize(context:, id:, site_id: nil, label: nil)
+      @context = context
+      @id = id
+      @site_id = site_id
+      @label = label
+      @power = nil
+      @message_hooks = Hash.new { |h, k| h[k] = [] }
+      @context.register_device(self)
+      @message_signal = ConditionVariable.new
+
+      add_hooks
+    end
+
+    # Handles updating the internal state of the Light from incoming
+    # protocol messages.
+    # @api private
+    def handle_message(message, ip, transport)
+      payload = message.payload
+
+      @message_hooks[payload.class].each do |hook|
+        hook.call(payload)
+      end
+      @message_signal.broadcast
+      seen!
+    end
+
+    # Adds a block to be run when a payload of class `payload_class` is received
+    # @param payload_class [Class] Payload type to execute block on
+    # @param &hook [Proc] Hook to run
+    # @return [void]
+    def add_hook(payload_class, hook_arg = nil, &hook_block)
+      hook = block_given? ? hook_block : hook_arg
+      if !hook || !hook.is_a?(Proc)
+        raise "MUst pass a proc either as an argument or a block"
+      end
+      @message_hooks[payload_class] << hook
+    end
+
+    # Removes a hook added by {#add_hook}
+    # @param payload_class [Class] Payload type to delete hook from
+    # @param hook [Proc] The original hook passed into {#add_hook}
+    # @return [void]
+    def remove_hook(payload_class, hook)
+      @message_hooks[payload_class].delete(hook)
+    end
+
+    # Returns the color of the device.
+    # @param refresh: [Boolean] If true, will request for current color
+    # @param fetch: [Boolean] If false, it will not request current color if it's not cached
+    # @return [Color] Color
+    def color(refresh: false, fetch: true)
+      @color = nil if refresh
+      send_message!(Protocol::Light::Get.new, wait_for: Protocol::Light::Get) if fetch && !@color
+      @color
+    end
+
+    # Returns the label of the light
+    # @param refresh: [Boolean] If true, will request for current label
+    # @param fetch: [Boolean] If false, it will not request current label if it's not cached
+    # @return [String] Label
+    def label(refresh: false, fetch: true)
+      @label = nil if refresh
+      send_message!(Protocol::Light::Get.new, wait_for: Protocol::Light::Get) if fetch && !@label
+      @label
+    end
+
+    MAX_LABEL_LENGTH = 32
+    class LabelTooLong < ArgumentError; end
+
+    # Sets the label of the light
+    # @param label [String] Desired label
+    # @raise [LabelTooLong] if label is greater than {MAX_LABEL_LENGTH}
+    # @return [Light] self
+    def set_label(label)
+      if label.length > MAX_LABEL_LENGTH
+        raise LabelTooLong.new("Label length must be below or equal to #{MAX_LABEL_LENGTH}")
+      end
+      while self.label != label
+        send_message!(Protocol::Device::SetLabel.new(label: label), wait_for: Protocol::Device::StateLabel)
+      end
+      self
+    end
+
+    # Set the power state to `level` synchronously.
+    # This method cannot guarantee the message was received.
+    # @param level [0, 1] 0 for off, 1 for on
+    # @return [Light, LightCollection] self for chaining
+    def set_power!(level)
+      send_message!(Protocol::Device::SetPower.new(level: level), wait_for: Protocol::Device::StatePower) do |payload|
+        if level.zero?
+          payload.level == 0
+        else
+          payload.level > 0
+        end
+      end
+      self
+    end
+
+    # Turns the light(s) on synchronously
+    # @return [Light, LightCollection] self for chaining
+    def turn_on!
+      set_power!(1)
+    end
+
+    # Turns the light(s) off synchronously
+    # @return [Light, LightCollection]
+    def turn_off!
+      set_power!(0)
+    end
+
+    # @return [Boolean] Returns true if device is on
+    def on?(**kwargs)
+      power(**kwargs) == :on
+    end
+
+    # @return [Boolean] Returns true if device is off
+    def off?(**kwargs)
+      power(**kwargs) == :off
+    end
+
+    # @param refresh: see #label
+    # @param fetch: see #label
+    # @return [:unknown, :off, :on] Light power state
+    def power(refresh: false, fetch: true)
+      @power = nil if refresh
+      send_message!(Protocol::Device::GetPower.new, wait_for: Protocol::Device::StatePower) if !@power && fetch
+      case @power
+      when nil
+        :unknown
+      when 0
+        :off
+      else
+        :on
+      end
+    end
+
+    # Returns the local time of the light
+    # @return [Time]
+    def time
+      send_message!(Protocol::Device::GetTime.new, wait_for: Protocol::Device::StateTime) do |payload|
+        Time.at(payload.time.to_f / NSEC_IN_SEC)
+      end
+    end
+
+    # Returns the difference between the device time and time on the current machine
+    # Positive values means device time is further in the future.
+    # @return [Float]
+    def time_delta
+      device_time = time
+      delta = device_time - Time.now
+    end
+
+    # Pings the device and measures response time.
+    # @return [Float] Latency from sending a message to receiving a response.
+    def latency
+      start = Time.now.to_f
+      send_message!(Protocol::Device::GetTime.new, wait_for: Protocol::Device::StateTime)
+      Time.now.to_f - start
+    end
+
+    # Returns the mesh firmware details
+    # @api private
+    # @return [Hash] firmware details
+    def mesh_firmware(fetch: true)
+      @mesh_firmware ||= begin
+        send_message!(Protocol::Device::GetMeshFirmware.new,
+          wait_for: Protocol::Device::StateMeshFirmware) do |payload|
+          Firmware.new(payload)
+        end if fetch
+      end
+    end
+
+    # Returns the wifi firmware details
+    # @api private
+    # @return [Hash] firmware details
+    def wifi_firmware(fetch: true)
+      @wifi_firmware ||= begin
+        send_message!(Protocol::Device::GetWifiFirmware.new,
+          wait_for: Protocol::Device::StateWifiFirmware) do |payload|
+          Firmware.new(payload)
+        end if fetch
+      end
+    end
+
+    # Returns the temperature of the device
+    # @return [Float] Temperature in Celcius
+    def temperature
+      send_message!(Protocol::Light::GetTemperature.new,
+          wait_for: Protocol::Light::StateTemperature) do |payload|
+        payload.temperature / 100.0
+      end
+    end
+
+    # Returns mesh network info
+    # @api private
+    # @return [Hash] Mesh network info
+    def mesh_info
+      send_message!(Protocol::Device::GetMeshInfo.new,
+          wait_for: Protocol::Device::StateMeshInfo) do |payload|
+        {
+          signal: payload.signal, # This is in Milliwatts
+          tx: payload.tx,
+          rx: payload.rx
+        }
+      end
+    end
+
+    # Returns wifi network info
+    # @api private
+    # @return [Hash] wifi network info
+    def wifi_info
+      send_message!(Protocol::Device::GetWifiInfo.new,
+          wait_for: Protocol::Device::StateWifiInfo) do |payload|
+        {
+          signal: payload.signal, # This is in Milliwatts
+          tx: payload.tx,
+          rx: payload.rx
+        }
+      end
+    end
+
+    # Returns version info
+    # @api private
+    # @return [Hash] version info
+    def version
+      send_message!(Protocol::Device::GetVersion.new,
+         wait_for: Protocol::Device::StateVersion) do |payload|
+        {
+          vendor: payload.vendor,
+          product: payload.product,
+          version: payload.version
+        }
+      end
+    end
+
+    # Return device uptime
+    # @api private
+    # @return [Float] Device uptime in seconds
+    def uptime
+      send_message!(Protocol::Device::GetInfo.new,
+         wait_for: Protocol::Device::StateInfo) do |payload|
+        payload.uptime.to_f / NSEC_IN_SEC
+      end
+    end
+
+    # Return device last downtime
+    # @api private
+    # @return [Float] Device's last downtime in secodns
+    def last_downtime
+      send_message!(Protocol::Device::GetInfo.new,
+         wait_for: Protocol::Device::StateInfo) do |payload|
+        payload.downtime.to_f / NSEC_IN_SEC
+      end
+    end
+
+    # Returns the `site_id` the Light belongs to.
+    # @api private
+    # @return [String]
+    def site_id
+      if @site_id.nil?
+        # FIXME: This is ugly.
+        context.routing_manager.routing_table.site_id_for_device_id(id)
+      else
+        @site_id
+      end
+    end
+
+    # Returns the tags uint64 bitfield for protocol use.
+    # @api private
+    # @return [Integer]
+    def tags_field
+      try_until -> { @tags_field } do
+        send_message(Protocol::Device::GetTags.new)
+      end
+      @tags_field
+    end
+
+    # Add tag to the Light
+    # @param tag [String] The tag to add
+    # @return [Light] self
+    def add_tag(tag)
+      context.add_tag_to_device(tag: tag, device: self)
+      self
+    end
+
+    # Remove tag from the Light
+    # @param tag [String] The tag to remove
+    # @return [Light] self
+    def remove_tag(tag)
+      context.remove_tag_from_device(tag: tag, device: self)
+      self
+    end
+
+    # Returns the tags that are associated with the Light
+    # @return [Array<String>] tags
+    def tags
+      context.tags_for_device(self)
+    end
+    
+    # Returns a nice string representation of the Light
+    def to_s
+      %Q{#<LIFX::Light id=#{id} label=#{label(fetch: false)} power=#{power(fetch: false)}>}.force_encoding(Encoding.default_external)
+    end
+    alias_method :inspect, :to_s
+
+    # Compare current Light to another light
+    # @param other [Light]
+    # @return [-1, 0, 1] Comparison value
+    def <=>(other)
+      raise ArgumentError.new("Comparison of #{self} with #{other} failed") unless other.is_a?(LIFX::Light)
+      [label, id, 0] <=> [other.label, other.id, 0]
+    end
+
+    # Queues a message to be sent the Light
+    # @param payload [Protocol::Payload] the payload to send
+    # @param acknowledge: [Boolean] whether the device should respond
+    # @return [Light] returns self for chaining
+    def send_message(payload, acknowledge: true)
+      context.send_message(target: Target.new(device_id: id, site_id: @site_id), payload: payload, acknowledge: acknowledge)
+      self
+    end
+
+    # Queues a message to be sent to the Light and waits for a response
+    # @param payload [Protocol::Payload] the payload to send
+    # @param wait_for: [Class] the payload class to wait for
+    # @param wait_timeout: [Numeric] wait timeout
+    # @param block: [Proc] the block that is executed when the expected `wait_for` payload comes back. If the return value is false or nil, it will try to send the message again.
+    # @return [Object] the truthy result of `block` is returned.
+    # @raise [Timeout::Error]
+    def send_message!(payload, wait_for:, wait_timeout: 3, timeout_exception: Timeout::Error, &block)
+      if Thread.current[:sync_enabled]
+        raise "Cannot use synchronous methods inside a sync block"
+      end
+
+      result = nil
+      begin
+        block ||= Proc.new { |msg| true }
+        proc = -> (payload) {
+          result = block.call(payload)
+        }
+        add_hook(wait_for, proc)
+        try_until -> { result }, signal: @message_signal, timeout_exception: timeout_exception do
+          send_message(payload)
+        end
+        result
+      ensure
+        remove_hook(wait_for, proc)
+      end
+    end
+
+    protected
+
+    def add_hooks
+      add_hook(Protocol::Device::StateLabel) do |payload|
+        @label = payload.label.to_s
+      end
+
+      add_hook(Protocol::Light::State) do |payload|
+        @label      = payload.label.to_s
+        @color      = Color.from_struct(payload.color.snapshot)
+        @power      = payload.power.to_i
+        @tags_field = payload.tags
+      end
+
+      add_hook(Protocol::Device::StateTags) do |payload|
+        @tags_field = payload.tags
+      end
+
+      add_hook(Protocol::Device::StatePower) do |payload|
+        @power = payload.level.to_i
+      end
+
+      add_hook(Protocol::Device::StateMeshFirmware) do |payload|
+        @mesh_firmware = Firmware.new(payload)
+      end
+
+      add_hook(Protocol::Device::StateWifiFirmware) do |payload|
+        @wifi_firmware = Firmware.new(payload)
+      end
+    end
+  end
+end

data/lib/lifx/light_collection.rb

@@ -0,0 +1,105 @@
+require 'lifx/light_target'
+
+module LIFX
+  # LightCollection represents a collection of {Light}s, which can either refer to
+  # all lights on a {NetworkContext}, or lights
+  class LightCollection
+    include LightTarget
+    include Enumerable
+    extend Forwardable
+
+    class TagNotFound < ArgumentError; end
+
+    # Refers to {NetworkContext} the instance belongs to
+    # @return [NetworkContext]
+    attr_reader :context
+
+    # Tag of the collection. `nil` represents all lights
+    # @return [String]
+    attr_reader :tag
+
+    # Creates a {LightCollection} instance. Should not be used directly.
+    # @api private
+    # @param context: [NetworkContext] NetworkContext this collection belongs to
+    # @param tag: [String] Tag 
+    def initialize(context:, tag: nil)
+      @context = context
+      @tag = tag
+    end
+
+    # Queues a {Protocol::Payload} to be sent to bulbs in the collection
+    # @param payload [Protocol::Payload] Payload to be sent
+    # @param acknowledge: [Boolean] whether recipients should acknowledge message
+    # @api private
+    # @return [LightCollection] self for chaining
+    def send_message(payload, acknowledge: false)
+      if tag
+        context.send_message(target: Target.new(tag: tag), payload: payload, acknowledge: acknowledge)
+      else
+        context.send_message(target: Target.new(broadcast: true), payload: payload, acknowledge: acknowledge)
+      end
+      self
+    end
+
+    # Returns a {Light} with device id matching `id`
+    # @param id [String] Device ID
+    # @return [Light]
+    def with_id(id)
+      lights.find { |l| l.id == id}
+    end
+
+    # Returns a {Light} with its label matching `label`
+    # @param label [String, Regexp] Label
+    # @return [Light]
+    def with_label(label)
+      if label.is_a?(Regexp)
+        lights.find { |l| l.label(fetch: false) =~ label }
+      else
+        lights.find { |l| l.label(fetch: false) == label }
+      end
+    end
+
+    # Returns a {LightCollection} of {Light}s tagged with `tag`
+    # @param tag [String] Tag
+    # @return [LightCollection]
+    def with_tag(tag)
+      if context.tags.include?(tag)
+        self.class.new(context: context, tag: tag)
+      else
+        raise TagNotFound.new("No such tag '#{tag}'")
+      end
+    end
+
+    # Returns an Array of {Light}s
+    # @return [Array<Light>]
+    def lights
+      if tag
+        context.all_lights.select { |l| l.tags.include?(tag) }
+      else
+        context.all_lights
+      end
+    end
+
+    DEFAULT_ALIVE_THRESHOLD = 30 # seconds
+    # Returns an Array of {Light}s considered alive
+    # @param threshold: The maximum number of seconds a {Light} was last seen to be considered alive
+    def alive(threshold: DEFAULT_ALIVE_THRESHOLD)
+      lights.select { |l| l.seconds_since_seen <= threshold }
+    end
+
+    # Returns an Array of {Light}s considered stale
+    # @param threshold: The minimum number of seconds since a {Light} was last seen to be considered stale
+    def stale(threshold: DEFAULT_ALIVE_THRESHOLD)
+      lights.select { |l| l.seconds_since_seen > threshold }
+    end
+
+    # Returns a nice string representation of itself
+    # @return [String]
+    def to_s
+      %Q{#<#{self.class.name} lights=#{lights}#{tag ? " tag=#{tag}" : ''}>}
+    end
+    alias_method :inspect, :to_s
+
+    def_delegators :lights, :empty?, :each
+  end
+end

data/lib/lifx/light_target.rb

@@ -0,0 +1,189 @@
+module LIFX
+  # LightTarget is a module that contains Light commands that can work
+  # with either a single {Light} or multiple Lights via a {LightCollection}
+  module LightTarget
+    MSEC_PER_SEC   = 1000
+
+    # Attempts to set the color of the light(s) to `color` asynchronously.
+    # This method cannot guarantee that the message was received.
+    # @param color [Color] The color to be set
+    # @param duration: [Numeric] Transition time in seconds
+    # @return [Light, LightCollection] self for chaining
+    def set_color(color, duration: LIFX::Config.default_duration)
+      send_message(Protocol::Light::Set.new(
+        color: color.to_hsbk,
+        duration: (duration * MSEC_PER_SEC).to_i,
+        stream: 0,
+      ))
+      self
+    end
+
+    # Attempts to apply a waveform to the light(s) asynchronously.
+    # @note Don't use this directly.
+    # @api private
+    def set_waveform(color, waveform:,
+                            cycles:,
+                            stream: 0,
+                            transient: true,
+                            period: 1.0,
+                            duty_cycle: 0.5,
+                            acknowledge: false)
+      send_message(Protocol::Light::SetWaveform.new(
+        color: color.to_hsbk,
+        waveform: waveform,
+        cycles: cycles,
+        stream: stream,
+        transient: transient,
+        period: (period * 1_000).to_i,
+        duty_cycle: (duty_cycle * 65535).round - 32768
+      ), acknowledge: acknowledge)
+    end
+
+    # Attempts to make the light(s) pulse `color` and then back to its original color. Asynchronous.
+    # @param color [Color] Color to pulse
+    # @param duty_cycle: [Float] Percentage of a cycle the light(s) is set to `color`
+    # @param cycles: [Integer] Number of cycles
+    # @param transient: [Boolean] If false, the light will remain at the color the waveform is at when it ends
+    # @param period: [Integer] Number of seconds a cycle. Must be above 1.0 (?)
+    # @param stream: [Integer] Unused
+    def pulse(color, cycles: 1,
+                     duty_cycle: 0.5,
+                     transient: true,
+                     period: 1.0,
+                     stream: 0)
+      set_waveform(color, waveform: Protocol::Light::Waveform::PULSE,
+                          cycles: cycles,
+                          duty_cycle: duty_cycle,
+                          stream: stream,
+                          transient: transient,
+                          period: period)
+    end
+
+    # Attempts to make the light(s) transition to `color` and back in a smooth sine wave. Asynchronous.
+    # @param color [Color] Color
+    # @param cycles: [Integer] Number of cycles
+    # @param transient: [Boolean] If false, the light will remain at the color the waveform is at when it ends
+    # @param period: [Integer] Number of seconds a cycle. Must be above 1.0 (?)
+    # @param stream: [Integer] Unused
+    def sine(color, cycles: 1,
+                    period: 1.0,
+                    transient: true,
+                    stream: 0)
+      set_waveform(color, waveform: Protocol::Light::Waveform::SINE,
+                          cycles: cycles,
+                          duty_cycle: 0,
+                          stream: stream,
+                          transient: transient,
+                          period: period)
+    end
+
+    # Attempts to make the light(s) transition to `color` smoothly, then immediately back to its original color. Asynchronous.
+    # @param color [Color] Color
+    # @param cycles: [Integer] Number of cycles
+    # @param transient: [Boolean] If false, the light will remain at the color the waveform is at when it ends
+    # @param period: [Integer] Number of seconds a cycle. Must be above 1.0 (?)
+    # @param stream: [Integer] Unused
+    def half_sine(color, cycles: 1,
+                         period: 1.0,
+                         transient: true,
+                         stream: 0)
+      set_waveform(color, waveform: Protocol::Light::Waveform::HALF_SINE,
+                          cycles: cycles,
+                          stream: stream,
+                          transient: transient,
+                          period: period)
+    end
+
+    # Attempts to make the light(s) transition to `color` linearly and back. Asynchronous.
+    # @param color [Color] Color to pulse
+    # @param cycles: [Integer] Number of cycles
+    # @param transient: [Boolean] If false, the light will remain at the color the waveform is at when it ends
+    # @param period: [Integer] Number of seconds a cycle. Must be above 1.0 (?)
+    # @param stream: [Integer] Unused
+    def triangle(color, cycles: 1,
+                     period: 1.0,
+                     transient: true,
+                     stream: 0)
+      set_waveform(color, waveform: Protocol::Light::Waveform::TRIANGLE,
+                          cycles: cycles,
+                          stream: stream,
+                          transient: transient,
+                          period: period)
+    end
+
+    # Attempts to make the light(s) transition to `color` linearly, then instantly back. Asynchronous.
+    # @param color [Color] Color to saw wave
+    # @param cycles: [Integer] Number of cycles
+    # @param transient: [Boolean] If false, the light will remain at the color the waveform is at when it ends
+    # @param period: [Integer] Number of seconds a cycle. Must be above 1.0 (?)
+    # @param stream: [Integer] Unused
+    def saw(color, cycles: 1,
+                   period: 1.0,
+                   transient: true,
+                   stream: 0)
+      set_waveform(color, waveform: Protocol::Light::Waveform::SAW,
+                          cycles: cycles,
+                          stream: stream,
+                          transient: transient,
+                          period: period)
+    end
+
+    # Attempts to set the power state to `value` asynchronously.
+    # This method cannot guarantee the message was received.
+    # @param value [0, 1] 0 for off, 1 for on
+    # @return [Light, LightCollection] self for chaining
+    def set_power(value)
+      send_message(Protocol::Device::SetPower.new(level: value))
+      self
+    end
+
+    # Attempts to turn the light(s) on asynchronously.
+    # This method cannot guarantee the message was received.
+    # @return [Light, LightCollection] self for chaining
+    def turn_on
+      set_power(1)
+    end
+
+    # Attempts to turn the light(s) off asynchronously.
+    # This method cannot guarantee the message was received.
+    # @return [Light, LightCollection] self for chaining
+    def turn_off
+      set_power(0)
+    end
+
+    # Requests light(s) to report their state
+    # This method cannot guarantee the message was received.
+    # @return [Light, LightCollection] self for chaining
+    def refresh
+      send_message(Protocol::Light::Get.new)
+      self
+    end
+
+    # Attempts to set the site id of the light.
+    # Will clear label and tags. This method cannot guarantee message receipt.
+    # @note Don't use this unless you know what you're doing.
+    # @api private
+    # @param site_id [String] Site ID
+    # @return [void]
+    def set_site_id(site_id)
+      send_message(Protocol::Device::SetSite.new(site: [site_id].pack('H*')))
+    end
+
+    NSEC_IN_SEC = 1_000_000_000
+    # Attempts to set the device time on the targets
+    # @api private
+    # @param time [Time] The time to set
+    # @return [void]
+    def set_time(time = Time.now)
+      send_message(Protocol::Device::SetTime.new(time: (time.to_f * NSEC_IN_SEC).round))
+    end
+
+
+    # Attempts to reboots the light(s).
+    # This method cannot guarantee the message was received.
+    # @return [Light, LightCollection] self for chaining
+    def reboot!
+      send_message(Protocol::Device::Reboot.new)
+    end
+  end
+end

data/lib/lifx/logging.rb

@@ -0,0 +1,11 @@
+module LIFX
+  module Logging
+    def self.included(mod)
+      mod.extend(self)
+    end
+
+    def logger
+      LIFX::Config.logger
+    end
+  end
+end