huebot 0.4.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 267bb3cc14e143785af2250a762b365f513bb18a3630b68edf10d3df3748de2a
-  data.tar.gz: 7afa69b3aa54a936deebbcea75b409f2411fa5482554b22cd29aff088ce351b6
+  metadata.gz: 5da1b1dcd0f32ce09e44155b39d7bc6ed92aa285944fc3a67801cf02642737c0
+  data.tar.gz: 9116d3a891e608276e64517f9252a42cddd615ca9952c55e816ca53196bdde15
 SHA512:
-  metadata.gz: 442d3fb05c7f1e6610437ff5fc2f92d25694e2e9342ff9b16217ba80b7982538d48f807304e487fd583385864e9f4cf86491e33d2c66ba663b22449867ba780c
-  data.tar.gz: '01908c65fb9c472271904973e313bc080eb96d91b557ef2e8bb3902a5ea054f7fb71b3b37bf6f51f356bf742c5ab32a336e4c013059a0a537dc3a538955dfc97'
+  metadata.gz: fc1ae1f775c685e635fe36d85ef33548a50163f80378f42301f73e9bdf868343fecb4b9a9fa64490466771dc44b51f95745587bc32423e65cdc306dae0e01fa9
+  data.tar.gz: b5721fb115fc0f8c38e9389063a9012a51d7aa2fa0cf2f1b7a2d93812d916b2ffb1f27508358483a9656b4bdb09d7f78fc7bd9e4f65ff599214c9cdd2f0e8a93

data/README.md

@@ -1,50 +1,120 @@
 # 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.
+Program your Hue lights!
 
     $ huebot run dimmer.yml --light="Office Desk"
 
-**dimmer.yml**
+A few examples are below. [See the Wiki](https://github.com/jhollinger/huebot/wiki) for full documentation.
 
-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.
+**dimmer.yaml**
+
+This (very simple) program starts with the light(s) on at full brightness, then enters an hour and a half long loop of slowly dimming and raising the light(s). It finishes by turning them off again. Since no color is specified, the light(s) will retain whatever color they last had.
+
+```yaml
+serial:
+  devices:
+    lights:
+      - LR Lamp 1
+      - LR Lamp 2
+    groups:
+      - Dining Room
+  steps:
+    - transition:
+        state:
+          on: true
+          bri: 254
+
+    - serial:
+        loop:
+          timer:
+            hours: 1
+            minutes: 30
+        steps:
+          - transition:
+              state:
+                bri: 150
+                time: 10 # 10 second transition
+              pause: 2   # 2 second pause before the next step
+
+          - transition:
+              state:
+                bri: 254
+                time: 10 # 10 second transition
+              pause: 2   # 2 second pause before the next step
+
+    - transition:
+        state:
+          on: false
+```
+
+**party.yaml**
+
+This more complicated program starts by switching devices on, then enters an infinite loop of two parallel steps. One branch fades up and down while the other branch is fading more lights down _then_ up.
 
 ```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
+serial:
+  steps:
+    # Turn all inputs on to a mid brightness
+    - transition:
+        devices:
+          inputs: $all
+        state:
+          on: true
+          bri: 100
+
+    # Run these steps in parallel in an infinite loop
+    - parallel:
+        loop: true
+        steps:
+          # Parallel branch 1: Fade inputs #1 and #3 up and down
+          - serial:
+              devices:
+                inputs:
+                  - $1
+                  - $3
+              steps:
+                - transition:
+                    state:
+                      bri: 254
+                      time: 10 # transition over 10 seconds
+                    pause: 5   # pause an extra 5 sec after the transition
+                - transition:
+                    state:
+                      bri: 25
+                      time: 10
+                    pause: 5
+
+          # Parallel branch 2: Fade inputs #2 and #4 down and up
+          - serial:
+              devices:
+                inputs:
+                  - $2
+                  - $4
+              steps:
+                - transition:
+                    state:
+                      bri: 25
+                      time: 10
+                    pause: 5
+                - transition:
+                    state:
+                      bri: 254
+                      time: 10
+                    pause: 5
 ```
 
-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)
+[See the Wiki](https://github.com/jhollinger/huebot/wiki) for more documentation and examples.
 
 ## Install
 
     gem install huebot
 
-## License
-
-Huebot is licensed under the MIT license (see LICENSE file).
+Having trouble with Hue Bridge auto discovery? Me too. If you know your bridge's IP (and ideally have assigned it a static one), you can set it manually:
 
-A patched version of the "hue" gem is bundled in huebot's codebase (to remove a dependency that's unnecessarily annoying to install). The license for it can be found at `lib/hue/LICENSE`.
+    huebot set-ip <your bridge's IP>
 
-## UNDER ACTIVE DEVELOPMENT
+Configuration is stored in `~/.config/huebot`.
 
