hidapi 0.1.4 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 75e7069e09a362e591f7edba9bfa9a7763f5f31a
-  data.tar.gz: 981e48c8d73d8add81d2728e461a060761ce7bae
+  metadata.gz: 4ac8b4c330d8100c012e526918bbbb565a263b33
+  data.tar.gz: bfe231f2734ac2ba14a96189399d839444ff6d15
 SHA512:
-  metadata.gz: 2f20a27445bf2f1052572a72857f74b0d575c486e2c5018dffd9a5b6547a89f3b47adfc93e00c323af92b66fdd01a266f164315cdee1203a3c4c1b0da75d7ca5
-  data.tar.gz: 829d91b1b8c1f9a7402bd50a8ab82c167a4738542872a91904659ea936767b056f81dc0d27d676e0b1157f03b3973f828016d7fab9ac108dbc261c18d88e2ee8
+  metadata.gz: f812b49152605ce2d9d2d1b504d7e414dee1e25f67d7567ff82d0f51136b39ee098c2d1bccb86d2c49ac8c9242367c9df81e6dfb7b9f3a187e52d40a5dd6e905
+  data.tar.gz: 3d7f09c0fc38b0d19c0fc1fc96a7eed0c4ea57ff7edff4cfe8824a2683c6a0b22715b4502d0afc7c6ad5d8de6c32f8e3756bdefb0b68451af727570d4a3343d2

data/README.md

@@ -50,7 +50,6 @@ 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.
@@ -58,13 +57,61 @@ such as 16 or 32 bit values, then you will likely want to pack the string yourse
 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.
 
+There are multiple methods to open a device.
+```ruby
+vendor_id = 0x4d4d
+product_id = 0xc0c0
+serial_number = '123456'
+bus_number = 1
+device_address = 12
+interface = 0
+dev_hidapi_path = "/dev/hidapi/my-dev@1-2.3"
+dev_raw_path = "/dev/bus/usb/001/00c"
+
+# open with just the vendor and product id.  first match is returned.
+my_dev = HIDAPI::open(vendor_id, product_id)
+
+# extend that by also including the serial number. first match is returned, 
+# but this time it should definitely be unique
+my_dev = HIDAPI::open(vendor_id, product_id, serial_number)
+
+# (linux only) open the device using the hidapi path.
+my_dev = HIDAPI::open_path(dev_hidapi_path)
+
+# (linux only) open the device using the raw dev path.
+my_dev = HIDAPI::open_path(dev_raw_path)
+
+# open the device using the BUS:ADDRESS:INTERFACE path.
+# the components of the path must be in hexadecimal.
+my_dev = HIDAPI::open_path("#{bus_number.to_s(16)}:#{device_address.to_s(16)}:#{interface.to_s(16)}")
+```
+
+Because USB is hot-pluggable, you may want to avoid the `open_path` method unless your device is guaranteed to be plugged
+into the same port all the time.  For instance, a device plugged into a port inside the computer case.  Devices plugged
+into external ports, or hubs, are not necessarily good candidates for `open_path` because they can be unplugged and plugged
+into a different port at any time.  A device at "001:00c:00" may be at "001:00b:00" the next time because the user swapped
+the plug into another port.
+
+If you will only have one instance of the device plugged in, it is best to use the `open` method with the vendor_id and 
+product_id of the device.  If you have multiple instances and they each have unique serial numbers, then you would want
+to use the `open` method with the vendor_id, product_id, and serial_number.  If you have multiple instances with the same
+serial number (because it is hardcoded into the firmware for example), then you will need to use dedicated ports and 
+`open_path`.
+
+
 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 
