libusb 0.1.2 → 0.1.3

data/History.txt

@@ -1,3 +1,8 @@
+=== 0.1.3 / 2012-03-15
+
+* Add documentation of descriptor accessors
+* Fix #extra accessor of Configuration, Setting and Endpoint
+
 === 0.1.2 / 2012-03-14
 
 * Mark all blocking functions as blocking in FFI, so that parallel threads are not blocked

data/lib/libusb.rb

@@ -18,7 +18,7 @@ require 'ffi'
 
 
 module LIBUSB
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 
   module Call
     extend FFI::Library
@@ -235,6 +235,7 @@ module LIBUSB
   Call::RequestRecipients.to_h.each{|k,v| const_set(k,v) }
   Call::IsoSyncTypes.to_h.each{|k,v| const_set(k,v) }
 
+  # Base class of libusb errors
   class Error < RuntimeError
   end
   ErrorClassForResult = {}
@@ -592,6 +593,7 @@ module LIBUSB
     private :actual_length, :actual_buffer
   end
 
+  # @private
   class DeviceDescriptor < FFI::Struct
     include Comparable
 
@@ -626,10 +628,61 @@ module LIBUSB
         :extra, :pointer,
         :extra_length, :int
 
-    members.each do |member|
-      define_method(member) do
-        self[member]
-      end
+    # Size of this descriptor (in bytes).
+    def bLength
+      self[:bLength]
+    end
+
+    # Descriptor type (0x02)
+    def bDescriptorType
+      self[:bDescriptorType]
+    end
+
+    # Total length of data returned for this configuration.
+    def wTotalLength
+      self[:wTotalLength]
+    end
+
+    # Number of interfaces supported by this configuration.
+    def bNumInterfaces
+      self[:bNumInterfaces]
+    end
+
+    # Identifier value for this configuration.
+    def bConfigurationValue
+      self[:bConfigurationValue]
+    end
+
+    # Index of string descriptor describing this configuration.
+    def iConfiguration
+      self[:iConfiguration]
+    end
+
+    # Configuration characteristics.
+    #
+    # * Bit 7: Reserved, set to 1. (USB 1.0 Bus Powered)
+    # * Bit 6: Self Powered
+    # * Bit 5: Remote Wakeup
+    # * Bit 4..0: Reserved, set to 0.
+    #
+    # @return [Integer]
+    def bmAttributes
+      self[:bmAttributes]
+    end
+
+    # Maximum power consumption of the USB device from this bus in this configuration when the device is fully opreation.
+    #
+    # @result [Integer] Maximum Power Consumption in 2mA units
+    def maxPower
+      self[:maxPower]
+    end
+
+    # Extra descriptors.
+    #
+    # @return [String]
+    def extra
+      return if self[:extra].null?
+      self[:extra].read_string(self[:extra_length])
     end
 
     def initialize(device, *args)
@@ -663,15 +716,15 @@ module LIBUSB
       "\#<#{self.class} #{attrs.join(' ')}>"
     end
 
-    # Return name of the configuration as String.
+    # Return name of this configuration as String.
     def description
       return @description if defined? @description
       @description = device.try_string_descriptor_ascii(self.iConfiguration)
     end
 
-    # Return all interface decriptions of the configuration as Array of InterfaceDescriptor s.
+    # Return all interface decriptions of the configuration as Array of {Setting}s.
     def settings() self.interfaces.map {|d| d.settings }.flatten end
-    # Return all endpoints of all interfaces of the configuration as Array of EndpointDescriptor s.
+    # Return all endpoints of all interfaces of the configuration as Array of {Endpoint}s.
     def endpoints() self.settings.map {|d| d.endpoints }.flatten end
 
     def <=>(o)
@@ -704,9 +757,9 @@ module LIBUSB
     end
     alias settings alt_settings
 
-    # The Device the Interface belongs to.
+    # The {Device} this Interface belongs to.
     def device() self.configuration.device end
-    # Return all endpoints of all alternative settings as Array of EndpointDescriptor s.
+    # Return all endpoints of all alternative settings as Array of {Endpoint}s.
     def endpoints() self.alt_settings.map {|d| d.endpoints }.flatten end
 
     def <=>(o)
@@ -730,10 +783,57 @@ module LIBUSB
         :extra, :pointer,
         :extra_length, :int
 