-**TODO**
+## License
 
-* Validate number of inputs against compiled programs
-* Brief explanation various features
-* Wiki entry with more examples
-* Link to official Hue docs
+Huebot is licensed under the MIT license (see LICENSE file).

data/bin/huebot

@@ -1,47 +1,80 @@
 #!/usr/bin/env ruby
 
 # Used for local testing
-# $LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
+$LOAD_PATH.unshift File.join(File.dirname(__FILE__), '..', 'lib')
 
 require 'huebot'
-require 'huebot/cli'
 
-Huebot::CLI.tap { |cli|
+Huebot::CLI::Helpers.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")
+    bridge, error = Huebot::Bridge.connect
+    if error
+      $stderr.puts error
+      exit 1
+    end
+    retval = Huebot::CLI::Runner.ls bridge
+    exit retval
 
   when :run
     opts, sources = cli.get_input!
+    if sources.empty?
+      cli.help!
+      exit 1
+    end
 
-    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 }
+    bridge, error = Huebot::Bridge.connect
+    if error
+      $stderr.puts error
+      exit 1
+    end
+    retval = Huebot::CLI::Runner.run(bridge, sources, opts)
+    exit retval
 
   when :check
     opts, sources = cli.get_input!
+    if sources.empty?
+      cli.help!
+      exit 1
+    end
+
+    bridge, error = Huebot::Bridge.connect
+    if error
+      $stderr.puts error
+      exit 1
+    end
+    retval = Huebot::CLI::Runner.check(bridge, sources, opts)
+    exit retval
+
+  when :"get-state"
+    opts, _sources = cli.get_input!
+    if opts.inputs.empty?
+      cli.help!
+      exit 1
+    end
+
+    bridge, error = Huebot::Bridge.connect
+    if error
+      $stderr.puts error
+      exit 1
+    end
+    retval = Huebot::CLI::Runner.get_state(bridge, opts.inputs)
+    exit retval
+
+  when :"set-ip"
+    ip = cli.get_args(num: 1).first
+    retval = Huebot::CLI::Runner.set_ip ip
+    exit retval
 
-    client = Hue::Client.new
-    device_mapper = Huebot::DeviceMapper.new(client, opts.inputs)
-    compiler = Huebot::Compiler.new(device_mapper)
+  when :"clear-ip"
+    cli.get_args(num: 0)
+    retval = Huebot::CLI::Runner.unregister
+    exit retval
 
-    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
+  when :unregister
+    cli.get_args(num: 0)
+    retval = Huebot::CLI::Runner.unregister
+    exit retval
 
   else cli.help!
   end

data/lib/huebot/bot.rb

@@ -1,64 +1,107 @@
 module Huebot
   class Bot
-    attr_reader :client
-
     Error = Class.new(StandardError)
 
-    def initialize(client)
-      @client = client
+    def initialize(device_mapper)
+      @device_mapper = device_mapper
+      #@client = device_mapper.bridge.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
+      exec program.data
     end
 
     private
 
-    def iterate(transitions)
-      transitions.each do |t|
-        if t.respond_to?(:children)
-          parallel_transitions t
-        else
-          transition t
-        end
+    def exec(node)
+      i = node.instruction
+      case i
+      when Program::AST::Transition
+        transition i.state, i.devices, i.sleep
+      when Program::AST::SerialControl
+        serial node.children, i.loop, i.sleep
+      when Program::AST::ParallelControl
+        parallel node.children, i.loop, i.sleep
+      else
+        raise Error, "Unexpected instruction '#{i.class.name}'"
       end
     end
 
-    def parallel_transitions(t)
-      t.children.map { |sub_t|
+    def transition(state, device_refs, sleep_time = nil)
+      time = (state["transitiontime"] || 4).to_f / 10
+      devices = map_devices device_refs
+      devices.map { |device|
         Thread.new {
-          transition sub_t
+          # TODO error handling
+          device.set_state state
+          wait time
         }
       }.map(&:join)
-      wait t.wait if t.wait and t.wait > 0
+      wait sleep_time if sleep_time
     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
+    def serial(nodes, lp, sleep_time = nil)
+      control_loop(lp) {
+        nodes.map { |node|
+          exec node
         }
-      }.map(&:join)
+      }
+      wait sleep_time if sleep_time
+    end
+
+    def parallel(nodes, lp, sleep_time = nil)
+      control_loop(lp) {
+        nodes.map { |node|
+          Thread.new {
+            # TODO error handling
+            exec node
+          }
+        }.map(&:join)
+      }
+      wait sleep_time if sleep_time
+    end
+
+    def control_loop(lp)
+      case lp
+      when Program::AST::InfiniteLoop
+        loop { yield }
+      when Program::AST::CountedLoop
+        lp.n.times { yield }
+      when Program::AST::DeadlineLoop
+        until Time.now >= lp.stop_time
+          yield
+        end
+      when Program::AST::TimerLoop
+        sec = ((lp.hours * 60) + lp.minutes) * 60
+        time = 0
+        until time >= sec
+          start = Time.now
+          yield
+          time += (Time.now - start).round
+        end
+      else
+        raise Error, "Unexpected loop type '#{lp.class.name}'"
+      end
+    end
+
+    def map_devices(refs)
+      refs.reduce([]) { |acc, ref|
+        devices =
+          case ref
+          when Program::AST::Light
+            [@device_mapper.light!(ref.name)]
+          when Program::AST::Group
+            [@device_mapper.group!(ref.name)]
+          when Program::AST::DeviceRef
+            Array(@device_mapper.var! ref.ref)
+          else
+            raise Error, "Unknown device reference '#{ref.class.name}'"
+          end
+        acc + devices
+      }
     end
 
