usb-ruby 0.1.0

data/lib/usb/device.rb

@@ -0,0 +1,134 @@
+# frozen_string_literal: true
+
+module USB
+  class Device
+    include Comparable
+
+    attr_reader :context
+
+    def self.finalizer(ptr)
+      proc do
+        FFIBindings.libusb_unref_device(ptr) unless ptr.nil? || ptr.null?
+      rescue StandardError
+      end
+    end
+
+    def initialize(context, ptr, ref: true)
+      raise ArgumentError, "device pointer is required" if ptr.nil? || ptr.null?
+
+      @context = context
+      @ptr = ptr
+      @owns_ref = ref
+
+      FFIBindings.libusb_ref_device(@ptr) if @owns_ref
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@ptr)) if @owns_ref
+    end
+
+    def bus_number
+      FFIBindings.libusb_get_bus_number(@ptr)
+    end
+
+    def device_address
+      FFIBindings.libusb_get_device_address(@ptr)
+    end
+
+    def port_number
+      FFIBindings.libusb_get_port_number(@ptr)
+    end
+
+    def port_numbers
+      buffer = FFI::MemoryPointer.new(:uint8, 16)
+      count = Error.raise_on_error(FFIBindings.libusb_get_port_numbers(@ptr, buffer, 16))
+      buffer.read_array_of_uint8(count)
+    end
+
+    def speed
+      Error.raise_on_error(FFIBindings.libusb_get_device_speed(@ptr))
+    end
+
+    def max_packet_size(endpoint)
+      Error.raise_on_error(FFIBindings.libusb_get_max_packet_size(@ptr, endpoint))
+    end
+
+    def max_iso_packet_size(endpoint)
+      Error.raise_on_error(FFIBindings.libusb_get_max_iso_packet_size(@ptr, endpoint))
+    end
+
+    def parent
+      parent_ptr = FFIBindings.libusb_get_parent(@ptr)
+      return nil if parent_ptr.null?
+
+      Device.new(@context, parent_ptr)
+    end
+
+    def device_descriptor
+      descriptor_ptr = FFI::MemoryPointer.new(FFIBindings::DeviceDescriptorStruct)
+      Error.raise_on_error(FFIBindings.libusb_get_device_descriptor(@ptr, descriptor_ptr))
+      DeviceDescriptor.new(FFIBindings::DeviceDescriptorStruct.new(descriptor_ptr))
+    end
+
+    def vendor_id
+      device_descriptor.vendor_id
+    end
+
+    def product_id
+      device_descriptor.product_id
+    end
+
+    def device_class
+      device_descriptor.device_class
+    end
+
+    def config_descriptors
+      Array.new(device_descriptor.num_configurations) { |index| config_descriptor(index) }
+    end
+
+    def active_config_descriptor
+      fetch_config_descriptor(:libusb_get_active_config_descriptor)
+    end
+
+    def config_descriptor(index)
+      fetch_config_descriptor(:libusb_get_config_descriptor, index)
+    end
+
+    def config_descriptor_by_value(value)
+      fetch_config_descriptor(:libusb_get_config_descriptor_by_value, value)
+    end
+
+    def open
+      handle_ptr = FFI::MemoryPointer.new(:pointer)
+      Error.raise_on_error(FFIBindings.libusb_open(@ptr, handle_ptr))
+      handle = DeviceHandle.new(handle_ptr.read_pointer)
+      return handle unless block_given?
+
+      begin
+        yield handle
+      ensure
+        handle.close
+      end
+    end
+
+    def <=>(other)
+      [bus_number, device_address] <=> [other.bus_number, other.device_address]
+    end
+
+    def inspect
+      ids = format("%04x:%04x", vendor_id, product_id)
+      format("#<USB::Device %03d/%03d %s>", bus_number, device_address, ids)
+    rescue StandardError
+      format("#<USB::Device %03d/%03d>", bus_number, device_address)
+    end
+
+    def to_ptr
+      @ptr
+    end
+
+    private
+
+    def fetch_config_descriptor(function_name, *args)
+      descriptor_ptr = FFI::MemoryPointer.new(:pointer)
+      Error.raise_on_error(FFIBindings.public_send(function_name, @ptr, *args, descriptor_ptr))
+      ConfigDescriptor.new(descriptor_ptr.read_pointer)
+    end
+  end
+end

