libusb 0.2.2 → 0.3.0

data/lib/libusb/endpoint.rb

@@ -47,18 +47,31 @@ module LIBUSB
     # * Bits 7: Direction 0 = Out, 1 = In (Ignored for Control Endpoints)
     #
     # @return [Integer]
+    #
+    # @see #endpoint_number
+    # @see #direction
     def bEndpointAddress
       self[:bEndpointAddress]
     end
 
+    # @return [Integer]
+    def endpoint_number
+      bEndpointAddress & 0b1111
+    end
+
+    # @return [Symbol]  Either +:in+ or +:out+
+    def direction
+      bEndpointAddress & ENDPOINT_IN == 0 ? :out : :in
+    end
+
     # Attributes which apply to the endpoint when it is configured using the {Configuration#bConfigurationValue}.
     #
-    # * Bits 0..1: Transfer Type
+    # * Bits 1..0: Transfer Type
     #   * 00 = Control
     #   * 01 = Isochronous
     #   * 10 = Bulk
     #   * 11 = Interrupt
-    # * Bits 2..7: are reserved. If Isochronous endpoint,
+    # * Bits 7..2: are reserved. If Isochronous endpoint,
     # * Bits 3..2: Synchronisation Type (Iso Mode)
     #   * 00 = No Synchonisation
     #   * 01 = Asynchronous
@@ -71,10 +84,34 @@ module LIBUSB
     #   * 11 = Reserved
     #
     # @return [Integer]
+    #
+    # @see #transfer_type
+    # @see #usage_type
+    # @see #synchronization_type
     def bmAttributes
       self[:bmAttributes]
     end
 
+    TransferTypes = [:control, :isochronous, :bulk, :interrupt]
+    # @return [Symbol]  One of {TransferTypes}
+    def transfer_type
+      TransferTypes[bmAttributes & 0b11]
+    end
+
+    SynchronizationTypes = [:no_synchronization, :asynchronous, :adaptive, :synchronous]
+    # @return [Symbol]  One of {SynchronizationTypes}
+    def synchronization_type
+      return unless transfer_type == :isochronous
+      SynchronizationTypes[(bmAttributes & 0b1100) >> 2]
+    end
+
+    UsageTypes = [:data, :feedback, :implicit_feedback, :unknown]
+    # @return [Symbol]  One of {UsageTypes}
+    def usage_type
+      return unless transfer_type == :isochronous
+      UsageTypes[(bmAttributes & 0b110000) >> 4]
+    end
+
     # Maximum Packet Size this endpoint is capable of sending or receiving
     def wMaxPacketSize
       self[:wMaxPacketSize]
@@ -117,18 +154,8 @@ module LIBUSB
     attr_reader :setting
 
     def inspect
-      endpoint_address = self.bEndpointAddress
-      num = endpoint_address & 0b00001111
-      inout = (endpoint_address & 0b10000000) == 0 ? "OUT" : "IN "
-      bits = self.bmAttributes
-      transfer_type = %w[Control Isochronous Bulk Interrupt][0b11 & bits]
-      type = [transfer_type]
-      if transfer_type == 'Isochronous'
-        synchronization_type = %w[NoSynchronization Asynchronous Adaptive Synchronous][(0b1100 & bits) >> 2]
-        usage_type = %w[Data Feedback ImplicitFeedback ?][(0b110000 & bits) >> 4]
-        type << synchronization_type << usage_type
-      end
-      "\#<#{self.class} #{num} #{inout} #{type.join(" ")}>"
+      type = [transfer_type, synchronization_type, usage_type].compact
+      "\#<#{self.class} #{endpoint_number} #{direction} #{type.join(" ")}>"
     end
 
     # The {Device} this Endpoint belongs to.

data/lib/libusb/eventmachine.rb