-    def wait(time)
-      ms = time * 100
-      seconds = ms / 1000.to_f
+    def wait(seconds)
       # TODO sleep in small bursts in a loop so can detect if an Interrupt was caught
       sleep seconds
     end

data/lib/huebot/bridge.rb

@@ -0,0 +1,24 @@
+module Huebot
+  class Bridge
+    def self.connect(config = Huebot::Config.new)
+      client = Client.new(config)
+      error = client.connect
+      return nil, error if error
+      return new(client)
+    end
+
+    attr_reader :client
+
+    def initialize(client)
+      @client = client
+    end
+
+    def lights
+      client.get!("/lights").map { |(id, attrs)| Light.new(client, id, attrs) }
+    end
+
+    def groups
+      client.get!("/groups").map { |(id, attrs)| Group.new(client, id, attrs) }
+    end
+  end
+end

data/lib/huebot/cli/helpers.rb

@@ -0,0 +1,170 @@
+require 'optparse'
+require 'yaml'
+
+module Huebot
+  module CLI
+    module Helpers
+      #
+      # Returns the command given to huebot.
+      #
+      # @return [Symbol]
+      #
+      def self.get_cmd
+        ARGV[0].to_s.to_sym
+      end
+
+      def self.get_args(min: nil, max: nil, num: nil)
+        args = ARGV[1..]
+        if num
+          if num != args.size
+            $stderr.puts "Expected #{num} args, found #{args.size}"
+            exit 1
+          end
+        elsif min and max
+          if args.size < min or args.size > max
+            $stderr.puts "Expected #{min}-#{max} args, found #{args.size}"
+          end
+        elsif min
+          if args.size < min
+            $stderr.puts "Expected at least #{num} args, found #{args.size}"
+            exit 1
+          end
+        elsif max
+          if args.size > max
+            $stderr.puts "Expected no more than #{num} args, found #{args.size}"
+            exit 1
+          end
+        end
+        args
+      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::Program::Src>] Array of given program sources
+      #
+      def self.get_input!
+        options, parser = option_parser
+        parser.parse!
+
+        files = ARGV[1..-1]
+        if (bad_paths = files.select { |p| !File.exist? p }).any?
+          $stderr.puts "Cannot find #{bad_paths.join ', '}"
+          exit 1
+        end
+
+        sources = files.map { |path|
+          src = YAML.load_file(path)
+          version = (src.delete("version") || 1.0).to_f
+          Program::Src.new(src, path, version)
+        }
+
+        if options.read_stdin
+          src = YAML.load($stdin.read)
+          version = (src.delete("version") || 1.0).to_f
+          sources << Program::Src.new(src, "STDIN", version)
+        end
+        return options, sources
+      end
+
+      #
+      # Prints any program errors or warnings, and returns a boolean for each.
+      #
+      # @param programs [Array<Huebot::Program>]
+      # @param device_mapper [Huebot::DeviceMapper]
+      # @param io [IO] Usually $stdout or $stderr
+      # @param quiet [Boolean] if true, don't print anything
+      #
+      def self.check!(programs, device_mapper, io, quiet: false)
+        if (invalid_progs = programs.select { |prog| prog.errors.any? }).any?
+          errors = invalid_progs.reduce([]) { |acc, prog|
+            acc + prog.errors.map { |e| "  #{prog.name}: #{e}" }
+          }
+          print_messages! io, "Errors", errors unless quiet
+        end
+
+        if (imperfect_progs = programs.select { |prog| prog.warnings.any? }).any?
+          warnings = imperfect_progs.reduce([]) { |acc, prog|
+            acc + prog.warnings.map { |e| "  #{prog.name}: #{e}" }
+          }
+          print_messages! io, "Warnings", warnings unless quiet
+        end
+
+        all_lights = programs.reduce([]) { |acc, p| acc + p.light_names }
+        if (missing_lights = device_mapper.missing_lights all_lights).any?
+          print_messages! io, "Unknown lights", missing_lights
+        end
+
+        all_groups = programs.reduce([]) { |acc, p| acc + p.group_names }
+        if (missing_groups = device_mapper.missing_groups all_groups).any?
+          print_messages! io, "Unknown groups", missing_groups
+        end
+
+        all_vars = programs.reduce([]) { |acc, p| acc + p.device_refs }
+        if (missing_vars = device_mapper.missing_vars all_vars).any?
+          print_messages! io, "Unknown device inputs", missing_vars.map { |d| "$#{d}" }
+        end
+
+        invalid_devices = missing_lights.size + missing_groups.size + missing_vars.size
+        return invalid_progs.any?, imperfect_progs.any?, invalid_devices > 0
+      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 errors [Array<String>]
+      #
+      def self.print_messages!(io, label, errors)
+        io.puts "#{label}:"
+        errors.each_with_index { |msg, i|
+          io.puts "  #{i+1}) #{msg}"
+        }
+      end
+
+      def self.option_parser
+        options = Options.new([], false)
+        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]
+
+  Print the current state of the given lights and/or groups:
+      huebot get-state [options]
+
+  Manually set/clear the IP for your Hue Bridge (useful when on a VPN):
+      huebot set-ip 192.168.1.20
+      huebot clear-ip
+
+  Clear all connection config:
+    huebot unregister
+
+  Options:
+          ).strip
+          opts.on("-lLIGHT", "--light=LIGHT", "Light ID or name") { |l| options.inputs << Light::Input.new(l) }
+          opts.on("-gGROUP", "--group=GROUP", "Group ID or name") { |g| options.inputs << Group::Input.new(g) }
+          opts.on("-i", "Read program from STDIN") { options.read_stdin = true }
+          opts.on("-h", "--help", "Prints this help") { puts opts; exit }
+        }
+        return options, parser
+      end
+    end
+  end
+end