+In order to use a USB device in Windows, the system needs the WinUSB driver installed for the device.  Please use the 
+[Zadig tool](http://zadig.akeo.ie/) to install the driver for your device.  Even then Windows seems quirky with libusb. 
+The biggest problem I have noticed is the inability to close a device without exiting the program.  I haven't thoroughly
+investigated it yet because Windows has not been my primary development environment.  I would appreciate any feedback related
+to this issue.
+
+The `HIDAPI::SetupTaskHelper` handles Linux and OS X 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.
@@ -81,8 +128,8 @@ HIDAPI::SetupTaskHelper.new(
 
 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.
+that points to the correct USB device.  The library can use these links to open the device, and the presence of the links in the`/dev/hidapi`
+directory would be a clear indicator that the device has been recognized and configured.
 
 
 ## Contributing

data/lib/hidapi/device.rb

@@ -413,19 +413,42 @@ module HIDAPI
 
     ##
     # Generates a path for a device.
-    def self.make_path(usb_dev, interface)
-      bus = usb_dev.bus_number
-      address = usb_dev.device_address
+    def self.make_path(usb_dev, interface = 0)
+      if usb_dev.is_a?(Hash)
+        bus = usb_dev[:bus] || usb_dev['bus']
+        address = usb_dev[:device_address] || usb_dev['device_address']
+      else
+        bus = usb_dev.bus_number
+        address = usb_dev.device_address
+      end
       "#{bus.to_hex(4)}:#{address.to_hex(4)}:#{interface.to_hex(2)}"
     end
 
+    ##
+    # Validates a device path.
+    def self.validate_path(path)
+      match = /(?<BUS>\d+):(?<ADDR>\d+):(?<IFACE>\d+)/.match(path)
+      return nil unless match
+      make_path(
+          {
+              bus: match['BUS'].to_i(16),
+              device_address: match['ADDR'].to_i(16)
+          },
+          match['IFACE'].to_i(16)
+      )
+    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) }
+        data = if open?
+                 handle.string_descriptor_ascii(index)
+               else
+                 usb_device.open { |handle| handle.string_descriptor_ascii(index) }
+               end
         HIDAPI.debug("read string at index #{index} for device #{path}: #{data.inspect}")
         data
       rescue =>e
@@ -554,6 +577,7 @@ module HIDAPI
       until shutdown_thread
         begin
           context.handle_events 0
+          sleep 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}"

data/lib/hidapi/engine.rb

@@ -23,6 +23,17 @@ module HIDAPI
     def enumerate(vendor_id = 0, product_id = 0, options = {})
       raise HIDAPI::HidApiError, 'not initialized' unless @context
 
+      if vendor_id.is_a?(Hash) || (vendor_id.is_a?(String) && options.empty?)
+        options = vendor_id
+        vendor_id = 0
+        product_id = 0
+      end
+
+      if product_id.is_a?(Hash) || (product_id.is_a?(String) && options.empty?)
+        options = product_id
+        product_id = 0
+      end
+
       if options.is_a?(String) || options.is_a?(Symbol)
         options = { as: options }
       end
@@ -58,6 +69,11 @@ module HIDAPI
       raise ArgumentError, 'vendor_id must be provided' if vendor_id.to_i == 0
       raise ArgumentError, 'product_id must be provided' if product_id.to_i == 0
 
+      if serial_number.is_a?(Hash)
+        options = serial_number
+        serial_number = nil
+      end
+
       klass = (options || {}).delete(:as) || 'HIDAPI::Device'
       klass = Object.const_get(klass) unless klass == :no_mapping
 
@@ -84,21 +100,50 @@ module HIDAPI
 
     ##
     # Opens the first device with the specified vendor_id, product_id, and optionally serial_number.
-    def open(vendor_id, product_id, serial_number = nil)
-      dev = get_device(vendor_id, product_id, serial_number)
+    def open(vendor_id, product_id, serial_number = nil, options = {})
+      dev = get_device(vendor_id, product_id, serial_number, options)
       dev.open if dev
     end
 
     ##
     # Gets the device with the specified path.
     def get_device_by_path(path, options = {})