@@ -0,0 +1,183 @@
+# This file is part of Libusb for Ruby.
+#
+# Libusb for Ruby is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Libusb for Ruby is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
+
+require 'libusb'
+require 'eventmachine'
+
+module LIBUSB
+class Context
+  # Register libusb's file descriptors and timeouts to EventMachine.
+  #
+  # @example
+  #   require 'libusb/eventmachine'
+  #   context = LIBUSB::Context.new
+  #   EventMachine.run do
+  #     context.eventmachine_register
+  #   end
+  #
+  # @see
+  #   DevHandle#eventmachine_bulk_transfer
+  #   DevHandle#eventmachine_control_transfer
+  #   DevHandle#eventmachine_interrupt_transfer
+  def eventmachine_register
+    @eventmachine_attached_fds = {}
+    @eventmachine_timer = nil
+
+    pollfds = self.pollfds
+    if pollfds
+      pollfds.each do |pollfd|
+        eventmachine_add_pollfd(pollfd)
+      end
+
+      self.on_pollfd_added do |pollfd|
+        eventmachine_add_pollfd(pollfd)
+      end
+
+      self.on_pollfd_removed do |pollfd|
+        eventmachine_rm_pollfd(pollfd)
+      end
+    else
+      # Libusb pollfd API is not available on this platform.
+      # Use simple polling timer, instead:
+      EventMachine.add_periodic_timer(0.01) do
+        @eventmachine_timer = self.handle_events 0
+      end
+    end
+  end
+
+  def eventmachine_unregister
+    @eventmachine_timer.cancel if @eventmachine_timer
+    @eventmachine_attached_fds.each do |fd, watcher|
+      watcher.detach
+    end
+  end
+
+  class EMPollfdHandler < EventMachine::Connection
+    def initialize
+      @callbacks = []
+      super
+    end
+
+    def on_need_handle_events(&block)
+      @callbacks << block
+    end
+
+    def need_handle_events
+      @callbacks.each do |cb|
+        cb.call
+      end
+    end
+    alias notify_readable need_handle_events
+    alias notify_writable need_handle_events
+  end
+
+  private
+  def eventmachine_add_pollfd(pollfd)
+    conn = EventMachine.watch(pollfd.io, EMPollfdHandler)
+    conn.notify_readable = pollfd.pollin?
+    conn.notify_writable = pollfd.pollout?
+    cb = proc do
+      if @eventmachine_timer
+        @eventmachine_timer.cancel
+        @eventmachine_timer = nil
+      end
+
+      self.handle_events 0
+      timeout = self.next_timeout
+#         puts "libusb new timeout: #{timeout.inspect}"
+      if timeout
+        @eventmachine_timer = EventMachine.add_timer(timeout, &cb)
+      end
+    end
+    conn.on_need_handle_events(&cb)
+
+    @eventmachine_attached_fds[pollfd.fd] = conn
+#       puts "libusb pollfd added: #{pollfd.inspect}"
+  end
+
+  def eventmachine_rm_pollfd(pollfd)
+    @eventmachine_attached_fds[pollfd.fd].detach
+#       puts "libusb pollfd removed: #{pollfd.inspect}"
+  end
+end
+
+class DevHandle
+  class EMTransfer
+    include EM::Deferrable
+
+    def initialize(opts, dev_handle, transfer_method)
+      dev_handle.send(transfer_method, opts) do |res|
+        EM.next_tick do
+          if res.kind_of?(LIBUSB::Error)
+            fail res
+          else
+            succeed res
+          end
+        end
+      end
+    end
+  end
+
+  # Execute an eventmachine driven USB interrupt transfer.
+  #
+  # @see Context#eventmachine_register
+  #   DevHandle#interrupt_transfer
+  def eventmachine_interrupt_transfer(opts={})
+    eventmachine_transfer(opts, :interrupt_transfer)
+  end
+
+  # Execute an eventmachine driven USB bulk transfer.
+  #
+  # @example
+  #   tr = devh.eventmachine_bulk_transfer( :endpoint => 0x02, :dataOut => "data" )
+  #   tr.callback do |data|
+  #     puts "sent: #{data.inspect}"
+  #   end
+  #   tr.errback do |ex|
+  #     puts "send-err: #{ex}"
+  #   end
+  #
+  # @see Context#eventmachine_register
+  #   DevHandle#bulk_transfer
+  def eventmachine_bulk_transfer(opts={})
+    eventmachine_transfer(opts, :bulk_transfer)
+  end
+
+  # Execute an eventmachine driven USB control transfer.
+  #
+  # @example
+  #   tr = devh.eventmachine_control_transfer(
+  #     :bmRequestType=>ENDPOINT_IN|REQUEST_TYPE_CLASS|RECIPIENT_INTERFACE,
+  #     :bRequest=>0x01,
+  #     :wValue=>0, :wIndex=>0, :dataIn=>1 )
+  #   tr.callback do |data|
+  #     puts "recved: #{data.inspect}"
+  #   end
+  #   tr.errback do |ex|
+  #     puts "recv-err: #{ex}"
+  #   end
+  #
+  # @see Context#eventmachine_register
+  #   DevHandle#control_transfer
+  def eventmachine_control_transfer(opts={})
+    eventmachine_transfer(opts, :control_transfer)
+  end
+
+  private
+  def eventmachine_transfer(opts, method)
+    EMTransfer.new opts, self, method
+  end
+end
+end