-    members.each do |member|
-      define_method(member) do
-        self[member]
-      end
+    # Size of this descriptor (in bytes).
+    def bLength
+      self[:bLength]
+    end
+
+    # Descriptor type (0x04)
+    def bDescriptorType
+      self[:bDescriptorType]
+    end
+
+    # Number of this interface.
+    def bInterfaceNumber
+      self[:bInterfaceNumber]
+    end
+
+    # Value used to select this alternate setting for this interface.
+    def bAlternateSetting
+      self[:bAlternateSetting]
+    end
+
+    # Number of endpoints used by this interface (excluding the control endpoint).
+    def bNumEndpoints
+      self[:bNumEndpoints]
+    end
+
+    # USB-IF class code for this interface.
+    def bInterfaceClass
+      self[:bInterfaceClass]
+    end
+
+    # USB-IF subclass code for this interface, qualified by the {bInterfaceClass} value.
+    def bInterfaceSubClass
+      self[:bInterfaceSubClass]
+    end
+
+    # USB-IF protocol code for this interface, qualified by the {bInterfaceClass} and {bInterfaceSubClass} values.
+    def bInterfaceProtocol
+      self[:bInterfaceProtocol]
+    end
+
+    # Index of string descriptor describing this interface.
+    def iInterface
+      self[:iInterface]
+    end
+
+    # Extra descriptors.
+    #
+    # @return [String]
+    def extra
+      return if self[:extra].null?
+      self[:extra].read_string(self[:extra_length])
     end
 
     def initialize(interface, *args)
@@ -762,15 +862,15 @@ module LIBUSB
       "\#<#{self.class} #{attrs.join(' ')}>"
     end
 
-    # Return name of the Interface as String.
+    # Return name of this interface as String.
     def description
       return @description if defined? @description
       @description = device.try_string_descriptor_ascii(self.iInterface)
     end
 
-    # The Device the InterfaceDescriptor belongs to.
+    # The {Device} this Setting belongs to.
     def device() self.interface.configuration.device end
-    # The ConfigDescriptor the InterfaceDescriptor belongs to.
+    # The {Configuration} this Setting belongs to.
     def configuration() self.interface.configuration end
 
     def <=>(o)
@@ -795,10 +895,82 @@ module LIBUSB
         :extra, :pointer,
         :extra_length, :int
 
-    members.each do |member|
-      define_method(member) do
-        self[member]
-      end
+    # Size of Descriptor in Bytes (7 bytes)
+    def bLength
+      self[:bLength]
+    end
+
+    # Descriptor type (0x05)
+    def bDescriptorType
+      self[:bDescriptorType]
+    end
+
+    # The address of the endpoint described by this descriptor.
+    #
+    # * Bits 0..3: Endpoint Number.
+    # * Bits 4..6: Reserved. Set to Zero
+    # * Bits 7: Direction 0 = Out, 1 = In (Ignored for Control Endpoints)
+    #
+    # @return [Integer]
+    def bEndpointAddress
+      self[:bEndpointAddress]
+    end
+
+    # Attributes which apply to the endpoint when it is configured using the {Configuration#bConfigurationValue}.
+    #
+    # * Bits 0..1: Transfer Type
+    #   * 00 = Control
+    #   * 01 = Isochronous
+    #   * 10 = Bulk
+    #   * 11 = Interrupt
+    # * Bits 2..7: are reserved. If Isochronous endpoint,
+    # * Bits 3..2: Synchronisation Type (Iso Mode)
+    #   * 00 = No Synchonisation
+    #   * 01 = Asynchronous
+    #   * 10 = Adaptive
+    #   * 11 = Synchronous
+    # * Bits 5..4: Usage Type (Iso Mode)
+    #   * 00 = Data Endpoint
+    #   * 01 = Feedback Endpoint
+    #   * 10 = Explicit Feedback Data Endpoint
+    #   * 11 = Reserved
+    #
+    # @return [Integer]
+    def bmAttributes
+      self[:bmAttributes]
+    end
+
+    # Maximum Packet Size this endpoint is capable of sending or receiving
+    def wMaxPacketSize
+      self[:wMaxPacketSize]
+    end
+
+    # Interval for polling endpoint data transfers. Value in frame counts.
+    # Ignored for Bulk & Control Endpoints. Isochronous must equal 1 and field
+    # may range from 1 to 255 for interrupt endpoints.
+    #
+    # The interval is respected by the kernel driver, so user mode processes
+    # using libusb don't need to care about it.
+    def bInterval
+      self[:bInterval]
+    end
+
+    # For audio devices only: the rate at which synchronization feedback is provided.
+    def bRefresh
+      self[:bRefresh]
+    end
+
+    # For audio devices only: the address if the synch endpoint.
+    def bSynchAddress
+      self[:bSynchAddress]
+    end
+
+    # Extra descriptors.
+    #
+    # @return [String]
+    def extra
+      return if self[:extra].null?
+      self[:extra].read_string(self[:extra_length])
     end
 
     def initialize(setting, *args)
