ffi-hdhomerun 0.3.100b91730e74 → 0.4

data/README.md

@@ -0,0 +1,87 @@
+ffi-hdhomerun
+=============
+http://bitbucket.org/dmlary/ffi-hdhomerun
+
+Description
+-----------
+Ruby-FFI bindings and wrappers for libhdhomerun.
+
+Features
+--------
+Allows the user to capture video from an HDHomeRun device within Ruby.
+
+What's missing
+--------------
+*  Channel scan
+*  Documentation
+
+Usage
+-----
+    require 'ffi-hdhomerun'
+
+    # Dump the list of tuners on the network
+    HDHomeRun.discover.each do |hash|
+      puts "hdhomerun device %s found at %s" % [ hash[:id], hash[:ip_addr] ]
+    end
+
+    # Allocate a tuner
+    tuner = HDHomeRun::Tuner.new(:id => 'FFFFFFFF', :tuner => 0)
+
+    # Set the channel and optionally the program
+    tuner.channel = 20
+    tuner.program = 3
+
+    # Capture some data
+    File.open("capture.ts", "w") do |file|
+      puts "Capturing (^C to stop):"
+      tuner.capture do |buf|
+        file.write(buf)
+        STDOUT.write(buf.size > 0 ? "." : "?")
+        STDOUT.flush
+      end
+    end
+
+Requirements
+------------
+*  libhdhomerun >= 1.0
+*  ffi >= 1.0
+
+FFI_HDHOMERUN_OLD_DEVICE_STRUCT
+-------------------------------
+libhdhomerun made a change to the device structure used for discovery
+sometime between version 20100121 and 20110323.  They added a new field
+caller tuner_count, but the filename of the hdhomerun library was not
+incremented in ubuntu.  As a result, on older releases such as Lucid, users
+of this gem will have to set FFI_HDHOMERUN_OLD_DEVICE_STRUCT in their
+environment to get proper results from the HDHomeRun.discover() method.
+This environment variable only needs to be set if you're planning on
+using the discovery method.
+
+Copyright
+---------
+Copyright (c) 2011,2012 David M. Lary 
+All rights reserved.
+
+License
+-------
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+*  Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+*  Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+*  The name of the author may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
+THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/Rakefile

@@ -1 +1,5 @@
 require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+desc "Run all RSpec tests"
+RSpec::Core::RakeTask.new(:spec)

data/ffi-hdhomerun.gemspec

@@ -4,8 +4,7 @@ require "ffi-hdhomerun"
 
 Gem::Specification.new do |s|
   s.name        = "ffi-hdhomerun"
-  s.version     = "%s.%s" % [ HDHomeRun::VERSION, 
-                            `hg id -i`.chomp.sub("+", "m") ]
+  s.version     = "%s" % [ HDHomeRun::VERSION ]
   s.authors     = ["David M. Lary"]
   s.email       = ["dmlary@gmail.com"]
   s.homepage    = "http://bitbucket.org/dmlary/ffi-hdhomerun"

data/lib/ffi-hdhomerun.rb

@@ -1,10 +1,166 @@
 require 'ffi/hdhomerun'
+require 'pry'
 
 #
 # Documentation can be found under HDHomeRun::Tuner
 #
 module HDHomeRun
-  VERSION = "0.3"
+  VERSION = "0.4"
+  ERROR_STRING_UNKNOWN_VARIABLE = "ERROR: unknown getset variable"
+  MAX_TUNERS = 8
+
+  class ConnectionError < Exception; end
+  class UnknownVariableError < Exception; end
+
+  #
+  # Discover tuners on the network.
+  #
+  # Warning: This function will return invalid data 
+  #
+  # Returns an array of hashes with the following fields:
+  #   :id -- device id (string)
+  #   :type -- device type (int)
+  #   :ip_addr -- ip address (IPAddr)
+  #   :tuner_count -- number of tuners on the device (int)
+  #
+  def self.discover
+    results_ptr = FFI::MemoryPointer.new(FFI::HDHomeRun::Device, 64)
+    count = FFI::HDHomeRun::discover_find_devices_custom(
+              FFI::HDHomeRun::DEVICE_ID_WILDCARD,
+              FFI::HDHomeRun::DEVICE_TYPE_TUNER,
+              FFI::HDHomeRun::DEVICE_ID_WILDCARD,
+              results_ptr,
+              64)
+    raise "error sending discover request" if count < 0
+
+    # Loop through the results and construct an array of hashes
+    # as our output.
+    (0..count-1).map do |i|
+
+      # construct our hash
+      p = FFI::HDHomeRun::Device.new(results_ptr[i])
+      out = { :id => "%08X" % p.device_id, 
+              :type => p.device_type,
+              :ip_addr => p.ip_addr }
+
+      # Some versions of the library don't support tuner_count
+      out.merge!({ :tuner_count => p.tuner_count }) if 
+        p.respond_to? :tuner_count
+
+      out
+    end
+  end
+
+  # HDHomeRun device wrapper.
+  class Device
+    include FFI::HDHomeRun
+
+    attr_reader :id
+
+    # Initialize new hdhomerun device
+    #
+    # Arguments:
+    #   [:id] HDHomeRun id (default "FFFFFFFF")
+    #
+    # Create a device instance for any HDHomeRun device on the network:
+    #   device = HDHomeRun::Device.new
+    #
+    # Create a device instance for a specific HDHomeRun device on the network:
+    #   device = HDHomeRun::Device.new "FEEDFACE"
+    #
+    def initialize(p={})
+      p = {:id => p} unless p.is_a? Hash
+      p[:id] ||= "FFFFFFFF"
+      p[:id] = "%08X" % p[:id] if p[:id].is_a? Fixnum
+
+      @hd = create_from_str(p[:id].to_s, nil)
+      raise ArgumentError, "Invalid device id: %s" % p[:id] if @hd.null?
+      @id = get_device_id_requested(@hd)
+      raise ArgumentError, "Invalid device id: %08X" % id \
+        unless validate_device_id(@id)
+      raise ConnectionError, "Unable to connect to device" \
+        unless get_model_str(@hd)
+    end
+
+    #
+    # Get a device variable; equivalent to:
+    #   hdhomerun_config <id> get <key>
+    #
+    def get(key)
+      value = FFI::MemoryPointer.new(:pointer, 1)
+      error = FFI::MemoryPointer.new(:pointer, 1)
+
+      if get_var(@hd, key, value, error) < 0
+        raise ConnectionError, 
+          "communication error sending request to hdhomerun device"
+      end
+      value = value.read_pointer
+      error = error.read_pointer
+
+      # Return the value if we didn't get an error.
+      return value.read_string if error.null?
+
+      # Throw a useful exception if this get was for an unknown variable.
+      error = error.read_string
+      raise UnknownVariableError, "unknown variable '%s'" % key if
+        error == ERROR_STRING_UNKNOWN_VARIABLE
+ 
+      # otherwise, it's a generic runtime error.
+      raise RuntimeError, error
+    end
+
+    #
+    # Set a device variable; equivalent to:
+    #   hdhomerun_config <id> set <key> <value>
+    #
+    def set(key, value)
+      error = FFI::MemoryPointer.new(:pointer, 1)
+
+      if set_var(@hd, key, value.to_s, nil, error) < 0
+        raise ConnectionError, 
+          "communication error sending request to hdhomerun device"
+      end
+      error = error.read_pointer
+
+      return true if error.null?
+
+      # Throw a useful exception if this get was for an unknown variable.
+      error = error.read_string
+      raise UnknownVariableError, "unknown variable '%s'" % key if
+        error == ERROR_STRING_UNKNOWN_VARIABLE
+ 
+      # otherwise, it's a generic runtime error.
+      raise RuntimeError, error
+    end
+
+    # Get the number of tuners on this device.
+    def tuner_count
+      @tuner_count ||= begin
+        MAX_TUNERS.times do |tuner|
+          begin
+            get "/tuner%d/debug" % tuner
+          rescue UnknownVariableError
+            break tuner
+          end
+        end or raise RuntimeError, "Unable to detect tuner count"
+      end
+    end
+
+    # Get an array of tuners for this device.
+    def tuners
+      @tuners ||= tuner_count.times.map do |tuner|
+        Tuner.new(:id => @id, :tuner => tuner)
+      end
+    end
+
+    def id
+      "%08X" % @id
+    end
+
+    def to_s
+      "<%s:0x%08x @id=%08X>" % [ self.class, object_id, @id ]
+    end
+  end
 
   # HDHomeRun tuner wrapper.
   #