data/lib/libusb/transfer.rb

@@ -19,10 +19,16 @@ module LIBUSB
   # Abstract base class for USB transfers. Use
   # {ControlTransfer}, {BulkTransfer}, {InterruptTransfer}, {IsochronousTransfer}
   # to do transfers.
+  #
+  # There are convenience methods for {DevHandle#bulk_transfer}, {DevHandle#control_transfer}
+  # and {DevHandle#interrupt_transfer}, that fit for most use cases.
+  # Using {Transfer} derived classes directly, however, is needed for isochronous transfers and
+  # allows a more advanced buffer management.
   class Transfer
     def initialize(args={})
       args.each{|k,v| send("#{k}=", v) }
       @buffer = nil
+      @completion_flag = Context::CompletionFlag.new
     end
     private :initialize
 
@@ -156,26 +162,33 @@ module LIBUSB
 
     # Submit the transfer and wait until the transfer completes or fails.
     #
-    # A proper {LIBUSB::Error} is raised, in case the transfer did not complete.
-    def submit_and_wait!
-      completed = false
+    # Inspect {#status} to check for transfer errors.
+    def submit_and_wait
+      @completion_flag.completed = false
       submit! do |tr2|
-        completed = true
+        @completion_flag.completed = true
       end
 
-      until completed
+      until @completion_flag.completed?
         begin
-          @dev_handle.device.context.handle_events
+          @dev_handle.device.context.handle_events nil, @completion_flag
         rescue ERROR_INTERRUPTED
           next
         rescue LIBUSB::Error
           cancel!
-          until completed
-            @dev_handle.device.context.handle_events
+          until @completion_flag.completed?
+            @dev_handle.device.context.handle_events nil, @completion_flag
           end
           raise
         end
       end
+    end
+
+    # Submit the transfer and wait until the transfer completes or fails.
+    #
+    # A proper {LIBUSB::Error} is raised, in case the transfer did not complete.
+    def submit_and_wait!
+      submit_and_wait
 
       raise( TransferStatusToError[status] || ERROR_OTHER, "error #{status}") unless status==:TRANSFER_COMPLETED
     end

data/lib/libusb/version_gem.rb

@@ -0,0 +1,19 @@
+# This file is part of Libusb for Ruby.
+#
+# Libusb for Ruby is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Libusb for Ruby is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
+
+module LIBUSB
+  # Library version of libusb for Ruby
+  VERSION = "0.3.0"
+end

data/libusb.gemspec

@@ -0,0 +1,31 @@
+# -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
+require "libusb/version_gem"
+
+Gem::Specification.new do |s|
+  s.name        = "libusb"
+  s.version     = LIBUSB::VERSION
+  s.authors     = ["Lars Kanis"]
+  s.email       = ["lars@greiz-reinsdorf.de"]
+  s.homepage    = "http://github.com/larskanis/libusb"
+  s.summary     = %q{Access USB devices from Ruby via libusb-1.0}
+  s.description = %q{LIBUSB is a Ruby binding that gives Ruby programmers access to arbitrary USB devices}
+  s.rdoc_options = %w[--main README.md --charset=UTF-8]
+
+  s.rubyforge_project = "libusb"
+
+  s.files         = `git ls-files`.split("\n")
+  s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  s.require_paths = ["lib"]
+  s.extensions    = ['ext/extconf.rb']
+
+  # travis currently runs a slightly older version of rbx,
+  # that needs a special ffi version.
+  unless ENV['TRAVIS'] && defined?(RUBY_ENGINE) && RUBY_ENGINE=='rbx'
+    s.add_runtime_dependency 'ffi', '>= 1.0'
+  end
+
+  s.add_development_dependency 'rake-compiler', '>= 0.6'
+  s.add_development_dependency 'bundler'
+end

data/test/test_libusb_compat.rb

@@ -68,7 +68,7 @@ class TestLibusbCompat < Test::Unit::TestCase
               assert_equal config_desc, ep.configuration, "backref should be correct"
               assert_equal dev, ep.device, "backref should be correct"
 
-              assert_operator 0, :<, ep.wMaxPacketSize, "packet size should be > 0"
+              assert_operator 0, :<=, ep.wMaxPacketSize, "packet size should be > 0"
             end
           end
         end