@@ -824,11 +996,11 @@ module LIBUSB
       "\#<#{self.class} #{num} #{inout} #{type.join(" ")}>"
     end
 
-    # The Device the EndpointDescriptor belongs to.
+    # The {Device} this Endpoint belongs to.
     def device() self.setting.interface.configuration.device end
-    # The ConfigDescriptor the EndpointDescriptor belongs to.
+    # The {Configuration} this Endpoint belongs to.
     def configuration() self.setting.interface.configuration end
-    # The Interface the EndpointDescriptor belongs to.
+    # The {Interface} this Endpoint belongs to.
     def interface() self.setting.interface end
 
     def <=>(o)
@@ -1072,13 +1244,85 @@ module LIBUSB
       config
     end
 
-    # allow access to Descriptor members on Device
-    DeviceDescriptor.members.each do |member|
-      define_method(member) do
-        @pDevDesc[member]
-      end
+    # Size of the Descriptor in Bytes (18 bytes)
+    def bLength
+      @pDevDesc[:bLength]
     end
 
+    # Device Descriptor (0x01)
+    def bDescriptorType
+      @pDevDesc[:bDescriptorType]
+    end
+
+    # USB specification release number which device complies too
+    #
+    # @return [Integer] in binary-coded decimal
+    def bcdUSB
+      @pDevDesc[:bcdUSB]
+    end
+
+    # USB-IF class code for the device (Assigned by USB Org)
+    #
+    # * If equal to 0x00, each interface specifies it's own class code
+    # * If equal to 0xFF, the class code is vendor specified
+    # * Otherwise field is valid Class Code
+    def bDeviceClass
+      @pDevDesc[:bDeviceClass]
+    end
+
+    # USB-IF subclass code for the device, qualified by the {bDeviceClass}
+    # value (Assigned by USB Org)
+    def bDeviceSubClass
+      @pDevDesc[:bDeviceSubClass]
+    end
+
+    # USB-IF protocol code for the device, qualified by the {bDeviceClass}
+    # and {bDeviceSubClass} values (Assigned by USB Org)
+    def bDeviceProtocol
+      @pDevDesc[:bDeviceProtocol]
+    end
+
+    # Maximum Packet Size for Endpoint 0. Valid Sizes are 8, 16, 32, 64
+    def bMaxPacketSize0
+      @pDevDesc[:bMaxPacketSize0]
+    end
+
+    # USB-IF vendor ID (Assigned by USB Org)
+    def idVendor
+      @pDevDesc[:idVendor]
+    end
+
+    # USB-IF product ID (Assigned by Manufacturer)
+    def idProduct
+      @pDevDesc[:idProduct]
+    end
+
+    # Device release number in binary-coded decimal.
+    def bcdDevice
+      @pDevDesc[:bcdDevice]
+    end
+
+    # Index of string descriptor describing manufacturer.
+    def iManufacturer
+      @pDevDesc[:iManufacturer]
+    end
+
+    # Index of string descriptor describing product.
+    def iProduct
+      @pDevDesc[:iProduct]
+    end
+
+    # Index of string descriptor containing device serial number.
+    def iSerialNumber
+      @pDevDesc[:iSerialNumber]
+    end
+
+    # Number of Possible Configurations
+    def bNumConfigurations
+      @pDevDesc[:bNumConfigurations]
+    end
+
+
     def inspect
       attrs = []
       attrs << "#{self.bus_number}/#{self.device_address}"
@@ -1147,13 +1391,13 @@ module LIBUSB
       configs
     end
 
-    # Return all interfaces of the device.
+    # Return all interfaces of this device.
     # @return [Array<Interface>]
     def interfaces() self.configurations.map {|d| d.interfaces }.flatten end