+
+      # Our linux setup routine creates convenient /dev/hidapi/* links.
+      # If the user wants to open one of those, we can simple parse the link to generate
+      # the path that the library expects.
+      if File.exist?(path)
+
+        hidapi_regex = /^\/dev\/hidapi\//
+        usb_bus_regex = /^\/dev\/bus\/usb\/(?<BUS>\d+)\/(?<ADDR>\d+)$/
+
+        if hidapi_regex.match(path)
+          path = File.expand_path(File.readlink(path), File.dirname(path))
+        elsif !usb_bus_regex.match(path)
+          raise HIDAPI::DevicePathInvalid, 'Cannot open file paths other than /dev/hidapi/XXX or /dev/bus/usb/XXX/XXX paths.'
+        end
+
+        # path should now be in the form /dev/bus/usb/AAA/BBB
+        match = usb_bus_regex.match(path)
+
+        raise HIDAPI::DevicePathInvalid, "Link target does not appear valid (#{path})." unless match
+
+        interface = (options.delete(:interface) || 0).to_s(16)
+
+        path = HIDAPI::Device.validate_path("#{match['BUS']}:#{match['ADDR']}:#{interface}")
+      end
+
+      valid_path = HIDAPI::Device.validate_path(path)
+      raise HIDAPI::DevicePathInvalid, "Path should be in BUS:ADDRESS:INTERFACE format with each value being in hexadecimal (ie - 0001:01A:00), not #{path}." unless valid_path
+      path = valid_path
+
       klass = (options || {}).delete(:as) || 'HIDAPI::Device'
       klass = Object.const_get(klass) unless klass == :no_mapping
 
       enumerate(as: :no_mapping).each do |usb_dev|
         usb_dev.settings.each do |intf_desc|
           if intf_desc.bInterfaceClass == HID_CLASS
-            dev_path = HIDAPI::make_path(usb_dev, intf_desc.bInterfaceNumber)
+            dev_path = HIDAPI::Device.make_path(usb_dev, intf_desc.bInterfaceNumber)
             if dev_path == path
               if klass != :no_mapping
                 return klass.new(usb_dev, intf_desc.bInterfaceNumber)
@@ -113,8 +158,8 @@ module HIDAPI
 
     ##
     # Opens the device with the specified path.
-    def open_path(path)
-      dev = get_device_by_path(path)
+    def open_path(path, options = {})
+      dev = get_device_by_path(path, options)
       dev.open if dev
     end
 

data/lib/hidapi/errors.rb

@@ -15,4 +15,8 @@ module HIDAPI
   ##
   # An open device is required for the method called.
   DeviceNotOpen = Class.new(HidApiError)
+
+  ##
+  # Device path invalid.
+  DevicePathInvalid = Class.new(HidApiError)
 end

data/lib/hidapi/setup_task_helper.rb

@@ -8,8 +8,8 @@ module HIDAPI
     attr_reader :vendor_id, :product_id, :simple_name, :interface
 
     def initialize(vendor_id, product_id, simple_name, interface)
-      @vendor_id = vendor_id.to_s.strip.to_i(16)
-      @product_id = product_id.to_s.strip.to_i(16)
+      @vendor_id = interpret_id(vendor_id)
+      @product_id = interpret_id(product_id)
       @simple_name = simple_name.to_s.strip.gsub(' ', '_').gsub(/[^A-Za-z0-9_\-]/, '')
       @interface = interface.to_s.strip.to_i
       @temp_dir = Dir.mktmpdir('hidapi_setup')
@@ -229,6 +229,11 @@ LABEL="hidapi_rules_end"
       true
     end
 
+    private
+
+    def interpret_id(id)
+      id.is_a?(Integer) ? id : id.to_s.strip.to_i(16)
+    end
   end
 end
 

data/lib/hidapi/version.rb

@@ -1,3 +1,3 @@
 module HIDAPI
-  VERSION = '0.1.4'
+  VERSION = '0.1.8'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hidapi
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.8
 platform: ruby
 authors:
 - Beau Barker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-08-09 00:00:00.000000000 Z
+date: 2016-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: libusb