data/lib/usb/device_descriptor.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module USB
+  class DeviceDescriptor
+    def initialize(struct)
+      @struct = struct
+    end
+
+    def bcd_usb
+      @struct[:bcdUSB]
+    end
+
+    def device_class
+      @struct[:bDeviceClass]
+    end
+
+    def device_sub_class
+      @struct[:bDeviceSubClass]
+    end
+
+    def device_protocol
+      @struct[:bDeviceProtocol]
+    end
+
+    def max_packet_size_0
+      @struct[:bMaxPacketSize0]
+    end
+
+    def vendor_id
+      @struct[:idVendor]
+    end
+
+    def product_id
+      @struct[:idProduct]
+    end
+
+    def bcd_device
+      @struct[:bcdDevice]
+    end
+
+    def manufacturer_index
+      @struct[:iManufacturer]
+    end
+
+    def product_index
+      @struct[:iProduct]
+    end
+
+    def serial_number_index
+      @struct[:iSerialNumber]
+    end
+
+    def num_configurations
+      @struct[:bNumConfigurations]
+    end
+
+    def inspect
+      format("#<USB::DeviceDescriptor %04x:%04x class=0x%02x>", vendor_id, product_id, device_class)
+    end
+  end
+end

data/lib/usb/device_handle.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module USB
+  class DeviceHandle
+    def self.finalizer(ptr)
+      proc do
+        FFIBindings.libusb_close(ptr) unless ptr.nil? || ptr.null?
+      rescue StandardError
+      end
+    end
+
+    def initialize(device_or_ptr)
+      @ptr =
+        case device_or_ptr
+        when Device
+          open_device(device_or_ptr)
+        when FFI::Pointer
+          device_or_ptr
+        else
+          raise ArgumentError, "expected USB::Device or FFI::Pointer"
+        end
+
+      raise ArgumentError, "device handle pointer is required" if @ptr.nil? || @ptr.null?
+
+      @device = device_or_ptr if device_or_ptr.is_a?(Device)
+      ObjectSpace.define_finalizer(self, self.class.finalizer(@ptr))
+    end
+
+    def close
+      return if closed?
+
+      ObjectSpace.undefine_finalizer(self)
+      FFIBindings.libusb_close(@ptr)
+      @ptr = FFI::Pointer::NULL
+    end
+
+    def closed?
+      @ptr.nil? || @ptr.null?
+    end
+
+    def device
+      @device ||= begin
+        device_ptr = FFIBindings.libusb_get_device(@ptr)
+        device_ptr.null? ? nil : Device.new(nil, device_ptr)
+      end
+    end
+
+    def configuration
+      configuration_ptr = FFI::MemoryPointer.new(:int)
+      Error.raise_on_error(FFIBindings.libusb_get_configuration(@ptr, configuration_ptr))
+      configuration_ptr.read_int
+    end
+
+    def configuration=(value)
+      Error.raise_on_error(FFIBindings.libusb_set_configuration(@ptr, value))
+    end
+
+    def claim_interface(number)
+      Error.raise_on_error(FFIBindings.libusb_claim_interface(@ptr, number))
+      self
+    end
+
+    def release_interface(number)
+      Error.raise_on_error(FFIBindings.libusb_release_interface(@ptr, number))
+      self
+    end
+
+    def set_interface_alt_setting(interface, alt_setting)
+      Error.raise_on_error(FFIBindings.libusb_set_interface_alt_setting(@ptr, interface, alt_setting))
+      self
+    end
+
+    def clear_halt(endpoint)
+      Error.raise_on_error(FFIBindings.libusb_clear_halt(@ptr, endpoint))
+      self
+    end
+
+    def reset_device
+      Error.raise_on_error(FFIBindings.libusb_reset_device(@ptr))
+      self
+    end
+
+    def kernel_driver_active?(interface)
+      result = FFIBindings.libusb_kernel_driver_active(@ptr, interface)
+      Error.raise_on_error(result) == 1
+    end
+
+    def detach_kernel_driver(interface)
+      Error.raise_on_error(FFIBindings.libusb_detach_kernel_driver(@ptr, interface))
+      self
+    end
+
+    def attach_kernel_driver(interface)
+      Error.raise_on_error(FFIBindings.libusb_attach_kernel_driver(@ptr, interface))
+      self
+    end
+
+    def auto_detach_kernel_driver=(enable)
+      Error.raise_on_error(FFIBindings.libusb_set_auto_detach_kernel_driver(@ptr, enable ? 1 : 0))
+    end
+
+    def with_interface(number)
+      claimed = false
+      claim_interface(number)
+      claimed = true
+      yield self
+    ensure
+      release_interface(number) if claimed && !closed?
+    end
+
+    def control_transfer(bm_request_type:, b_request:, w_value:, w_index:, data_or_length: nil, timeout: 1000)
+      if data_or_length.is_a?(Integer)
+        buffer = FFI::MemoryPointer.new(:uint8, [data_or_length, 1].max)
+        transferred = Error.raise_on_error(
+          FFIBindings.libusb_control_transfer(
+            @ptr, bm_request_type, b_request, w_value, w_index, buffer, data_or_length, timeout
+          )
+        )
+        buffer.read_bytes(transferred)
+      else
+        data = data_or_length.nil? ? "".b : data_or_length.to_s.b
+        buffer = bytes_pointer(data)
+        Error.raise_on_error(
+          FFIBindings.libusb_control_transfer(
+            @ptr, bm_request_type, b_request, w_value, w_index, buffer, data.bytesize, timeout
+          )
+        )
+      end
+    end
+
+    def bulk_transfer(endpoint:, data_or_length:, timeout: 1000)
+      transferred = FFI::MemoryPointer.new(:int)
+
+      if data_or_length.is_a?(Integer)
+        buffer = FFI::MemoryPointer.new(:uint8, [data_or_length, 1].max)
+        Error.raise_on_error(FFIBindings.libusb_bulk_transfer(@ptr, endpoint, buffer, data_or_length, transferred, timeout))
+        buffer.read_bytes(transferred.read_int)
+      else
+        data = data_or_length.to_s.b
+        buffer = bytes_pointer(data)
+        Error.raise_on_error(FFIBindings.libusb_bulk_transfer(@ptr, endpoint, buffer, data.bytesize, transferred, timeout))
+        transferred.read_int
+      end
+    end
+
+    def interrupt_transfer(endpoint:, data_or_length:, timeout: 1000)
+      transferred = FFI::MemoryPointer.new(:int)
+
+      if data_or_length.is_a?(Integer)
+        buffer = FFI::MemoryPointer.new(:uint8, [data_or_length, 1].max)
+        Error.raise_on_error(
+          FFIBindings.libusb_interrupt_transfer(@ptr, endpoint, buffer, data_or_length, transferred, timeout)
+        )
+        buffer.read_bytes(transferred.read_int)
+      else
+        data = data_or_length.to_s.b
+        buffer = bytes_pointer(data)
+        Error.raise_on_error(
+          FFIBindings.libusb_interrupt_transfer(@ptr, endpoint, buffer, data.bytesize, transferred, timeout)
+        )
+        transferred.read_int
+      end
+    end
+
+    def string_descriptor_ascii(index)
+      return nil if index.to_i.zero?
+
+      buffer = FFI::MemoryPointer.new(:uint8, 256)
+      length = Error.raise_on_error(FFIBindings.libusb_get_string_descriptor_ascii(@ptr, index, buffer, 256))
+      buffer.read_string_length(length)
+    end
+
+    def manufacturer
+      string_descriptor_ascii(device.device_descriptor.manufacturer_index)
+    end
+
+    def product
+      string_descriptor_ascii(device.device_descriptor.product_index)
+    end
+
+    def serial_number
+      string_descriptor_ascii(device.device_descriptor.serial_number_index)
+    end
+
+    def alloc_streams(num_streams, endpoints)
+      endpoint_ptr = endpoint_array_pointer(endpoints)
+      Error.raise_on_error(FFIBindings.libusb_alloc_streams(@ptr, num_streams, endpoint_ptr, endpoints.length))
+    end
+
+    def free_streams(endpoints)
+      endpoint_ptr = endpoint_array_pointer(endpoints)
+      Error.raise_on_error(FFIBindings.libusb_free_streams(@ptr, endpoint_ptr, endpoints.length))
+    end
+
+    def dev_mem_alloc(length)
+      FFIBindings.libusb_dev_mem_alloc(@ptr, length)
+    end
+
+    def dev_mem_free(buffer, length)
+      Error.raise_on_error(FFIBindings.libusb_dev_mem_free(@ptr, buffer, length))
+    end
+
+    def bos_descriptor
+      descriptor_ptr = FFI::MemoryPointer.new(:pointer)
+      Error.raise_on_error(FFIBindings.libusb_get_bos_descriptor(@ptr, descriptor_ptr))
+      BOSDescriptor.new(descriptor_ptr.read_pointer)
+    end
+
+    def to_ptr
+      @ptr
+    end
+
+    def inspect
+      descriptor = device&.device_descriptor
+      if descriptor
+        format("#<USB::DeviceHandle %04x:%04x>", descriptor.vendor_id, descriptor.product_id)
+      else
+        "#<USB::DeviceHandle>"
+      end
+    rescue StandardError
+      "#<USB::DeviceHandle>"
+    end
+
+    private
+
+    def open_device(device)
+      handle_ptr = FFI::MemoryPointer.new(:pointer)
+      Error.raise_on_error(FFIBindings.libusb_open(device.to_ptr, handle_ptr))
+      handle_ptr.read_pointer
+    end
+
+    def bytes_pointer(data)
+      pointer = FFI::MemoryPointer.new(:uint8, [data.bytesize, 1].max)
+      pointer.put_bytes(0, data) unless data.empty?
+      pointer
+    end
+
+    def endpoint_array_pointer(endpoints)
+      pointer = FFI::MemoryPointer.new(:uint8, endpoints.length)
+      endpoints.each_with_index do |endpoint, index|
+        pointer.put_uint8(index, endpoint)
+      end
+      pointer
+    end
+  end
+end

