ruhue 0.1.0

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/Gemfile

@@ -0,0 +1,7 @@
+source :rubygems
+
+gemspec
+
+gem 'pry'
+gem 'yard'
+gem 'redcarpet'

data/README.md

@@ -0,0 +1,66 @@
+# Ruhue
+
+So far, mere documentations of my findings when sniffing the Hue.
+
+There is a mailing list, dedicated to discussions and questions about hacking the
+Philips Hue and related protocols.
+
+- Mailing list web interface: <https://groups.google.com/d/forum/hue-hackers>
+- Mailing list e-mail address: <hue-hackers@googlegroups.com>
+
+Other link resources:
+
+- [Hack the Hue](http://rsmck.co.uk/hue)
+- [A Day with Philips Hue](http://www.nerdblog.com/2012/10/a-day-with-philips-hue.html?showComment=1352172383498)
+
+## Console
+
+There is a console script in this repository, written by @Burgestrand as the
+documentation effort travels further. It is written in Ruby, and only supports
+Ruby 1.9.x and newer. You may start the console with the following:
+
+1. Install bundler: `gem install bundler`
+2. Install console script dependencies: `bundle install`
+3. Run the console script: `ruby console.rb`
+
+You’ll be dropped into a pry prompt (similar to IRB), with access to the following
+local variables:
+
+- hue — a Hue instance, documented in `lib/hue.rb`
+- client — a Hue::Client, documented in `lib/hue/client.rb`
+
+Once the Hue API exploration adventure starts slowing down, the scripts will be
+turned into a ruby gem and tested with rspec.
+
+## API
+
+The API reference documentation has moved to the [hue-api][] repository. It is
+hosted on <http://burgestrand.github.com/hue-api/> using GitHub Pages. Contributions
+are very welcome, and if you’d like commit access to the hue-api repository, just ask!
+
+[hue-api]: https://github.com/Burgestrand/hue-api
+
+## Gem License
+
+Copyright (c) 2012 Kim Burgestrand
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -0,0 +1,32 @@
+begin
+  require "bundler/gem_tasks"
+rescue LoadError
+  # Not everybody needs bundler tasks.
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new('yard:doc') do |task|
+    task.options = ['--no-stats']
+  end
+
+  task 'yard:stats' do
+    YARD::CLI::Stats.run('--list-undoc')
+  end
+
+  task :yard => ['yard:doc', 'yard:stats']
+rescue LoadError
+  puts "WARN: YARD not available. You may install documentation dependencies via bundler."
+end
+
+desc "Run an interactive console with Ruhue loaded"
+task :console do
+  exec "irb", "-Ilib", "-rruhue"
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |spec|
+  spec.ruby_opts = %w[-W]
+end
+
+task :default => :spec

data/examples/console.rb

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+require "bundler/setup"
+require "pry"
+require "ruhue"
+
+def prompt(query)
+  print(query)
+  gets.chomp.tap { puts }
+end
+
+puts <<-HELLO
+Hi there!
+
+This is an interpreter to aid experimenting with the Hue. It’s written in Ruby
+and makes API calls to the Hue hub a little more pleasant. You’re expected to
+know Ruby in order to use this.
+
+I’ll first ask you for your Hue hub username. If you do not have one, just make
+one up and I’ll register an application for you on the Hue hub. Use the same
+username every time, or you’ll have a lot of unused applications registered to
+your Hue after a little while.
+
+First off, I’ll see if I can find your Hue. Give me five seconds at most.
+HELLO
+
+hue = Ruhue.discover
+puts
+puts "Hue discovered at #{hue.host}!"
+puts
+
+username = prompt("Now, your username please (10-40 characters, 0-9, a-z, A-Z): ")
+client = Ruhue::Client.new(hue, username)
+
+puts "Hi #{client.username}!"
+
+if client.registered?
+  puts "It appears you’re already registered with the Hub. Play away!"
+elsif client.register("ruhue")
+  puts "A new application has been registered with the Hub as #{client.username}. Play away!"
+end
+
+# Blinks all your lights!
+#
+# num_lights = 3
+# on = true
+# 10_000.times do |i|
+#   sleep(0.04)
+#   light = (i%num_lights) + 1
+#   client.put("/lights/#{light}/state", on: on)
+#   on = ! on if light == num_lights
+# end
+
+binding.pry

data/lib/ruhue.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+require 'httpi'
+require 'nokogiri'
+require 'socket'
+require 'timeout'
+require 'json'
+
+class Ruhue
+  TimeoutError = Class.new(TimeoutError)
+  APIError = Class.new(StandardError)
+
+  class << self
+    # Search for a Hue hub, with configurable timeout.
+    #
+    # This sends out a broadcast packet with UDP, and waits for
+    # a response from the Hue hub.
+    #
+    # @param [Integer] timeout seconds until giving up
+    # @raise [Ruhue::TimeoutError] in case timeout is reached
+    # @return [Hub]
+    def discover(timeout = 5)
+      socket  = UDPSocket.new(Socket::AF_INET)
+      payload = []
+      payload << "M-SEARCH * HTTP/1.1"
+      payload << "HOST: 239.255.255.250:1900"
+      payload << "MAN: ssdp:discover"
+      payload << "MX: 10"
+      payload << "ST: ssdp:all"
+      socket.send(payload.join("\n"), 0, "239.255.255.250", 1900)
+
+      Timeout.timeout(timeout, Ruhue::TimeoutError) do
+        loop do
+          message, (_, _, hue_ip, _) = socket.recvfrom(1024)
+          # TODO: improve this. How do we know it’s a Hue hub?
+          return new(hue_ip) if message =~ /description\.xml/
+        end
+      end
+    end
+  end
+
+  # @example
+  #   hue = Ruhue.new("192.168.0.21")
+  #
+  # @param [String] host address to the Hue hub.
+  def initialize(host)
+    @host = host.to_str
+  end
+
+  # @return [String] hue host
+  attr_reader :host
+
+  # @param [String] path
+  # @return [String] full url
+  def url(path)
+    "http://#{host}/#{path.to_s.sub(/\A\//, "")}"
+  end
+
+  # GET a path of the Hue.
+  #
+  # @param [String] path
+  # @return [Ruhue::Response]
+  def get(path)
+    request(:get, path)
+  end
+
+  # POST a payload to the Hue.
+  #
+  # @param [String] path
+  # @param data json-serializable
+  # @return [Ruhue::Response]
+  def post(path, data)
+    request(:post, path, JSON.dump(data))
+  end
+
+  # PUT a payload to the Hue.
+  #
+  # @param [String] path
+  # @param data json-serializable
+  # @return [Ruhue::Response]
+  def put(path, data)
+    request(:put, path, JSON.dump(data))
+  end
+
+  # DELETE a resource.
+  #
+  # @param [String] path
+  # @return [Ruhue::Response]
+  def delete(path)
+    request(:delete, path)
+  end
+
+  # @return [Nokogiri::XML] Hue device description
+  def description
+    Nokogiri::XML(get("/description.xml").body)
+  end
+
+  protected
+
+  def request(method, path, *args)
+    response = HTTPI.send(method, url(path), *args)
+    Ruhue::Response.new(response)
+  end
+end
+
+require 'ruhue/response'
+require 'ruhue/client'

data/lib/ruhue/client.rb

@@ -0,0 +1,61 @@
+class Ruhue::Client
+  class << self
+    def valid_username?(name)
+      name =~ /\A[0-9a-zA-Z]{10,40}\z/
+    end
+  end
+
+  # Create a Hue client. You’ll need a Hue hub
+  # username for this, created via a POST to the
+  # /api endpoint. See README for more information.
+  #
+  # @param [Ruhue] hue
+  # @param [String] username
+  def initialize(hue, username)
+    unless self.class.valid_username?(username)
+      raise ArgumentError, "invalid username, must be length 10-40, only numbers and letters"
+    end
+
+    @hue = hue
+    @username = username
+  end
+
+  # @return [Ruhue]
+  attr_reader :hue
+
+  # @return [String]
+  attr_reader :username
+
+  # Register a given username with the Hue hub.
+  #
+  # @param [String] device_type used as device name
+  # @return [Ruhue::Client] if successful
+  # @raise [APIError] if failed
+  def register(device_type)
+    response = hue.post("/api", username: username, devicetype: device_type)
+    tap { raise Ruhue::APIError, response.error_messages.join(", ") if response.error? }
+  end
+
+  # @return [Boolean] true if username is registered.
+  def registered?
+    not get("/").error?
+  end
+
+  def get(path)
+    hue.get(url(path))
+  end
+
+  def post(path, data)
+    hue.post(url(path), data)
+  end
+
+  def put(path, data)
+    hue.put(url(path), data)
+  end
+
+  protected
+
+  def url(path)
+    "/api/#{username}/#{path.sub(/\A\//, "")}"
+  end
+end

data/lib/ruhue/response.rb

@@ -0,0 +1,23 @@
+class Ruhue::Response
+  # @param [HTTPI::Response] response
+  def initialize(response)
+    @response = response
+    @data = JSON.load(response.body)
+  end
+
+  # @return [String] body
+  attr_reader :response
+
+  # @return [Array, Hash] data
+  attr_reader :data
+
+  # @return [Boolean] true if the response is an error.
+  def error?
+    data.is_a?(Array) and data.any? { |hash| hash.has_key?("error") }
+  end
+
+  # @return [Array<String>, nil] array of error messages and their address, nil if no error.
+  def error_messages
+    data.map { |hash| "#{hash["error"]["address"]}: #{hash["error"]["description"]}" } if error?
+  end
+end

data/lib/ruhue/version.rb

@@ -0,0 +1,4 @@
+class Ruhue
+  # @see http://semver.org/
+  VERSION = "0.1.0"
+end

data/ruhue.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ruhue/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "ruhue"
+  gem.summary       = %q{API client for interacting with the Philips Hue Hub HTTP API.}
+
+  gem.homepage      = "https://github.com/Burgestrand/ruhue"
+  gem.authors       = ["Kim Burgestrand"]
+  gem.email         = ["kim@burgestrand.se"]
+  gem.license       = "MIT License"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.require_paths = ["lib"]
+
+  gem.version       = Ruhue::VERSION
+
+  gem.add_dependency 'httpi'
+  gem.add_dependency 'nokogiri'
+  gem.add_development_dependency 'rspec'
+end

metadata

@@ -0,0 +1,106 @@
+--- !ruby/object:Gem::Specification
+name: ruhue
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+  prerelease: 
+platform: ruby
+authors:
+- Kim Burgestrand
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-11-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httpi
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- kim@burgestrand.se
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- examples/console.rb
+- lib/ruhue.rb
+- lib/ruhue/client.rb
+- lib/ruhue/response.rb
+- lib/ruhue/version.rb
+- ruhue.gemspec
+homepage: https://github.com/Burgestrand/ruhue
+licenses:
+- MIT License
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: API client for interacting with the Philips Hue Hub HTTP API.
+test_files: []
+has_rdoc: