usb-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 57a269f637b918eeb1bba951a051b436458afe412c425165b2c1c7c2b46fdb25
+  data.tar.gz: c5b682b0de82b3579bcf28f45efd92fba56c4e4ac3511fa30d4cc4ffaa2171b8
+SHA512:
+  metadata.gz: a7311cda74c4e9481a0c221e417ae04ebdc9efc70599ab287d9b95ce9f79d222e24eb50b3e44ac1cb43e23f64fac4ba48567f04d384530928431c4858f2b0146
+  data.tar.gz: da4c60df04e25348cc1c1d2d762466d62aff997b480b7767ba3300c9afcb215f0fa7806b105ed98e3832c5fc65d995e84ea08874a7a2f2f5d81c49c39ddbcdc3

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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,52 @@
+# usb-ruby
+
+`usb-ruby` is a Ruby FFI binding for libusb 1.0. It exposes the libusb API through the top-level `USB` module and does not require native extension compilation.
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```bash
+bundle add usb-ruby
+```
+
+Or install it directly:
+
+```bash
+gem install usb-ruby
+```
+
+## Usage
+
+```ruby
+require "usb"
+
+USB::Context.open do |context|
+  context.devices.each do |device|
+    descriptor = device.device_descriptor
+    puts format("%03d/%03d %04x:%04x",
+                device.bus_number,
+                device.device_address,
+                descriptor.vendor_id,
+                descriptor.product_id)
+  end
+end
+```
+
+## Development
+
+Run:
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rake install
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/ydah/usb.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/usb/bos_descriptor.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module USB
+  class BOSDescriptor
+    def self.finalizer(ptr)
+      proc do
+        FFIBindings.libusb_free_bos_descriptor(ptr) unless ptr.nil? || ptr.null?
+      rescue StandardError
+      end
+    end
+
+    def initialize(ptr)
+      raise ArgumentError, "BOS descriptor pointer is required" if ptr.nil? || ptr.null?
+
+      @ptr = ptr
+      @struct = FFIBindings::BOSDescriptorStruct.new(@ptr)
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@ptr))
+    end
+
+    def num_device_caps
+      @struct[:bNumDeviceCaps]
+    end
+
+    def device_capabilities
+      count = num_device_caps
+      base_ptr = @struct[:dev_capability]
+      return [] if base_ptr.null?
+
+      Array.new(count) do |index|
+        capability_ptr = base_ptr.get_pointer(index * FFI::Pointer.size)
+        BOSDevCapability.new(capability_ptr, self)
+      end
+    end
+
+    def close
+      return if @ptr.nil? || @ptr.null?
+
+      ObjectSpace.undefine_finalizer(self)
+      FFIBindings.libusb_free_bos_descriptor(@ptr)
+      @ptr = FFI::Pointer::NULL
+      @struct = nil
+    end
+
+    alias free close
+
+    def to_ptr
+      @ptr
+    end
+
+    def inspect
+      "#<USB::BOSDescriptor device_caps=#{num_device_caps}>"
+    end
+  end
+end

data/lib/usb/bos_dev_capability.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module USB
+  class BOSDevCapability
+    def initialize(ptr, bos_descriptor = nil)
+      raise ArgumentError, "BOS capability pointer is required" if ptr.nil? || ptr.null?
+
+      @bos_descriptor = bos_descriptor
+      @ptr = ptr
+      @struct = FFIBindings::BOSDevCapabilityStruct.new(@ptr)
+    end
+
+    def capability_type
+      @struct[:bDevCapabilityType]
+    end
+
+    def data
+      length = @struct[:bLength] - 3
+      return "".b if length <= 0
+
+      (@ptr + 3).read_bytes(length)
+    end
+
+    def usb_2_0_extension(context)
+      fetch_descriptor(context, :libusb_get_usb_2_0_extension_descriptor, USB20Extension)
+    end
+
+    def ss_device_capability(context)
+      fetch_descriptor(context, :libusb_get_ss_usb_device_capability_descriptor, SSDeviceCapability)
+    end
+
+    def container_id(context)
+      fetch_descriptor(context, :libusb_get_container_id_descriptor, ContainerID)
+    end
+
+    def inspect
+      "#<USB::BOSDevCapability type=#{capability_type}>"
+    end
+
+    private
+
+    def fetch_descriptor(context, function_name, klass)
+      descriptor_ptr = FFI::MemoryPointer.new(:pointer)
+      Error.raise_on_error(FFIBindings.public_send(function_name, context.to_ptr, @ptr, descriptor_ptr))
+      klass.new(descriptor_ptr.read_pointer)
+    end
+  end
+end

data/lib/usb/config_descriptor.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module USB
+  class ConfigDescriptor
+    include Enumerable
+
+    def self.finalizer(ptr)
+      proc do
+        FFIBindings.libusb_free_config_descriptor(ptr) unless ptr.nil? || ptr.null?
+      rescue StandardError
+      end
+    end
+
+    def initialize(ptr)
+      raise ArgumentError, "config descriptor pointer is required" if ptr.nil? || ptr.null?
+
+      @ptr = ptr
+      @struct = FFIBindings::ConfigDescriptorStruct.new(@ptr)
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@ptr))
+    end
+
+    def configuration_value
+      @struct[:bConfigurationValue]
+    end
+
+    def description_index
+      @struct[:iConfiguration]
+    end
+
+    def attributes
+      @struct[:bmAttributes]
+    end
+
+    def max_power
+      @struct[:MaxPower]
+    end
+
+    def num_interfaces
+      @struct[:bNumInterfaces]
+    end
+
+    def interfaces
+      count = num_interfaces
+      base_ptr = @struct[:interface]
+      return [] if base_ptr.null?
+
+      Array.new(count) do |index|
+        offset = index * FFIBindings::InterfaceStruct.size
+        Interface.new(self, FFIBindings::InterfaceStruct.new(base_ptr + offset))
+      end
+    end
+
+    def each(&block)
+      interfaces.each(&block)
+    end
+
+    def extra
+      read_extra(@struct[:extra], @struct[:extra_length])
+    end
+
+    def self_powered?
+      (attributes & 0x40) != 0
+    end
+
+    def remote_wakeup?
+      (attributes & 0x20) != 0
+    end
+
+    def close
+      return if @ptr.nil? || @ptr.null?
+
+      ObjectSpace.undefine_finalizer(self)
+      FFIBindings.libusb_free_config_descriptor(@ptr)
+      @ptr = FFI::Pointer::NULL
+      @struct = nil
+    end
+
+    def inspect
+      "#<USB::ConfigDescriptor value=#{configuration_value} interfaces=#{num_interfaces}>"
+    end
+
+    def to_ptr
+      @ptr
+    end
+
+    private
+
+    def read_extra(ptr, length)
+      return "".b if ptr.null? || length.zero?
+
+      ptr.read_bytes(length)
+    end
+  end
+end

