huebot 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 565062504fb9277b5047788566d50d5ea36223567f9ad5d8466a7ffa7886b661
+  data.tar.gz: 31d364292a69ffa6193ead6699d4b0642249c686a4917e040acf6e42408e9d02
+SHA512:
+  metadata.gz: cbaaa7f8beb87c9443a697957766338d961ae08602e8472298d80234945b152e101099fa8ad5edae3226b86fe7c6a7528273034a29680a02f9d40c5ab99f4b34
+  data.tar.gz: e31b3ed57ccd4f47c64841c2707d067776d89f5f7c7b45c26393de0928f321f0a18d3c5fc7a89c7e432abea401f8262891d0b6b770dcfcc2b21ec9e0d99aa14f

data/README.md

@@ -0,0 +1,46 @@
+# Huebot
+
+Orchestration and automation for Philips Hue devices. Huebot can be used as a Ruby library or a command line utility. Huebot programs are declared as YAML files.
+
+    $ huebot run dimmer.yml --light="Office Desk"
+
+**dimmer.yml**
+
+This (very simple) program starts with the light(s) on at full brightness, then enters an infinite loop of slowly dimming and raising the light(s). Since no color is specified, the light(s) will retain whatever color they last had.
+
+## Install
+
+    gem install huebot
+
+The curl library headers are required. On Ubuntu they can be installed with `apt-get install libcurl4-openssl-dev`.
+
+```yaml
+initial:
+  switch: on
+  brightness: 254
+  device: $all
+
+loop: true
+
+transitions:
+  - device: $all
+    brightness: 150
+    time: 100
+    wait: 20
+
+  - device: $all
+    brightness: 254
+    time: 100
+    wait: 20
+```
+
+The variable `$all` refers to all lights and/or groups passed in on the command line. They can be also referred to individually as `$1`, `$2`, `$3`, etc. The names of lights and groups can also be hard-coded into your program. [See examples in the Wiki.](https://github.com/jhollinger/huebot/wiki)
+
+## UNDER ACTIVE DEVELOPMENT
+
+**TODO**
+
+* Validate number of inputs against compiled programs
+* Brief explanation various features
+* Wiki entry with more examples
+* Link to official Hue docs

data/bin/huebot

@@ -0,0 +1,48 @@
+#!/usr/bin/env ruby
+
+# TODO remove
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'huebot'
+require 'huebot/cli'
+
+Huebot::CLI.tap { |cli|
+  case cli.get_cmd
+  when :ls
+    client = Hue::Client.new
+    puts "Lights\n" + client.lights.map { |l| "  #{l.id}: #{l.name}" }.join("\n") + \
+      "\nGroups\n" + client.groups.map { |g| "  #{g.id}: #{g.name}" }.join("\n")
+
+  when :run
+    opts, sources = cli.get_input!
+
+    client = Hue::Client.new
+    device_mapper = Huebot::DeviceMapper.new(client, opts.inputs)
+    compiler = Huebot::Compiler.new(device_mapper)
+
+    programs = sources.map { |src|
+      compiler.build src.ir, File.basename(src.filepath, ".*")
+    }
+    found_errors, _found_warnings = cli.check! programs, $stderr
+    exit 1 if found_errors
+
+    bot = Huebot::Bot.new(client)
+    programs.each { |prog| bot.execute prog }
+
+  when :check
+    opts, sources = cli.get_input!
+
+    client = Hue::Client.new
+    device_mapper = Huebot::DeviceMapper.new(client, opts.inputs)
+    compiler = Huebot::Compiler.new(device_mapper)
+
+    programs = sources.map { |src|
+      compiler.build src.ir, File.basename(src.filepath, ".*")
+    }
+    found_errors, found_warnings = cli.check! programs, $stdout
+    # TODO validate NUMBER of inputs against each program
+    exit (found_errors || found_warnings) ? 1 : 0
+
+  else cli.help!
+  end
+}

data/lib/huebot.rb

@@ -0,0 +1,31 @@
+require 'hue'
+
+module Huebot
+  autoload :DeviceMapper, 'huebot/device_mapper'
+  autoload :Program, 'huebot/program'
+  autoload :Compiler, 'huebot/compiler'
+  autoload :Bot, 'huebot/bot'
+  autoload :VERSION, 'huebot/version'
+
+  #
+  # Struct for storing a program's Intermediate Representation and source filepath.
+  #
+  # @attr ir [Hash]
+  # @attr filepath [String]
+  #
+  ProgramSrc = Struct.new(:ir, :filepath)
+
+  #
+  # Struct for specifying a Light input (id or name)
+  #
+  # @attr val [Integer|String] id or name
+  #
+  LightInput = Struct.new(:val)
+
+  #
+  # Struct for specifying a Gropu input (id or name)
+  #
+  # @attr val [Integer|String] id or name
+  #
+  GroupInput = Struct.new(:val)
+end

data/lib/huebot/bot.rb

@@ -0,0 +1,66 @@
+module Huebot
+  class Bot
+    attr_reader :client
+
+    Error = Class.new(StandardError)
+
+    def initialize(client)
+      @client = client
+    end
+
+    def execute(program)
+      transition program.initial_state if program.initial_state
+
+      if program.transitions.any?
+        if program.loop?
+          loop { iterate program.transitions }
+        elsif program.loops > 0
+          program.loops.times { iterate program.transitions }
+        else
+          iterate program.transitions
+        end
+      end
+
+      transition program.final_state if program.final_state
+    end
+
+    private
+
+    def iterate(transitions)
+      transitions.each do |t|
+        if t.respond_to?(:children)
+          parallel_transitions t
+        else
+          transition t
+        end
+      end
+    end
+
+    def parallel_transitions(t)
+      t.children.map { |sub_t|
+        Thread.new {
+          transition sub_t
+        }
+      }.map(&:join)
+      wait t.wait if t.wait and t.wait > 0
+    end
+
+    def transition(t)
+      time = t.state[:transitiontime] || 4
+      t.devices.map { |device|
+        Thread.new {
+          device.set_state t.state
+          wait time
+          wait t.wait if t.wait
+        }
+      }.map(&:join)
+    end
+
+    def wait(time)
+      ms = time * 100
+      seconds = ms / 1000.to_f
+      # TODO sleep in small bursts in a loop so can detect if an Interrupt was caught
+      sleep seconds
+    end
+  end
+end

data/lib/huebot/cli.rb

@@ -0,0 +1,118 @@
+require 'optparse'
+require 'ostruct'
+require 'yaml'
+
+module Huebot
+  #
+  # Helpers for running huebot in cli-mode.
+  #
+  module CLI
+    #
+    # Struct for storing cli options and program files.
+    #
+    # @attr inputs [Array<String>]
+    #
+    Options = Struct.new(:inputs)
+
+    #
+    # Returns the command given to huebot.
+    #
+    # @return [Symbol]
+    #
+    def self.get_cmd
+      ARGV[0].to_s.to_sym
+    end
+
+    #
+    # Parses and returns input from the CLI. Serious errors might result in the program exiting.
+    #
+    # @return [Huebot::CLI::Options] All given CLI options
+    # @return [Array<Huebot::ProgramSrc>] Array of given program sources
+    #
+    def self.get_input!
+      options, parser = option_parser
+      parser.parse!
+
+      files = ARGV[1..-1]
+      if files.empty?
+        puts parser.help
+        exit 1
+      elsif (bad_paths = files.select { |p| !File.exists? p }).any?
+        $stderr.puts "Cannot find #{bad_paths.join ', '}"
+        exit 1
+      else
+        return options, files.map { |path|
+          ProgramSrc.new(YAML.load_file(path), path)
+        }
+      end
+    end
+
+    #
+    # Prints any program errors or warnings, and returns a boolean for each.
+    #
+    # @param programs [Array<Huebot::Program>]
+    # @param io [IO] Usually $stdout or $stderr
+    # @param quiet [Boolean] if true, don't print anything
+    #
+    def self.check!(programs, io, quiet: false)
+      if (invalid_progs = programs.select { |prog| prog.errors.any? }).any?
+        print_messages! io, "Errors", invalid_progs, :errors unless quiet
+      end
+
+      if (imperfect_progs = programs.select { |prog| prog.warnings.any? }).any?
+        puts "" if invalid_progs.any?
+        print_messages! io, "Warnings", imperfect_progs, :warnings unless quiet
+      end
+
+      return invalid_progs.any?, imperfect_progs.any?
+    end
+
+    # Print help and exit
+    def self.help!
+      _, parser = option_parser
+      puts parser.help
+      exit 1
+    end
+
+    private
+
+    #
+    # Print each message (of the given type) for each program.
+    #
+    # @param io [IO] Usually $stdout or $stderr
+    # @param label [String] Top-level for this group of messages
+    # @param progs [Array<Huebot::CLI::Program>]
+    # @param msg_type [Symbol] name of method that holds the messages (i.e. :errors or :warnings)
+    #
+    def self.print_messages!(io, label, progs, msg_type)
+      io.puts "#{label}:"
+      progs.each { |prog|
+        io.puts "  #{prog.name}:"
+        prog.send(msg_type).each_with_index { |msg, i| io.puts "    #{i+1}. #{msg}" }
+      }
+    end
+
+    def self.option_parser
+      options = Options.new([])
+      parser = OptionParser.new { |opts|
+        opts.banner = %(
+List all lights and groups:
+    huebot ls
+
+Run program(s):
+    huebot run file1.yml [file2.yml [file3.yml ...]] [options]
+
+Validate programs and inputs:
+    huebot check file1.yml [file2.yml [file3.yml ...]] [options]
+
+Options:
+        ).strip
+        opts.on("-lLIGHT", "--light=LIGHT", "Light ID or name") { |l| options.inputs << LightInput.new(l) }
+        opts.on("-gGROUP", "--group=GROUP", "Group ID or name") { |g| options.inputs << GroupInput.new(g) }
+        opts.on("--all", "All lights and groups TODO") { $stderr.puts "Not Implemented"; exit 1 }
+        opts.on("-h", "--help", "Prints this help") { puts opts; exit }
+      }
+      return options, parser
+    end
+  end
+end

data/lib/huebot/compiler.rb

@@ -0,0 +1,159 @@
+module Huebot
+  class Compiler
+    def initialize(device_mapper)
+      @device_mapper = device_mapper
+    end
+
+    #
+    # Build a huebot program from an intermediate representation (a Hash).
+    #
+    # @param ir [Hash]
+    # @param default_name [String] A name to use if one isn't specified
+    # @return [Huebot::Program]
+    #
+    def build(ir, default_name = nil)
+      ir = ir.clone
+      prog = Huebot::Program.new
+      prog.name = ir.delete("name") || default_name
+
+      # loop/loops
+      val_loop = ir.delete("loop") || ir.delete(:loop)
+      prog.errors << "'loop' must be 'true' or 'false'." if !val_loop.nil? and ![true, false].include?(val_loop)
+      prog.loop = val_loop == true
+
+      val_loops = ir.delete("loops") || ir.delete(:loops)
+      prog.errors << "'loops' must be a positive integer." if !val_loops.nil? and val_loops.to_i < 0
+      prog.loops = val_loops.to_i
+
+      prog.errors << "'loop' and 'loops' are mutually exclusive." if prog.loop? and prog.loops > 0
+
+      # initial state
+      if (val_init = ir.delete("initial") || ir.delete(:initial))
+        errors, warnings, state = build_transition val_init
+        prog.initial_state = state
+        prog.errors += errors
+        prog.warnings += warnings
+      end
+
+      # transitions
+      if (val_trns = ir.delete("transitions") || ir.delete(:transitions))
+        val_trns.each do |val_trn|
+          errors, warnings, state = if val_trn["parallel"] || val_trn[:parallel]
+                                      build_parallel_transition val_trn
+                                    else
+                                      build_transition val_trn
+                                    end
+          prog.transitions << state
+          prog.errors += errors
+          prog.warnings += warnings
+        end
+      end
+
+      # final state
+      if (val_fnl = ir.delete("final") || ir.delete(:final))
+        errors, warnings, state = build_transition val_fnl
+        prog.final_state = state
+        prog.errors += errors
+        prog.warnings += warnings
+      end
+
+      # be strict about extra crap
+      if (unknown = ir.keys.map(&:to_s)).any?
+        prog.errors << "Unrecognized values: #{unknown.join ', '}."
+      end
+
+      # Add any warnings
+      prog.warnings << "'final' is defined but will never be reached because 'loop' is 'true'." if prog.final_state and prog.loop?
+
+      prog
+    end
+
+    private
+
+    def build_parallel_transition(t)
+      errors, warnings = [], []
+      transition = Huebot::Program::ParallelTransition.new(0, [])
+
+      transition.wait = t.delete("wait") || t.delete(:wait)
+      errors << "'wait' must be a positive integer." if transition.wait and transition.wait.to_i <= 0
+
+      parallel = t.delete("parallel") || t.delete(:parallel)
+      if !parallel.is_a? Array
+        errors << "'parallel' must be an array of transitions"
+      else
+        parallel.each do |sub_t|
+          sub_errors, sub_warnings, sub_transition = build_transition(sub_t)
+          errors += sub_errors
+          warnings += sub_warnings
+          transition.children << sub_transition
+        end
+      end
+
+      return errors, warnings, transition
+    end
+
+    def build_transition(t)
+      errors, warnings = [], []
+      transition = Huebot::Program::Transition.new
+      transition.devices = []
+
+      map_devices(t, :light, :lights, :light!) { |map_errors, devices|
+        errors += map_errors
+        transition.devices += devices
+      }
+
+      map_devices(t, :group, :groups, :group!) { |map_errors, devices|
+        errors += map_errors
+        transition.devices += devices
+      }
+
+      map_devices(t, :device, :devices, :var!) { |map_errors, devices|
+        errors += map_errors
+        transition.devices += devices
+      }
+      errors << "Missing light/lights, group/groups, or device/devices" if transition.devices.empty?
+
+      transition.wait = t.delete("wait") || t.delete(:wait)
+      errors << "'wait' must be a positive integer." if transition.wait and transition.wait.to_i <= 0
+
+      state = {}
+      switch = t.delete("switch")
+      switch = t.delete(:switch) if switch.nil?
+      if !switch.nil?
+        state[:on] = case switch
+                     when true, :on then true
+                     when false, :off then false
+                     else
+                       errors << "Unrecognized 'switch' value '#{switch}'."
+                       nil
+                     end
+      end
+      state[:transitiontime] = t.delete("time") || t.delete(:time) || t.delete("transitiontime") || t.delete(:transitiontime) || 4
+
+      transition.state = t.merge(state).reduce({}) { |a, (key, val)|
+        a[key.to_sym] = val
+        a
+      }
+      return errors, warnings, transition
+    end
+
+    private
+
+    def map_devices(t, singular_key, plural_key, ref_type)
+      errors, devices = [], []
+
+      key = t[singular_key.to_s] || t[singular_key]
+      keys = t[plural_key.to_s] || t[plural_key]
+
+      (Array(key) + Array(keys)).each { |x|
+        begin
+          devices += Array(@device_mapper.send(ref_type, x))
+        rescue Huebot::DeviceMapper::Unmapped => e
+          errors << e.message
+        end
+      }
+
+      yield errors, devices
+    end
+  end
+end

data/lib/huebot/device_mapper.rb

@@ -0,0 +1,51 @@
+module Huebot
+  class DeviceMapper
+    Unmapped = Class.new(StandardError)
+
+    def initialize(client, inputs = [])
+      all_lights, all_groups = client.lights, client.groups
+
+      @lights_by_id = all_lights.reduce({}) { |a, l| a[l.id] = l; a }
+      @lights_by_name = all_lights.reduce({}) { |a, l| a[l.name] = l; a }
+      @groups_by_id = all_groups.reduce({}) { |a, g| a[g.id] = g; a }
+      @groups_by_name = all_groups.reduce({}) { |a, g| a[g.name] = g; a }
+      @devices_by_var = inputs.each_with_index.reduce({}) { |a, (x, idx)|
+        dev = case x
+              when LightInput then @lights_by_id[x.val] || @lights_by_name[x.val]
+              when GroupInput then @groups_by_id[x.val] || @groups_by_name[x.val]
+              else raise "Invalid input: #{x}"
+              end || raise(Unmapped, "Could not find #{x.class.name[8..-6].downcase} with id or name '#{x.val}'")
+        a["$#{idx + 1}"] = dev
+        a
+      }
+      @all = @devices_by_var.values
+    end
+
+    def light!(id)
+      case id
+      when Integer
+        @lights_by_id[id]
+      when String
+        @lights_by_name[id]
+      end || (raise Unmapped, "Unmapped light '#{id}'")
+    end
+
+    def group!(id)
+      case id
+      when Integer
+        @groups_by_id[id]
+      when String
+        @groups_by_name[id]
+      end || (raise Unmapped, "Unmapped group '#{id}'")
+    end
+
+    def var!(id)
+      case id
+      when "$all"
+        @all
+      else
+        @devices_by_var[id]
+      end || (raise Unmapped, "Unmapped device '#{id}'")
+    end
+  end
+end

data/lib/huebot/program.rb

@@ -0,0 +1,32 @@
+module Huebot
+  class Program
+    Transition = Struct.new(:wait, :state, :devices)
+    ParallelTransition = Struct.new(:wait, :children)
+
+    attr_accessor :name
+    attr_accessor :initial_state
+    attr_accessor :transitions
+    attr_accessor :final_state
+    attr_accessor :loop
+    attr_accessor :loops
+    attr_accessor :errors
+    attr_accessor :warnings
+
+    def initialize
+      @name = nil
+      @initial_state = nil
+      @transitions = []
+      @final_state = nil
+      @loop = false
+      @loops = 0
+      @errors = []
+      @warnings = []
+    end
+
+    def valid?
+      errors.empty?
+    end
+
+    alias_method :loop?, :loop
+  end
+end

data/lib/huebot/version.rb

@@ -0,0 +1,4 @@
+module Huebot
+  # Gem version
+  VERSION = '0.1.0'
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: huebot
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jordan Hollinger
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2018-12-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: hue
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+description: Declare and run YAML programs for Philips Hue devices
+email: jordan.hollinger@gmail.com
+executables:
+- huebot
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/huebot
+- lib/huebot.rb
+- lib/huebot/bot.rb
+- lib/huebot/cli.rb
+- lib/huebot/compiler.rb
+- lib/huebot/device_mapper.rb
+- lib/huebot/program.rb
+- lib/huebot/version.rb
+homepage: https://github.com/jhollinger/huebot
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: Orchestration for Hue devices
+test_files: []