data/lib/usb/endpoint_descriptor.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module USB
+  class EndpointDescriptor
+    def initialize(interface_descriptor, struct)
+      @interface_descriptor = interface_descriptor
+      @struct = struct
+    end
+
+    def endpoint_address
+      @struct[:bEndpointAddress]
+    end
+
+    def direction
+      in? ? :in : :out
+    end
+
+    def transfer_type
+      case @struct[:bmAttributes] & 0x03
+      when TRANSFER_TYPE_CONTROL then :control
+      when TRANSFER_TYPE_ISOCHRONOUS then :isochronous
+      when TRANSFER_TYPE_BULK then :bulk
+      when TRANSFER_TYPE_INTERRUPT then :interrupt
+      else
+        :unknown
+      end
+    end
+
+    def max_packet_size
+      @struct[:wMaxPacketSize]
+    end
+
+    def interval
+      @struct[:bInterval]
+    end
+
+    def refresh
+      @struct[:bRefresh]
+    end
+
+    def synch_address
+      @struct[:bSynchAddress]
+    end
+
+    def extra
+      return "".b if @struct[:extra].null? || @struct[:extra_length].zero?
+
+      @struct[:extra].read_bytes(@struct[:extra_length])
+    end
+
+    def ss_endpoint_companion(context)
+      descriptor_ptr = FFI::MemoryPointer.new(:pointer)
+      Error.raise_on_error(
+        FFIBindings.libusb_get_ss_endpoint_companion_descriptor(context.to_ptr, @struct.pointer, descriptor_ptr)
+      )
+      SSEndpointCompanion.new(descriptor_ptr.read_pointer)
+    end
+
+    def in?
+      (endpoint_address & ENDPOINT_IN) == ENDPOINT_IN
+    end
+
+    def out?
+      !in?
+    end
+
+    def bulk?
+      transfer_type == :bulk
+    end
+
+    def interrupt?
+      transfer_type == :interrupt
+    end
+
+    def isochronous?
+      transfer_type == :isochronous
+    end
+
+    def control?
+      transfer_type == :control
+    end
+
+    def inspect
+      format("#<USB::EndpointDescriptor 0x%02x %s %s>", endpoint_address, transfer_type, direction)
+    end
+
+    def to_ptr
+      @struct.pointer
+    end
+  end
+end