data/lib/usb/constants.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module USB
+  LIBUSB_SUCCESS = 0
+  LIBUSB_ERROR_IO = -1
+  LIBUSB_ERROR_INVALID_PARAM = -2
+  LIBUSB_ERROR_ACCESS = -3
+  LIBUSB_ERROR_NO_DEVICE = -4
+  LIBUSB_ERROR_NOT_FOUND = -5
+  LIBUSB_ERROR_BUSY = -6
+  LIBUSB_ERROR_TIMEOUT = -7
+  LIBUSB_ERROR_OVERFLOW = -8
+  LIBUSB_ERROR_PIPE = -9
+  LIBUSB_ERROR_INTERRUPTED = -10
+  LIBUSB_ERROR_NO_MEM = -11
+  LIBUSB_ERROR_NOT_SUPPORTED = -12
+  LIBUSB_ERROR_OTHER = -99
+
+  TRANSFER_COMPLETED = 0
+  TRANSFER_ERROR = 1
+  TRANSFER_TIMED_OUT = 2
+  TRANSFER_CANCELLED = 3
+  TRANSFER_STALL = 4
+  TRANSFER_NO_DEVICE = 5
+  TRANSFER_OVERFLOW = 6
+
+  TRANSFER_TYPE_CONTROL = 0
+  TRANSFER_TYPE_ISOCHRONOUS = 1
+  TRANSFER_TYPE_BULK = 2
+  TRANSFER_TYPE_INTERRUPT = 3
+  TRANSFER_TYPE_BULK_STREAM = 4
+
+  TRANSFER_SHORT_NOT_OK = 1 << 0
+  TRANSFER_FREE_BUFFER = 1 << 1
+  TRANSFER_FREE_TRANSFER = 1 << 2
+  TRANSFER_ADD_ZERO_PACKET = 1 << 3
+
+  ENDPOINT_IN = 0x80
+  ENDPOINT_OUT = 0x00
+
+  REQUEST_TYPE_STANDARD = 0x00 << 5
+  REQUEST_TYPE_CLASS = 0x01 << 5
+  REQUEST_TYPE_VENDOR = 0x02 << 5
+  REQUEST_TYPE_RESERVED = 0x03 << 5
+
+  RECIPIENT_DEVICE = 0x00
+  RECIPIENT_INTERFACE = 0x01
+  RECIPIENT_ENDPOINT = 0x02
+  RECIPIENT_OTHER = 0x03
+
+  REQUEST_GET_STATUS = 0x00
+  REQUEST_CLEAR_FEATURE = 0x01
+  REQUEST_SET_FEATURE = 0x03
+  REQUEST_SET_ADDRESS = 0x05
+  REQUEST_GET_DESCRIPTOR = 0x06
+  REQUEST_SET_DESCRIPTOR = 0x07
+  REQUEST_GET_CONFIGURATION = 0x08
+  REQUEST_SET_CONFIGURATION = 0x09
+  REQUEST_GET_INTERFACE = 0x0A
+  REQUEST_SET_INTERFACE = 0x0B
+  REQUEST_SYNCH_FRAME = 0x0C
+  REQUEST_SET_SEL = 0x30
+  REQUEST_SET_ISOCH_DELAY = 0x31
+
+  DT_DEVICE = 0x01
+  DT_CONFIG = 0x02
+  DT_STRING = 0x03
+  DT_INTERFACE = 0x04
+  DT_ENDPOINT = 0x05
+  DT_BOS = 0x0F
+  DT_DEVICE_CAPABILITY = 0x10
+  DT_SS_ENDPOINT_COMPANION = 0x30
+  DT_SUPERSPEED_HUB = 0x2A
+
+  CLASS_PER_INTERFACE = 0x00
+  CLASS_AUDIO = 0x01
+  CLASS_COMM = 0x02
+  CLASS_HID = 0x03
+  CLASS_PHYSICAL = 0x05
+  CLASS_IMAGE = 0x06
+  CLASS_PRINTER = 0x07
+  CLASS_MASS_STORAGE = 0x08
+  CLASS_HUB = 0x09
+  CLASS_DATA = 0x0A
+  CLASS_SMART_CARD = 0x0B
+  CLASS_CONTENT_SECURITY = 0x0D
+  CLASS_VIDEO = 0x0E
+  CLASS_PERSONAL_HEALTHCARE = 0x0F
+  CLASS_DIAGNOSTIC_DEVICE = 0xDC
+  CLASS_WIRELESS = 0xE0
+  CLASS_MISCELLANEOUS = 0xEF
+  CLASS_APPLICATION = 0xFE
+  CLASS_VENDOR_SPEC = 0xFF
+
+  SPEED_UNKNOWN = 0
+  SPEED_LOW = 1
+  SPEED_FULL = 2
+  SPEED_HIGH = 3
+  SPEED_SUPER = 4
+  SPEED_SUPER_PLUS = 5
+
+  LOG_LEVEL_NONE = 0
+  LOG_LEVEL_ERROR = 1
+  LOG_LEVEL_WARNING = 2
+  LOG_LEVEL_INFO = 3
+  LOG_LEVEL_DEBUG = 4
+
+  HOTPLUG_EVENT_DEVICE_ARRIVED = 0x01
+  HOTPLUG_EVENT_DEVICE_LEFT = 0x02
+
+  HOTPLUG_ENUMERATE = 1 << 0
+  HOTPLUG_MATCH_ANY = -1
+
+  CAP_HAS_CAPABILITY = 0x0000
+  CAP_HAS_HOTPLUG = 0x0001
+  CAP_HAS_HID_ACCESS = 0x0100
+  CAP_SUPPORTS_DETACH_KERNEL_DRIVER = 0x0101
+
+  OPTION_LOG_LEVEL = 0
+  OPTION_USE_USBDK = 1
+  OPTION_NO_DEVICE_DISCOVERY = 2
+  OPTION_LOG_CB = 3
+
+  BT_WIRELESS_USB_DEVICE_CAPABILITY = 1
+  BT_USB_2_0_EXTENSION = 2
+  BT_SS_USB_DEVICE_CAPABILITY = 3
+  BT_CONTAINER_ID = 4
+  BT_PLATFORM_DESCRIPTOR = 5
+end

data/lib/usb/container_id.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module USB
+  class ContainerID
+    def self.finalizer(ptr)
+      proc do
+        FFIBindings.libusb_free_container_id_descriptor(ptr) unless ptr.nil? || ptr.null?
+      rescue StandardError
+      end
+    end
+
+    def initialize(ptr)
+      raise ArgumentError, "container ID pointer is required" if ptr.nil? || ptr.null?
+
+      @ptr = ptr
+      @struct = FFIBindings::ContainerIDStruct.new(@ptr)
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@ptr))
+    end
+
+    def container_id
+      @struct[:ContainerID].to_a
+    end
+
+    def close
+      return if @ptr.nil? || @ptr.null?
+
+      ObjectSpace.undefine_finalizer(self)
+      FFIBindings.libusb_free_container_id_descriptor(@ptr)
+      @ptr = FFI::Pointer::NULL
+      @struct = nil
+    end
+
+    alias free close
+
+    def to_ptr
+      @ptr
+    end
+
+    def inspect
+      "#<USB::ContainerID #{container_id.map { |byte| format('%02x', byte) }.join}>"
+    end
+  end
+end