data/test/test_libusb_compat_mass_storage.rb

@@ -16,7 +16,7 @@
 require "test/unit"
 require "libusb/compat"
 
-class TestLibusbCompat < Test::Unit::TestCase
+class TestLibusbCompatMassStorage < Test::Unit::TestCase
   include USB
 
   attr_accessor :devh
@@ -30,7 +30,7 @@ class TestLibusbCompat < Test::Unit::TestCase
     USB.each_device_by_class(USB_CLASS_MASS_STORAGE, 0x06, 0x50){|dev| devs << dev }
 
     dev = devs.last
-    abort "no mass storage device found" unless dev
+    skip "no mass storage device found" unless dev
     devh = dev.open
     if RUBY_PLATFORM=~/linux/i
       data = " "*1000

data/test/test_libusb_descriptors.rb

@@ -101,7 +101,7 @@ class TestLibusbDescriptors < Test::Unit::TestCase
               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_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

data/test/test_libusb_event_machine.rb

@@ -0,0 +1,118 @@
+# This file is part of Libusb for Ruby.
+#
+# Libusb for Ruby is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Libusb for Ruby is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with Libusb for Ruby.  If not, see <http://www.gnu.org/licenses/>.
+
+require "test/unit"
+require "libusb"
+require "libusb/eventmachine"
+require "eventmachine"
+
+class TestLibusbEventMachine < Test::Unit::TestCase
+  include LIBUSB
+  BOMS_GET_MAX_LUN = 0xFE
+
+  attr_accessor :context
+  attr_accessor :device
+  attr_accessor :devh
+  attr_accessor :endpoint_in
+  attr_accessor :endpoint_out
+
+  def setup
+    @context = Context.new
+    @context.debug = 3
+
+    @device = context.devices( :bClass=>CLASS_MASS_STORAGE, :bSubClass=>[0x06,0x01], :bProtocol=>0x50 ).last
+    skip "no mass storage device found" unless @device
+
+    @endpoint_in = @device.endpoints.find{|ep| ep.bEndpointAddress&ENDPOINT_IN != 0 }
+    @endpoint_out = @device.endpoints.find{|ep| ep.bEndpointAddress&ENDPOINT_IN == 0 }
+    @devh = @device.open
+
+    if RUBY_PLATFORM=~/linux/i && devh.kernel_driver_active?(0)
+      devh.detach_kernel_driver(0)
+    end
+    devh.claim_interface(0)
+
+    # clear any pending data
+    devh.clear_halt(endpoint_in)
+  end
+
+  def teardown
+  end
+
+  def em_run
+    EventMachine.run do
+      @context.eventmachine_register
+
+      EventMachine.add_shutdown_hook do
+        @devh.release_interface(0) if @devh
+        @devh.close if @devh
+        @context.eventmachine_unregister
+      end
+
+      yield
+    end
+  end
+
+
+  def test_bulk_transfer
+    em_run do
+      ticks = 0
+      tr = devh.eventmachine_bulk_transfer(
+          :endpoint => @endpoint_in,
+          :timeout => 1500,
+          :dataIn => 123 )
+#       puts "started usb transfer #{tr}"
+
+      tr.callback do |data|
+#         puts "recved: #{data.inspect}"
+
+        assert false, "the bulk transfer shouldn't succeed"
+        EventMachine.stop
+      end
+      tr.errback do |text|
+#         puts "recv-err: #{text}"
+        assert true, "the bulk transfer should fail"
+
+        assert_operator ticks, :>=, 4
+        EventMachine.stop
+      end
+
+      EventMachine.add_periodic_timer(0.333) do
+        ticks += 1
+      end
+    end
+  end
+
+  def test_event_loop
+    em_run do
+      tr = devh.eventmachine_control_transfer(
+        :bmRequestType=>ENDPOINT_IN|REQUEST_TYPE_CLASS|RECIPIENT_INTERFACE,
+        :bRequest=>BOMS_GET_MAX_LUN,
+        :wValue=>0, :wIndex=>0, :dataIn=>1 )
+
+#       puts "started usb transfer #{tr}"
+      tr.callback do |data|
+#         puts "recved: #{data.inspect}"
+        assert true, "the control transfer should succeed"
+        EventMachine.stop
+      end
+      tr.errback do |text|
+#         puts "recv-err: #{text}"
+        assert false, "the control transfer shouldn't fail"
+        EventMachine.stop
+      end
+    end
+  end
+end