-    # Return all interface decriptions of the device.
+    # Return all interface decriptions of this device.
     # @return [Array<Setting>]
     def settings() self.interfaces.map {|d| d.settings }.flatten end
-    # Return all endpoints of all interfaces of the device.
+    # Return all endpoints of all interfaces of this device.
     # @return [Array<Endpoint>]
     def endpoints() self.settings.map {|d| d.endpoints }.flatten end
 

data/test/test_libusb_descriptors.rb

@@ -29,10 +29,36 @@ class TestLibusbDescriptors < Test::Unit::TestCase
   def test_descriptors
     usb.devices.each do |dev|
       assert_match(/Device/, dev.inspect, "Device#inspect should work")
+
+      assert_kind_of Integer, dev.bLength
+      assert_equal 1, dev.bDescriptorType
+      assert_kind_of Integer, dev.bcdUSB
+      assert_kind_of Integer, dev.bDeviceClass
+      assert_kind_of Integer, dev.bDeviceSubClass
+      assert_kind_of Integer, dev.bDeviceProtocol
+      assert_kind_of Integer, dev.bMaxPacketSize0
+      assert_kind_of Integer, dev.idVendor
+      assert_kind_of Integer, dev.idProduct
+      assert_kind_of Integer, dev.bcdDevice
+      assert_kind_of Integer, dev.iManufacturer
+      assert_kind_of Integer, dev.iProduct
+      assert_kind_of Integer, dev.iSerialNumber
+      assert_kind_of Integer, dev.bNumConfigurations
+
       dev.configurations.each do |config_desc|
         assert_match(/Configuration/, config_desc.inspect, "ConfigDescriptor#inspect should work")
         assert dev.configurations.include?(config_desc), "Device#configurations should include this one"
 
+        assert_kind_of Integer, config_desc.bLength
+        assert_equal 2, config_desc.bDescriptorType
+        assert_kind_of Integer, config_desc.wTotalLength
+        assert_equal config_desc.interfaces.length, config_desc.bNumInterfaces
+        assert_kind_of Integer, config_desc.bConfigurationValue
+        assert_kind_of Integer, config_desc.iConfiguration
+        assert_kind_of Integer, config_desc.bmAttributes
+        assert_kind_of Integer, config_desc.maxPower
+        assert_kind_of String, config_desc.extra if config_desc.extra
+
         config_desc.interfaces.each do |interface|
           assert_match(/Interface/, interface.inspect, "Interface#inspect should work")
 
@@ -46,6 +72,17 @@ class TestLibusbDescriptors < Test::Unit::TestCase
             assert config_desc.settings.include?(if_desc), "ConfigDescriptor#settings should include this one"
             assert interface.alt_settings.include?(if_desc), "Inteerface#alt_settings should include this one"
 
+            assert_kind_of Integer, if_desc.bLength
+            assert_equal 4, if_desc.bDescriptorType
+            assert_kind_of Integer, if_desc.bInterfaceNumber
+            assert_kind_of Integer, if_desc.bAlternateSetting
+            assert_equal if_desc.endpoints.length, if_desc.bNumEndpoints
+            assert_kind_of Integer, if_desc.bInterfaceClass
+            assert_kind_of Integer, if_desc.bInterfaceSubClass
+            assert_kind_of Integer, if_desc.bInterfaceProtocol
+            assert_kind_of Integer, if_desc.iInterface
+            assert_kind_of String, if_desc.extra if if_desc.extra
+
             if_desc.endpoints.each do |ep|
               assert_match(/Endpoint/, ep.inspect, "EndpointDescriptor#inspect should work")
 
@@ -59,7 +96,15 @@ class TestLibusbDescriptors < Test::Unit::TestCase
               assert_equal config_desc, ep.configuration, "backref should be correct"
               assert_equal dev, ep.device, "backref should be correct"
 
+              assert_kind_of Integer, ep.bLength
+              assert_equal 5, ep.bDescriptorType
+              assert_kind_of Integer, ep.bEndpointAddress
+              assert_kind_of Integer, ep.bmAttributes
               assert_operator 0, :<, ep.wMaxPacketSize, "packet size should be > 0"
+              assert_kind_of Integer, ep.bInterval
+              assert_kind_of Integer, ep.bRefresh
+              assert_kind_of Integer, ep.bSynchAddress
+              assert_kind_of String, ep.extra if ep.extra
             end
           end
         end