data/lib/usb/context.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module USB
+  class Context
+    attr_reader :ptr
+
+    def self.open(**options)
+      context = new(**options)
+      return context unless block_given?
+
+      begin
+        yield context
+      ensure
+        context.close
+      end
+    end
+
+    def self.finalizer(ptr)
+      proc do
+        FFIBindings.libusb_exit(ptr) unless ptr.nil? || ptr.null?
+      rescue StandardError
+      end
+    end
+
+    def initialize(options: nil, **kwargs)
+      FFIBindings.ensure_loaded!
+      options = (options || {}).merge(kwargs)
+
+      context_ptr = FFI::MemoryPointer.new(:pointer)
+
+      if !options.empty? && FFIBindings.function_available?(:libusb_init_context)
+        Error.raise_on_error(FFIBindings.libusb_init_context(context_ptr, nil, 0))
+      else
+        Error.raise_on_error(FFIBindings.libusb_init(context_ptr))
+      end
+
+      @ptr = context_ptr.read_pointer
+      @closed = false
+      @hotplug_callbacks = {}
+      @pollfd_notifiers = {}
+
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@ptr))
+
+      options.each do |option, value|
+        set_option(option, value)
+      end
+    end
+
+    def close
+      return if closed?
+
+      ObjectSpace.undefine_finalizer(self)
+      @hotplug_callbacks.keys.each { |handle| deregister_hotplug(handle) }
+      FFIBindings.libusb_exit(@ptr)
+      @ptr = FFI::Pointer::NULL
+      @closed = true
+    end
+
+    def closed?
+      @closed || @ptr.nil? || @ptr.null?
+    end
+
+    def devices(vendor_id: nil, product_id: nil, device_class: nil)
+      all = raw_device_list
+      all.select! { |device| device.vendor_id == vendor_id } unless vendor_id.nil?
+      all.select! { |device| device.product_id == product_id } unless product_id.nil?
+      all.select! { |device| device.device_class == device_class } unless device_class.nil?
+      all
+    end
+
+    def open_device(vendor_id:, product_id:)
+      handle_ptr = FFIBindings.libusb_open_device_with_vid_pid(@ptr, vendor_id, product_id)
+      return nil if handle_ptr.null?
+
+      handle = DeviceHandle.new(handle_ptr)
+      return handle unless block_given?
+
+      begin
+        yield handle
+      ensure
+        handle.close
+      end
+    end
+
+    def set_option(option, value = nil)
+      normalized_option = normalize_option(option)
+
+      if FFIBindings.function_available?(:libusb_set_option)
+        result =
+          if value.nil?
+            FFIBindings.libusb_set_option(@ptr, normalized_option)
+          else
+            FFIBindings.libusb_set_option(@ptr, normalized_option, :int, value)
+          end
+
+        Error.raise_on_error(result)
+      elsif normalized_option == OPTION_LOG_LEVEL && !value.nil?
+        FFIBindings.libusb_set_debug(@ptr, value)
+      else
+        raise NotImplementedError, "libusb_set_option is not available"
+      end
+    rescue ArgumentError
+      raise unless normalized_option == OPTION_LOG_LEVEL && !value.nil?
+
+      FFIBindings.libusb_set_debug(@ptr, value)
+    end
+
+    def debug=(level)
+      set_option(OPTION_LOG_LEVEL, level)
+    end
+
+    def has_capability?(capability)
+      FFIBindings.libusb_has_capability(capability) != 0
+    end
+
+    def to_ptr
+      @ptr
+    end
+
+    private
+
+    def raw_device_list
+      list_ptr = FFI::MemoryPointer.new(:pointer)
+      count = Error.raise_on_error(FFIBindings.libusb_get_device_list(@ptr, list_ptr))
+      base_ptr = list_ptr.read_pointer
+
+      Array.new(count) do |index|
+        device_ptr = base_ptr.get_pointer(index * FFI::Pointer.size)
+        Device.new(self, device_ptr)
+      end
+    ensure
+      if defined?(base_ptr) && base_ptr && !base_ptr.null?
+        FFIBindings.libusb_free_device_list(base_ptr, 1)
+      end
+    end
+
+    def normalize_option(option)
+      case option
+      when :log_level then OPTION_LOG_LEVEL
+      when :use_usbdk then OPTION_USE_USBDK
+      when :no_device_discovery then OPTION_NO_DEVICE_DISCOVERY
+      when :log_callback then OPTION_LOG_CB
+      else
+        option
+      end
+    end
+  end
+end