hidapi 0.1.4

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 75e7069e09a362e591f7edba9bfa9a7763f5f31a
+  data.tar.gz: 981e48c8d73d8add81d2728e461a060761ce7bae
+SHA512:
+  metadata.gz: 2f20a27445bf2f1052572a72857f74b0d575c486e2c5018dffd9a5b6547a89f3b47adfc93e00c323af92b66fdd01a266f164315cdee1203a3c4c1b0da75d7ca5
+  data.tar.gz: 829d91b1b8c1f9a7402bd50a8ab82c167a4738542872a91904659ea936767b056f81dc0d27d676e0b1157f03b3973f828016d7fab9ac108dbc261c18d88e2ee8

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/*
+!/tmp/.keep
+/.idea/
+**/.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hidapi.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Beau Barker
+
+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/README.md

@@ -0,0 +1,103 @@
+# HIDAPI
+
+This is a Ruby port of the [HID API from Signal 11](http://www.signal11.us/oss/hidapi).
+  
+__I am not associated with Signal 11.__
+
+More specifically, it is a 
+port of the "libusb" version of the HID API.  I took creative liberty where I needed to and basically just sought to 
+make it work uniformly.  The gem relies on the [libusb](https://rubygems.org/gems/libusb).
+
+ 
+I know there are at least two other projects that were meant to bring an HID API to the Ruby world.  However, one of
+them is a C plugin (no real problem, just not Ruby) and the other is an FFI wrapper around the original HID API with
+a few missing components.  I didn't see any reason to bring FFI into it when the end result is something fairly simple.
+
+The entire library basically consists of the HIDAPI::Engine and the HIDAPI::Device classes.  The HIDAPI module maintains
+an instance of the HIDAPI::Engine and maps missing methods to the engine.  So basically `HIDAPI.enumerate` is the same
+as `HIDAPI.engine.enumerate` where the `engine` method creates an HIDAPI::Engine on the first call.  The HIDAPI::Engine
+class is used to enumerate and retrieve devices, while the HIDAPI::Device class is used for everything else.
+
+The original source included internationalization.  I have not included that (yet), but the HIDAPI::Language class has
+been defined and the [i18n](https://rubygems.org/gems/i18n) is required, even though we aren't using it yet.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hidapi'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hidapi
+
+
+## Usage
+
+Basic usage would be as follows.
+```ruby
+my_dev = HIDAPI::open(0x4d4d, 0xc0c0)
+my_dev.write 0x01, 0x02, 0x03, 0x04, 0x05
+my_dev.write [ 0x01, 0x02, 0x03, 0x04, 0x05 ]
+my_dev.write "\x01\x02\x03\x04\x05"
+input = my_dev.read
+my_dev.close
+```
+
+The `write` method takes data in any of the 3 forms shown above. Individual arguments, an array of arguments, or a string of arguments.
+Internally the first two are converted into the 3rd form using `pack("C*")`.  If you have a custom data set your are sending,
+such as 16 or 32 bit values, then you will likely want to pack the string yourself to prevent issues.
+
+The `read` method returns a packed string from the device.  For instance it may return "\x10\x01\x00".  Your application
+needs to know how to handle the values returned.
+
+In order to use a USB device in Linux, udev needs to grant access to the user running the application.  If run as root, 
+then it should just work.  However, you'd be running it as root.  A better option is to have udev grant the appropriate permissions.
+
+In order to use a USB device in OS X, the system needs a kernel extension telling the OS not to map the device to its own
+HID drivers.
+
+The `HIDAPI::SetupTaskHelper` handles both of these situations.  The gem includes a rake task `setup_hid_device` that 
+calls this class.  You can also execute the `lib/hidapi/setup_task_helper.rb` file directly.  However, in your application,
+both of these may be too cumbersome.  You can create an instance of the SetupTaskHelper class with the appropriate arguments
+and just run it yourself.
+
+```ruby
+require "hidapi"
+HIDAPI::SetupTaskHelper.new(
+  0x04d8,             # vendor_id
+  0xc002,             # product_id
+  "pico-lcd-graphic", # simple_name
+  0                   # interface
+).run
+```
+
+This will take the appropriate action on your OS to make the USB device available for use.  On linux, it will also add
+convenient symlinks to the /dev filesystem.  For instance, the above setup could give you something like `/dev/hidapi/pico-lcd-graphic@1-4`
+that points to the correct USB device.  The library doesn't use them, but the presence of the links in the`/dev/hidapi`
+directory would be a clear indicator that the device has been recognizes and configured.
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/barkerest/hidapi.
+
+
+## License
+
+Copyright (c) 2016 [Beau Barker](mailto:beau@barkerest.com)
+
+As said before, this is a port of the [HID API from Signal 11](http://www.signal11.us/oss/hidapi) so it has significant
+code in common with that library, although the very fact that it was ported means that there is no code that was copied
+from that library.  That library can be licensed under the GPL, BSD, or a custom license very similar to the MIT license.
+This gem is not that library.
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require 'hidapi/setup_task_helper'
+
+desc 'Setup an HID device for use with the library'
+task :setup_hid_device, :vendor_id, :product_id, :simple_name, :interface do |t,args|
+  args ||= {}
+  helper = HIDAPI::SetupTaskHelper.new(args[:vendor_id], args[:product_id], args[:simple_name], args[:interface])
+  helper.run
+end
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,17 @@
+#!/usr/bin/env ruby
+
+ENV['ENABLE_DEBUG'] = '1'
+
+require "bundler/setup"
+require "hidapi"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/hidapi.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hidapi/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'hidapi'
+  spec.version       = HIDAPI::VERSION
+  spec.authors       = ['Beau Barker']
+  spec.email         = ['beau@barkerest.com']
+
+  spec.summary       = 'A Ruby port of the HID API from Signal 11 Software (http://www.signal11.us/)'
+  spec.homepage      = 'https://github.com/barkerest/hidapi'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.required_ruby_version                = '>= 2.2.0'
+  spec.add_dependency             'libusb',   '~>0.5.1'
+  spec.add_dependency             'i18n'
+
+  spec.add_development_dependency 'bundler',  '~>1.12'
+  spec.add_development_dependency 'rake',     '~> 10.0'
+end

data/lib/hidapi.rb

@@ -0,0 +1,92 @@
+require 'libusb'
+require 'hidapi/version'
+
+##
+# A Ruby implementation of the HID API library from Signal 11 software.
+#
+# I am not associated with Signal 11 software.
+#
+# This library was written out of a need to get better debugging information.
+# By writing it, I learned quite a bit about HID devices and how to get them
+# working with multiple operating systems from one Ruby gem. To do this, I use LIBUSB.
+#
+# This module contains the library and wraps around an instance of the HIDAPI::Engine
+# class to simplify calls.  For instance, HIDAPI.engine.enumerate can also be used as
+# just HIDAPI.enumerate.
+#
+module HIDAPI
+
+  raise 'LIBUSB version must be at least 1.0' unless LIBUSB.version.major >= 1
+
+  ##
+  # Gets the engine used by the API.
+  #
+  # All engine methods can be passed through the HIDAPI module.
+  def self.engine
+    @engine ||= HIDAPI::Engine.new
+  end
+
+
+  def self.method_missing(m,*a,&b)    # :nodoc:
+    if engine.respond_to?(m)
+      engine.send(m,*a,&b)
+    else
+      # no super available for modules.
+      raise NoMethodError, "undefined method `#{m}` for HIDAPI:Module"
+    end
+  end
+
+
+  def self.respond_to_missing?(m)     # :nodoc:
+    engine.respond_to?(m)
+  end
+
+
+  ##
+  # Processes a debug message.
+  #
+  # You can either provide a debug message directly or via a block.
+  # If a block is provided, it will not be executed unless a debugger has been set and the message is left nil.
+  def self.debug(msg = nil, &block)
+    dbg = @debugger
+    if dbg
+      mutex.synchronize do
+        msg = block.call if block_given? && msg.nil?
+        dbg.call(msg)
+      end
+    end
+  end
+
+  ##
+  # Sets the debugger to use.
+  #
+  # :yields: the message to debug
+  def self.set_debugger(&block)
+    mutex.synchronize do
+      @debugger = block_given? ? block : nil
+    end
+  end
+
+  private
+
+  def self.mutex
+    @mutex ||= Mutex.new
+  end
+
+
+  if ENV['ENABLE_DEBUG'].to_s.to_i != 0
+    set_debugger do |msg|
+      msg = msg.to_s.strip
+      if msg.length > 0
+        @debug_file ||= File.open(File.expand_path('../../tmp/debug.log', __FILE__), 'w')
+        @debug_file.write "[#{Time.now.strftime('%Y-%m-%d %H:%M:%S')}] #{msg.gsub("\n", "\n" + (' ' * 22))}\n"
+        @debug_file.flush
+        STDOUT.print "(debug) #{msg.gsub("\n", "\n" + (' ' * 8))}\n"
+      end
+    end
+  end
+
+end
+
+# load all of the library components.
+Dir.glob(File.expand_path('../hidapi/*.rb', __FILE__)) { |file| require file }

data/lib/hidapi/device.rb

@@ -0,0 +1,634 @@
+
+
+module HIDAPI
+
+  ##
+  # This class is the interface to a HID device.
+  #
+  # Each instance can connect to a single interface on an HID device.
+  # If you have more than one interface, you will need to have more
+  # than one instance of this class to work with all of them.
+  #
+  # When open, the device is polled continuously for incoming data.
+  # It will build up a cache of up to 32 packets.  If you are not
+  # reading from the device, it will silently discard the oldest
+  # packets and continue storing the newest packets.
+  #
+  # The read method can block.  This is controlled by the +blocking+
+  # attribute.  The default value is true.  If you want the read method
+  # to be non-blocking, set this attribute to false.
+  class Device
+
+    ##
+    # Gets the USB device this HID device uses.
+    attr_accessor :usb_device
+    private :usb_device=
+
+    ##
+    # Gets the device handle for I/O.
+    attr_accessor :handle
+    private :handle=
+    protected :handle
+
+    ##
+    # Gets the input endpoint.
+    attr_accessor :input_endpoint
+    private :input_endpoint=
+    protected :input_endpoint
+
+    ##
+    # Gets the output endpoint.
+    attr_accessor :output_endpoint
+    private :output_endpoint=
+    protected :output_endpoint
+
+    ##
+    # Gets the maximum packet size for input packets.
+    attr_accessor :input_ep_max_packet_size
+    private :input_ep_max_packet_size=
+    protected :input_ep_max_packet_size
+
+    ##
+    # Gets the interface this HID device uses on the USB device.
+    attr_accessor :interface
+    private :interface=
+
+    ##
+    # Gets or sets the blocking nature for +read+.
+    #
+    # Defaults to +true+.  Set to +false+ to have +read+ be non-blocking.
+    attr_accessor :blocking
+
+    attr_accessor :thread
+    private :thread, :thread=
+
+    attr_accessor :mutex
+    private :mutex, :mutex=
+
+    attr_accessor :thread_initialized
+    private :thread_initialized, :thread_initialized=
+
+    attr_accessor :shutdown_thread
+    private :shutdown_thread, :shutdown_thread=
+
+    attr_accessor :transfer_cancelled
+    private :transfer_cancelled, :transfer_cancelled=
+
+    attr_accessor :transfer
+    private :transfer, :transfer=
+
+    attr_accessor :input_reports
+    private :input_reports, :input_reports=
+
+    ##
+    # Gets the path for this device that can be used by HIDAPI::Engine#get_device_by_path
+    attr_accessor :path
+    private :path=
+
+    attr_accessor :open_count
+    private :open_count, :open_count=
+
+
+    ##
+    # Initializes an HID device.
+    def initialize(usb_device, interface = 0)
+      raise HIDAPI::InvalidDevice, "invalid object (#{usb_device.class.name})" unless usb_device.is_a?(LIBUSB::Device)
+
+      self.usb_device = usb_device
+      self.blocking   = true
+      self.mutex      = Mutex.new
+      self.interface  = interface
+      self.path       = HIDAPI::Device.make_path(usb_device, interface)
+
+      self.input_endpoint     = self.output_endpoint = nil
+      self.thread             = nil
+      self.thread_initialized = false
+      self.input_reports      = []
+      self.shutdown_thread    = false
+      self.transfer_cancelled = LIBUSB::Context::CompletionFlag.new
+      self.open_count         = 0
+
+      self.class.init_hook.each do |proc|
+        proc.call self
+      end
+    end
+
+
+
+    ##
+    # Gets the manufacturer of the device.
+    def manufacturer
+      @manufacturer ||= read_string(usb_device.iManufacturer, "VENDOR(0x#{vendor_id.to_hex(4)})").strip
+    end
+
+    ##
+    # Gets the product/model of the device.
+    def product
+      @product ||= read_string(usb_device.iProduct, "PRODUCT(0x#{product_id.to_hex(4)})").strip
+    end
+
+    ##
+    # Gets the serial number of the device.
+    def serial_number
+      @serial_number ||= read_string(usb_device.iSerialNumber, '?').strip
+    end
+
+    ##
+    # Gets the vendor ID.
+    def vendor_id
+      @vendor_id ||= usb_device.idVendor
+    end
+
+    ##
+    # Gets the product ID.
+    def product_id
+      @product_id ||= usb_device.idProduct
+    end
+
+    ##
+    # Is the device currently open?
+    def open?
+      !!handle
+    end
+
+    ##
+    # Closes the device (if open).
+    #
+    # Returns the device.
+    def close
+      self.open_count = open_count - 1
+      if open_count <= 0
+        HIDAPI.debug("open_count for device #{path} is #{open_count}") if open_count < 0
+        if handle
+          begin
+            self.shutdown_thread = true
+            transfer.cancel! rescue nil if transfer
+            thread.join
+          rescue =>e
+            HIDAPI.debug "failed to kill read thread on device #{path}: #{e.inspect}"
+          end
+          begin
+            handle.release_interface(interface)
+          rescue =>e
+            HIDAPI.debug "failed to release interface on device #{path}: #{e.inspect}"
+          end
+          begin
+            handle.close
+          rescue =>e
+            HIDAPI.debug "failed to close device #{path}: #{e.inspect}"
+          end
+          HIDAPI.debug "closed device #{path}"
+        end
+        self.handle = nil
+        mutex.synchronize { self.input_reports = [] }
+        self.open_count = 0
+      end
+      self
+    end
+
+    ##
+    # Opens the device.
+    #
+    # Returns the device.
+    def open
+      if open?
+        self.open_count = open_count + 1
+        if open_count < 1
+          HIDAPI.debug "open_count for open device #{path} is #{open_count}"
+          self.open_count = 1
+        end
+        return self
+      end
+      self.open_count = 0
+      begin
+        self.handle = usb_device.open
+        raise 'no handle returned' unless handle
+
+        begin
+          if handle.kernel_driver_active?(interface)
+            handle.detach_kernel_driver(interface)
+          end
+        rescue LIBUSB::ERROR_NOT_SUPPORTED
+          HIDAPI.debug 'cannot determine kernel driver status, continuing to open device'
+        end
+
+        handle.claim_interface(interface)
+
+        self.input_endpoint = self.output_endpoint = nil
+
+        # now we need to find the endpoints.
+        usb_device.settings
+            .keep_if {|item| item.bInterfaceNumber == interface}
+            .each do |intf_desc|
+          intf_desc.endpoints.each do |ep|
+            if ep.transfer_type == :interrupt
+              if input_endpoint.nil? && ep.direction == :in
+                self.input_endpoint = ep.bEndpointAddress
+                self.input_ep_max_packet_size = ep.wMaxPacketSize
+              end
+              if output_endpoint.nil? && ep.direction == :out
+                self.output_endpoint = ep.bEndpointAddress
+              end
+            end
+            break if input_endpoint && output_endpoint
+          end
+        end
+
+        # output_ep is optional, input_ep is required
+        raise 'failed to locate input endpoint' unless input_endpoint
+
+        # start the read thread
+        self.input_reports = []
+        self.thread_initialized = false
+        self.shutdown_thread = false
+        self.thread = Thread.start(self) { |dev| dev.send(:execute_read_thread) }
+        sleep 0 until thread_initialized
+
+      rescue =>e
+        handle.close rescue nil
+        self.handle = nil
+        HIDAPI.debug "failed to open device #{path}: #{e.inspect}"
+        raise DeviceOpenFailed, e.inspect
+      end
+      HIDAPI.debug "opened device #{path}"
+      self.open_count = 1
+      self
+    end
+
+    ##
+    # Writes data to the device.
+    #
+    # The data to be written can be individual byte values, an array of byte values, or a string packed with data.
+    def write(*data)
+      raise ArgumentError, 'data must not be blank' if data.nil? || data.length < 1
+      raise HIDAPI::DeviceNotOpen unless open?
+
+      data, report_number, skipped_report_id = clean_output_data(data)
+
+      if output_endpoint.nil?
+        # No interrupt out endpoint, use the control endpoint.
+        handle.control_transfer(
+            bmRequestType: LIBUSB::REQUEST_TYPE_CLASS | LIBUSB::RECIPIENT_INTERFACE | LIBUSB::ENDPOINT_OUT,
+            bRequest: 0x09,   # HID Set_Report
+            wValue: (2 << 8) | report_number,  # HID output = 2
+            wIndex: interface,
+            dataOut: data
+        )
+        data.length + (skipped_report_id ? 1 : 0)
+      else
+        # Use the interrupt out endpoint.
+        handle.interrupt_transfer(
+            endpoint: output_endpoint,
+            dataOut: data
+        )
+      end
+    end
+
+    ##
+    # Attempts to read from the device, waiting up to +milliseconds+ before returning.
+    #
+    # If milliseconds is less than 1, it will wait forever.
+    # If milliseconds is 0, then it will return immediately.
+    #
+    # Returns the next report on success.  If no report is available and it is not waiting
+    # forever, it will return an empty string.
+    #
+    # Returns nil on error.
+    def read_timeout(milliseconds)
+      raise DeviceNotOpen unless open?
+
+      mutex.synchronize do
+        if input_reports.count > 0
+          data = input_reports.delete_at(0)
+          HIDAPI.debug "read data from device #{path}: #{data.inspect}"
+          return data
+        end
+
+        if shutdown_thread
+          HIDAPI.debug "read thread for device #{path} is not running"
+          return nil
+        end
+      end
+
+      # no data to return, do not block.
+      return '' if milliseconds == 0
+
+      if milliseconds < 0
+        # wait forever (as long as the read thread doesn't die)
+        until shutdown_thread
+          mutex.synchronize do
+            if input_reports.count > 0
+              data = input_reports.delete_at(0)
+              HIDAPI.debug "read data from device #{path}: #{data.inspect}"
+              return data
+            end
+          end
+          sleep 0
+        end
+
+        # error, return nil
+        HIDAPI.debug "read thread ended while waiting on device #{path}"
+        nil
+      else
+        # wait up to so many milliseconds for input.
+        stop_at = Time.now + (milliseconds * 0.001)
+        while Time.now < stop_at
+          mutex.synchronize do
+            if input_reports.count > 0
+              data = input_reports.delete_at(0)
+              HIDAPI.debug "read data from device #{path}: #{data.inspect}"
+              return data
+            end
+          end
+          sleep 0
+        end
+
+        # no input, return empty.
+        ''
+      end
+    end
+
+    ##
+    # Reads the next report from the device.
+    #
+    # In blocking mode, it will wait for a report.
+    # In non-blocking mode, it will return immediately with an empty string if there is no report.
+    #
+    # Returns nil on error.
+    def read
+      read_timeout blocking? ? -1 : 0
+    end
+
+    ##
+    # Is this device in blocking mode (for reading)?
+    def blocking?
+      !!blocking
+    end
+
+    ##
+    # Sends a feature report to the device.
+    def send_feature_report(data)
+      raise ArgumentError, 'data must not be blank' if data.nil? || data.length < 1
+      raise HIDAPI::DeviceNotOpen unless open?
+
+      data, report_number, skipped_report_id = clean_output_data(data)
+
+      handle.control_transfer(
+          bmRequestType: LIBUSB::REQUEST_TYPE_CLASS | LIBUSB::RECIPIENT_INTERFACE | LIBUSB::ENDPOINT_OUT,
+          bRequest: 0x09,   # HID Set_Report
+          wValue: (3 << 8) | report_number,   # HID feature = 3
+          wIndex: interface,
+          dataOut: data
+      )
+
+      data.length + (skipped_report_id ? 1 : 0)
+    end
+
+    ##
+    # Gets a feature report from the device.
+    def get_feature_report(report_number, buffer_size = nil)
+
+      buffer_size ||= input_ep_max_packet_size
+
+      handle.control_transfer(
+          bmRequestType: LIBUSB::REQUEST_TYPE_CLASS | LIBUSB::RECIPIENT_INTERFACE | LIBUSB::ENDPOINT_IN,
+          bRequest: 0x01,   # HID Get_Report
+          wValue: (3 << 8) | report_number,
+          wIndex: interface,
+          dataIn: buffer_size
+      )
+
+    end
+
+
+    def inspect   # :nodoc:
+      "#<#{self.class.name}:0x#{self.object_id.to_hex(16)} #{vendor_id.to_hex(4)}:#{product_id.to_hex(4)} #{manufacturer} #{product} #{serial_number} (#{open? ? 'OPEN' : 'CLOSED'})>"
+    end
+
+
+    def to_s      # :nodoc:
+      "#{manufacturer} #{product} (#{serial_number})"
+    end
+
+
+    ##
+    # Generates a path for a device.
+    def self.make_path(usb_dev, interface)
+      bus = usb_dev.bus_number
+      address = usb_dev.device_address
+      "#{bus.to_hex(4)}:#{address.to_hex(4)}:#{interface.to_hex(2)}"
+    end
+
+
+    ##
+    # Reads a string descriptor from the USB device.
+    def read_string(index, on_failure = '')
+      begin
+        # does not require an interface, so open from the usb_dev instead of using our open method.
+        data = usb_device.open { |handle| handle.string_descriptor_ascii(index) }
+        HIDAPI.debug("read string at index #{index} for device #{path}: #{data.inspect}")
+        data
+      rescue =>e
+        HIDAPI.debug("failed to read string at index #{index} for device #{path}: #{e.inspect}")
+        on_failure || ''
+      end
+    end
+
+
+    protected
+
+    ##
+    # Defines a hook to execute when data is read from the device.
+    #
+    # This can be provided as a proc, symbol, or simply as a block.
+    #
+    # The proc should return a true value if it consumes the data.
+    # If it does not consume the data it must return false or nil.
+    #
+    # If no read_hook proc consumes the data, it will be cached for
+    # future calls to +read+ or +read_timeout+.
+    #
+    # The read hook is called from within the read thread. If it must
+    # access resources from another thread, you will want to use
+    # a mutex for locking.
+    #
+    # :yields: a device and the input_report
+    #
+    #   read_hook do |device, input_report|
+    #     ...
+    #     true
+    #   end
+    def self.read_hook(proc = nil, &block)
+      @read_hook ||= []
+
+      proc = block if proc.nil? && block_given?
+      if proc
+        if proc.is_a?(Symbol) || proc.is_a?(String)
+          proc_name = proc
+          proc = Proc.new do |dev, input_report|
+            dev.send(proc_name, dev, input_report)
+          end
+        end
+        @read_hook << proc
+      end
+
+      @read_hook
+    end
+
+    ##
+    # Defines a hook to execute when a device is initialized.
+    #
+    # Yields the device instance.
+    def self.init_hook(proc = nil, &block)
+      @init_hook ||= []
+
+      proc = block if proc.nil? && block_given?
+      if proc
+        if proc.is_a?(Symbol) || proc.is_a?(String)
+          proc_name = proc
+          proc = Proc.new do |dev|
+            dev.send(proc_name, dev)
+          end
+        end
+        @init_hook << proc
+      end
+
+      @init_hook
+    end
+
+    private
+
+    def clean_output_data(data)
+      if data.length == 1 && data.first.is_a?(Array)
+        data = data.first
+      end
+
+      if data.length == 1 && data.first.is_a?(String)
+        data = data.first
+      end
+
+      data = data.pack('C*') unless data.is_a?(String)
+
+      skipped_report_id = false
+      report_number = data.getbyte(0)
+
+      if report_number == 0x00
+        data = data[1..-1].to_s
+        skipped_report_id = true
+      end
+
+      [ data, report_number, skipped_report_id ]
+    end
+
+    def execute_read_thread
+
+      begin
+        # make it available locally, prevent changes while we are running.
+        length = input_ep_max_packet_size
+        context = usb_device.context
+
+        # Construct our transfer.
+        self.transfer = LIBUSB::InterruptTransfer.new(
+            dev_handle: handle,
+            endpoint: input_endpoint,
+            callback: method(:read_callback),
+            timeout: 30000
+        )
+        transfer.alloc_buffer length
+
+        # clear flag for transfer cancellation.
+        transfer_cancelled.completed = false
+
+        # perform the initial submission, the callback will resubmit.
+        transfer.submit!
+      rescue =>e
+        HIDAPI.debug "failed to initialize read thread for device #{path}: #{e.inspect}"
+        self.shutdown_thread = true
+        raise e
+      ensure
+        # tell the main thread that we are running.
+        self.thread_initialized = true
+      end
+
+      # wait for the main thread to kill this thread.
+      until shutdown_thread
+        begin
+          context.handle_events 0
+        rescue LIBUSB::ERROR_BUSY, LIBUSB::ERROR_TIMEOUT, LIBUSB::ERROR_OVERFLOW, LIBUSB::ERROR_INTERRUPTED => e
+          # non fatal errors.
+          HIDAPI.debug "non-fatal error for read_thread on device #{path}: #{e.inspect}"
+        rescue => e
+          HIDAPI.debug "fatal error for read_thread on device #{path}: #{e.inspect}"
+          self.shutdown_thread = true
+          raise e
+        end
+      end
+
+      # no longer running.
+      self.thread_initialized = false
+
+      # cancel any transfers that may be pending.
+      transfer.cancel! rescue nil
+
+      # wait for the cancellation to complete.
+      until transfer_cancelled.completed?
+        context.handle_events 0, transfer_cancelled
+      end
+
+    end
+
+    def read_callback(tr)
+      if tr.status == :TRANSFER_COMPLETED
+        data = tr.actual_buffer
+
+        consumed = false
+        self.class.read_hook.each do |proc|
+          consumed =
+              begin
+                proc.call(self, data)
+              rescue =>e
+                HIDAPI.debug "read_hook failed for device #{path}: #{e.inspect}"
+                false
+              end
+          break if consumed
+        end
+
+        unless consumed
+          mutex.synchronize do
+            input_reports << tr.actual_buffer
+            input_reports.delete_at(0) while input_reports.length > 32
+          end
+        end
+      elsif tr.status == :TRANSFER_CANCELLED
+        mutex.synchronize do
+          self.shutdown_thread = true
+          transfer_cancelled.completed = true
+        end
+        HIDAPI.debug "read transfer cancelled for device #{path}"
+      elsif tr.status == :TRANSFER_NO_DEVICE
+        mutex.synchronize do
+          self.shutdown_thread = true
+          transfer_cancelled.completed = true
+        end
+        HIDAPI.debug "read transfer failed with no device for device #{path}"
+      elsif tr.status == :TRANSFER_TIMED_OUT
+        # ignore timeouts, they are normal
+      else
+        HIDAPI.debug "read transfer with unknown transfer code (#{tr.status}) for device #{path}"
+      end
+
+      # resubmit the transfer object.
+      begin
+        tr.submit!
+      rescue =>e
+        HIDAPI.debug "failed to resubmit transfer for device #{path}: #{e.inspect}"
+        mutex.synchronize do
+          self.shutdown_thread = true
+          transfer_cancelled.completed = true
+        end
+      end
+    end
+
+
+  end
+end