@@ -33,10 +189,11 @@ module HDHomeRun
   #     end
   #   end
   #   
-  class Tuner
+  class Tuner < Device
+    extend Forwardable
     include FFI::HDHomeRun
 
-    attr_reader :hd, :id, :tuner
+    attr_reader :tuner
 
     # Initialize new hdhomerun tuner
     #
@@ -46,32 +203,20 @@ module HDHomeRun
     #
     # Create a tuner instance for the first tuner on any HDHomeRun box
     # on the network:
-    #   tuner => HDHomeRun::Tuner.new(0)
+    #   tuner => HDHomeRun::Tuner.new
     #
     # Create a tuner instance for the second tuner on the HDHomeRun box
     # with id FE92EBD0
     #   tuner = HDHomeRun::Tuner.new(:id => "FE92EBD0", :tuner => 1)
     #
     def initialize(p={})
-      p = {:id => p} unless p.is_a? Hash
-      p[:id] ||= "FFFFFFFF"
-      p[:tuner] ||= 0
-      p[:tuner] = "/tuner%d" % p[:tuner] if p[:tuner].is_a? Fixnum
-
-      @hd = create_from_str(p[:id].to_s, nil)
-      raise ArgumentError, "Invalid device id: #{id}" if @hd.null?
-      @id = get_device_id_requested(@hd)
+      super(p)
+      @tuner = p[:tuner] || 0
+      @tuner = "/tuner%d" % @tuner if @tuner.is_a? Fixnum
 
-      @tuner = p[:tuner]
-      @tuner = "/tuner%d" % @tuner unless @tuner.is_a? String
       if set_tuner_from_str(@hd, @tuner) <= 0
         raise RuntimeError, "invalid tuner: %s" % @tuner
       end
-
-      raise ArgumentError, "Invalid device id: %08X" % id \
-        unless validate_device_id(@id)
-      raise RuntimeError, "Unable to connect to device" \
-        unless get_model_str(@hd)
     end
 
     # Dynamically define the following getter and setter methods
@@ -86,7 +231,7 @@ module HDHomeRun
     end
     
     # Dynamically define these as simple getter methods
-    %w{status streaminfo}.each do |name|
+    %w{status streaminfo debug}.each do |name|
       define_method name do
         get_tuner(name)
       end
@@ -147,35 +292,12 @@ module HDHomeRun
       end
     end
 
-    private
-
-    def get(key)
-      value = FFI::MemoryPointer.new(:pointer, 1)
-      error = FFI::MemoryPointer.new(:pointer, 1)
-
-      if get_var(@hd, key, value, error) < 0
-        raise RuntimeError, 
-          "communication error sending request to hdhomerun device"
-      end
-      value = value.read_pointer
-      error = error.read_pointer
-
-      raise RuntimeError, error.read_string unless error.null?
-      value.read_string
+    def to_s
+      "<%s:0x%08x @id=%08X, @tuner=%s>" % 
+        [ self.class, object_id, @id, @tuner ]
     end
 
-    def set(key, value)
-      error = FFI::MemoryPointer.new(:pointer, 1)
-
-      if set_var(@hd, key, value.to_s, nil, error) < 0
-        raise RuntimeError, 
-          "communication error sending request to hdhomerun device"
-      end
-      error = error.read_pointer
-
-      raise RuntimeError, error.read_string unless error.null?
-      true
-    end
+    private
 
     def get_tuner(key)
       get("%s/%s" % [@tuner, key.to_s])

data/lib/ffi/hdhomerun.rb

@@ -1,4 +1,5 @@
 require 'ffi'
+require 'ipaddr'
 
 module FFI # :nodoc:
   module HDHomeRun
@@ -6,6 +7,8 @@ module FFI # :nodoc:
     ffi_lib "libhdhomerun.so.1"
 
     VIDEO_DATA_BUFFER_SIZE_1S = (20000000 / 8)