data/test/test_libusb_keyboard.rb

@@ -0,0 +1,50 @@
+# This test requires a connected, but not mounted mass storage device with
+# read/write access allowed. Based on the following specifications:
+#   http://www.usb.org/developers/devclass_docs/usbmassbulk_10.pdf
+#   http://en.wikipedia.org/wiki/SCSI_command
+#
+
+require "test/unit"
+require "libusb"
+
+class TestLibusbKeyboard < Test::Unit::TestCase
+  include LIBUSB
+
+  attr_accessor :usb
+  attr_accessor :device
+  attr_accessor :dev
+  attr_accessor :endpoint_in
+  attr_accessor :endpoint_out
+
+  def setup
+    @usb = Context.new
+    @usb.debug = 3
+
+    @device = usb.devices( :bDeviceClass=>CLASS_HID, :bDeviceProtocol=>1 ).first
+    abort "no keyboard device found" unless @device
+
+    @endpoint_in = @device.endpoints.find{|ep| ep.bEndpointAddress&ENDPOINT_IN != 0 }.bEndpointAddress
+    @endpoint_out = @device.endpoints.find{|ep| ep.bEndpointAddress&ENDPOINT_IN == 0 }.bEndpointAddress
+
+    @dev = @device.open
+
+    if RUBY_PLATFORM=~/linux/i && dev.kernel_driver_active?(0)
+      dev.detach_kernel_driver(0)
+    end
+    dev.claim_interface(0)
+
+    # clear any pending data
+    dev.clear_halt(endpoint_in)
+  end
+
+  def teardown
+    dev.release_interface(0) if dev
+    dev.close if dev
+  end
+
+  def test_read
+    data_length = 8
+    recv = dev.interrupt_transfer(:endpoint=>endpoint_in, :dataIn=>data_length)
+    p recv
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libusb
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-03-14 00:00:00.000000000 Z
+date: 2012-03-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
-  requirement: &7425600 !ruby/object:Gem::Requirement
+  requirement: &11238960 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '1.0'
   type: :runtime
   prerelease: false
-  version_requirements: *7425600
+  version_requirements: *11238960
 - !ruby/object:Gem::Dependency
   name: rake-compiler
-  requirement: &7424760 !ruby/object:Gem::Requirement
+  requirement: &11254720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,29 +32,18 @@ dependencies:
         version: '0.6'
   type: :development
   prerelease: false
-  version_requirements: *7424760
-- !ruby/object:Gem::Dependency
-  name: rdoc
-  requirement: &7423680 !ruby/object:Gem::Requirement
-    none: false
-    requirements:
-    - - ~>
-      - !ruby/object:Gem::Version
-        version: '3.10'
-  type: :development
-  prerelease: false
-  version_requirements: *7423680
+  version_requirements: *11254720
 - !ruby/object:Gem::Dependency
   name: hoe
-  requirement: &7422380 !ruby/object:Gem::Requirement
+  requirement: &11254160 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '2.16'
+        version: '2.12'
   type: :development
   prerelease: false
-  version_requirements: *7422380
+  version_requirements: *11254160
 description: LIBUSB is a Ruby binding that gives Ruby programmers access to all functionality
   of libusb, version 1.0
 email:
@@ -82,6 +71,7 @@ files:
 - test/test_libusb_iso_transfer.rb
 - test/test_libusb_mass_storage.rb
 - test/test_libusb_mass_storage2.rb
+- test/test_libusb_keyboard.rb
 homepage: http://github.com/larskanis/libusb
 licenses: []
 post_install_message: 
@@ -105,15 +95,16 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: libusb
-rubygems_version: 1.8.17
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Access USB devices from Ruby via libusb-1.0
 test_files:
-- test/test_libusb_compat.rb
+- test/test_libusb_compat_mass_storage.rb
+- test/test_libusb_gc.rb
 - test/test_libusb_iso_transfer.rb
-- test/test_libusb_mass_storage2.rb
 - test/test_libusb_descriptors.rb
+- test/test_libusb_compat.rb
+- test/test_libusb_keyboard.rb
+- test/test_libusb_mass_storage2.rb
 - test/test_libusb_mass_storage.rb
-- test/test_libusb_compat_mass_storage.rb
-- test/test_libusb_gc.rb