data/lib/usb/error.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module USB
+  class Error < StandardError
+    attr_reader :code
+
+    ERROR_CLASSES = {}.freeze
+
+    class << self
+      def raise_on_error(result)
+        raise class_for_code(result).new(result) if result.is_a?(Integer) && result.negative?
+
+        result
+      end
+
+      def class_for_code(code)
+        self::ERROR_CLASSES.fetch(code, self)
+      end
+
+      def libusb_error_name(code)
+        FFIBindings.libusb_error_name(code)
+      rescue StandardError
+        code.to_s
+      end
+
+      def libusb_error_description(code)
+        FFIBindings.libusb_strerror(code)
+      rescue StandardError
+        "libusb error #{code}"
+      end
+    end
+
+    def initialize(code)
+      @code = code
+      super("#{self.class.libusb_error_name(code)}: #{self.class.libusb_error_description(code)}")
+    end
+  end
+
+  class TransferError < Error
+  end
+
+  class IOError < Error
+  end
+
+  class InvalidParamError < Error
+  end
+
+  class AccessError < Error
+  end
+
+  class NoDeviceError < Error
+  end
+
+  class NotFoundError < Error
+  end
+
+  class BusyError < Error
+  end
+
+  class TimeoutError < Error
+  end
+
+  class OverflowError < Error
+  end
+
+  class PipeError < Error
+  end
+
+  class InterruptedError < Error
+  end
+
+  class NoMemError < Error
+  end
+
+  class NotSupportedError < Error
+  end
+
+  Error.send(:remove_const, :ERROR_CLASSES)
+  Error::ERROR_CLASSES = {
+    LIBUSB_ERROR_IO => IOError,
+    LIBUSB_ERROR_INVALID_PARAM => InvalidParamError,
+    LIBUSB_ERROR_ACCESS => AccessError,
+    LIBUSB_ERROR_NO_DEVICE => NoDeviceError,
+    LIBUSB_ERROR_NOT_FOUND => NotFoundError,
+    LIBUSB_ERROR_BUSY => BusyError,
+    LIBUSB_ERROR_TIMEOUT => TimeoutError,
+    LIBUSB_ERROR_OVERFLOW => OverflowError,
+    LIBUSB_ERROR_PIPE => PipeError,
+    LIBUSB_ERROR_INTERRUPTED => InterruptedError,
+    LIBUSB_ERROR_NO_MEM => NoMemError,
+    LIBUSB_ERROR_NOT_SUPPORTED => NotSupportedError,
+    LIBUSB_ERROR_OTHER => Error
+  }.freeze
+end