+    DEVICE_TYPE_TUNER  = 0x00000001
+    DEVICE_ID_WILDCARD = 0xFFFFFFFF
 
     attach_function :create_from_str, 
                       :hdhomerun_device_create_from_str, 
@@ -40,6 +43,10 @@ module FFI # :nodoc:
     attach_function :get_video_stats,
                       :hdhomerun_device_get_video_stats, 
                       [:pointer, :pointer], :void
+    attach_function :discover_find_devices_custom,
+                      :hdhomerun_discover_find_devices_custom,
+                      [ :uint32, :uint32, :uint32, :pointer, :int ],
+                      :int
 
     # HDHomeRun capture statistics for a given tuner
     #
@@ -63,5 +70,44 @@ module FFI # :nodoc:
         end
       end
     end
+
+    # Discover device structure
+    #
+    # Silicon dust changed this structure at some point between
+    # revision 20100121 and 20110323, but the version number in the
+    # library filename was not changed by package maintainers for
+    # ubuntu.  As a result, there's no simple way to determine which
+    # structure we should use.  To work around this, the gem will
+    # assume the library has the newer structure unless the
+    # FFI_HDHOMERUN_OLD_DEVICE_STRUCT environment variable has been
+    # set.
+    #
+    class Device < FFI::Struct
+      if ENV['FFI_HDHOMERUN_OLD_DEVICE_STRUCT']
+        layout :ip_addr, :uint32,
+               :device_type, :uint32,
+               :device_id, :uint32
+      else
+        # Newer layout has support for :tuner_count
+        layout :ip_addr, :uint32,
+               :device_type, :uint32,
+               :device_id, :uint32,
+               :tuner_count, :uint8
+
+        define_method :tuner_count do
+          send(:[], :tuner_count)
+        end
+      end
+
+      %w{device_type device_id}.each do |name|
+        define_method name do
+          send(:[], name.to_sym)
+        end
+      end
+
+      def ip_addr
+        IPAddr.new(self[:ip_addr], Socket::AF_INET)
+      end
+    end
   end
 end

data/spec/hdhomerun_spec.rb

@@ -0,0 +1,104 @@
+require 'ffi-hdhomerun'
+require 'timeout'
+
+describe HDHomeRun do
+  it "can find hdhomerun devices on the network" do
+    devices = HDHomeRun.discover
+    devices.empty?.should eq(false)
+  end
+end
+
+describe HDHomeRun::Device do
+  before :each do
+    @device = HDHomeRun::Device.new
+  end
+
+  it "can connect to any device" do
+    HDHomeRun::Device.new
+  end
+
+  it "throws exception on invalid name" do
+    lambda { HDHomeRun::Device.new("WOOF WOOF, I'm a puppy!") } \
+      .should raise_error(ArgumentError)
+  end
+
+  it "throws exception on unreachable device" do
+    lambda { HDHomeRun::Device.new("FEEDFACE") } \
+      .should raise_error(HDHomeRun::ConnectionError)
+  end
+
+  it "can get device variables" do
+    str = @device.get("/sys/debug")
+    str.nil?.should eq(false)
+  end
+
+  it "can determine the correct number of tuners" do
+    count1 = @device.tuner_count
+    count2 = @device.get("/sys/debug").split(/\n/) \
+      .count { |l| l =~ /^t\d+: / }
+    count1.should eq(count2)
+  end
+
+  it "can return a list of tuners" do
+    tuners = @device.tuners
+    tuners.empty?.should eq(false)
+    tuners.each do |t|
+      t.channel.should eq(@device.get("%s/channel" % t.tuner))
+    end
+  end
+end
+
+describe HDHomeRun::Tuner do
+  before :all do
+    @tuner = HDHomeRun.discover.map do |device| 
+        HDHomeRun::Device.new(device[:id]).tuners
+      end.flatten.find do |tuner|
+        tuner.target == "none"
+      end
+    @tuner.nil?.should eq(false)
+
+    @device = HDHomeRun::Device.new(@tuner.id)
+
+    # Pull the test channel from the environment
+    @channel = ENV['FFI_HDHOMERUN_TEST_CHANNEL']
+
+    # Failing that, do a channel scan to find a channel with strong signal.
+    @channel ||= (2..69).to_a.find do |channel|
+      @tuner.channel = channel
+      sleep 0.75
+      @tuner.status !~ / lock=none /
+    end
+
+    fail "Unable to find good channel for tests.  " + 
+         "Please set the environment variable FFI_HDHOMERUN_TEST_CHANNEL " +
+         "to a channel that comes in clearly on your tuner" unless @channel
+  end
+
+  it "can set and get the channel" do
+    @tuner.channel = "none"
+    @tuner.channel.should eq("none")
+    @device.get("%s/channel" % @tuner.tuner).should eq("none")
+
+    channel = "auto:%d" % @channel
+    @tuner.channel = channel
+    @tuner.channel.should eq(channel)
+    @device.get("%s/channel" % @tuner.tuner).should eq(channel)
+  end
+
+  it "can capture from the tuner" do
+    @tuner.channel = "auto:%d" % @channel
+
+    bytes = 0
+    calls = 25
+    Timeout::timeout(2) do
+      @tuner.capture do |buf|
+        bytes += buf.size
+        calls -= 1
+        break if calls == 0
+      end
+    end
+
+    bytes.size.should be > 0
+  end
+end
+

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: ffi-hdhomerun
 version: !ruby/object:Gem::Version