data/lib/huebot/cli/runner.rb

@@ -0,0 +1,78 @@
+module Huebot
+  module CLI
+    module Runner
+      def self.ls(bridge)
+        puts "Lights\n" + bridge.lights.map { |l| "  #{l.id}: #{l.name}" }.join("\n") + \
+          "\nGroups\n" + bridge.groups.map { |g| "  #{g.id}: #{g.name}" }.join("\n")
+        return 0
+      rescue ::Huebot::Error => e
+        $stderr.puts "#{e.class.name}: #{e.message}"
+        return 1
+      end
+
+      def self.run(bridge, sources, opts)
+        device_mapper = Huebot::DeviceMapper.new(bridge, opts.inputs)
+        programs = sources.map { |src|
+          Huebot::Compiler.build src
+        }
+        found_errors, _found_warnings, missing_devices = Helpers.check! programs, device_mapper, $stderr
+        return 1 if found_errors || missing_devices
+
+        bot = Huebot::Bot.new(device_mapper)
+        programs.each { |prog| bot.execute prog }
+        return 0
+      rescue ::Huebot::Error => e
+        $stderr.puts "#{e.class.name}: #{e.message}"
+        return 1
+      end
+
+      def self.check(bridge, sources, opts)
+        device_mapper = Huebot::DeviceMapper.new(bridge, opts.inputs)
+        programs = sources.map { |src|
+          Huebot::Compiler.build src
+        }
+        found_errors, found_warnings, missing_devices = Helpers.check! programs, device_mapper, $stdout
+        return (found_errors || found_warnings || missing_devices) ? 1 : 0
+      rescue ::Huebot::Error => e
+        $stderr.puts "#{e.class.name}: #{e.message}"
+        return 1
+      end
+
+      def self.get_state(bridge, inputs)
+        device_mapper = Huebot::DeviceMapper.new(bridge, inputs)
+        device_mapper.each do |device|
+          puts device.name
+          puts "  #{device.get_state}"
+        end
+        0
+      end
+
+      def self.set_ip
+        config = Huebot::Config.new
+        config["ip"] = ip
+        0
+      rescue ::Huebot::Error => e
+        $stderr.puts "#{e.class.name}: #{e.message}"
+        return 1
+      end
+
+      def self.clear_ip
+        config = Huebot::Config.new
+        config["ip"] = nil
+        0
+      rescue ::Huebot::Error => e
+        $stderr.puts "#{e.class.name}: #{e.message}"
+        return 1
+      end
+
+      def self.unregister
+        config = Huebot::Config.new
+        config.clear
+        0
+      rescue ::Huebot::Error => e
+        $stderr.puts "#{e.class.name}: #{e.message}"
+        return 1
+      end
+    end
+  end
+end