-  version: 0.3.100b91730e74
-  prerelease: 7
+  version: '0.4'
+  prerelease: 
 platform: ruby
 authors:
 - David M. Lary
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-03 00:00:00.000000000Z
+date: 2012-07-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
-  requirement: &12302400 !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,7 +21,12 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *12302400
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Ruby FFI bindings for libhdhomerun
 email:
 - dmlary@gmail.com
@@ -31,11 +36,12 @@ extra_rdoc_files: []
 files:
 - .hgignore
 - Gemfile
-- README.txt
+- README.md
 - Rakefile
 - ffi-hdhomerun.gemspec
 - lib/ffi-hdhomerun.rb
 - lib/ffi/hdhomerun.rb
+- spec/hdhomerun_spec.rb
 homepage: http://bitbucket.org/dmlary/ffi-hdhomerun
 licenses: []
 post_install_message: 
@@ -51,13 +57,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
-  - - ! '>'
+  - - ! '>='
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
 rubyforge_project: ffi-hdhomerun
-rubygems_version: 1.8.10
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Ruby FFI bindings for libhdhomerun
-test_files: []
+test_files:
+- spec/hdhomerun_spec.rb

data/README.txt

@@ -1,62 +0,0 @@
-= ffi-hdhomerun
-http://bitbucket.org/dmlary/ffi-hdhomerun
-
-== Description
-Ruby-FFI bindings and wrappers for libhdhomerun.
-
-== Features
-Allows the user to capture video from an HDHomeRun device within Ruby.
-
-== What's missing
-* Discovery
-* Documentation
-
-== Usage
-  require 'ffi-hdhomerun'
-
-  # Allocate a tuner
-  tuner = HDHomeRun::Tuner.new(:id => 'FFFFFFFF', :tuner => 0)
-
-  # Set the channel and optionally the program
-  tuner.channel = 20
-  tuner.program = 3
-
-  # Capture some data
-  File.open("capture.ts", "w") do |file|
-    puts "Capturing (^C to stop):"
-    tuner.capture do |buf|
-      file.write(buf)
-      STDOUT.write(buf.size > 0 ? "." : "?")
-      STDOUT.flush
-    end
-  end
-
-== Requirements
-- libhdhomerun >= 1.0
-- ffi >= 1.0
-
-== Copyright
-Copyright (c) 2011, David M. Lary 
-All rights reserved.
-
-== License
-  Redistribution and use in source and binary forms, with or without
-  modification, are permitted provided that the following conditions are met:
-    * Redistributions of source code must retain the above copyright
-      notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-      notice, this list of conditions and the following disclaimer in the
-      documentation and/or other materials provided with the distribution.
-    * The name of the author may not be used to endorse or promote products
-      derived from this software without specific prior written permission.
-  
-  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
-  ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
-  INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
-  (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
-  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
-  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
-  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.