usbkit 0.1.0

data/lib/usbkit/backend/usb_ruby.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+begin
+  require "usb"
+rescue LoadError
+  nil
+end
+
+require_relative "base"
+
+module UsbKit
+  module Backend
+    class UsbRuby < Base
+    end
+  end
+end
+
+require_relative "usb_ruby/device_wrapper"
+
+module UsbKit
+  module Backend
+    ##
+    # usb-ruby backed implementation of the UsbKit backend contract.
+    #
+    class UsbRuby
+      REQUEST_TYPE_BITS = {
+        standard: 0x00,
+        class: 0x20,
+        vendor: 0x40
+      }.freeze
+
+      RECIPIENT_BITS = {
+        device: 0x00,
+        interface: 0x01,
+        endpoint: 0x02,
+        other: 0x03
+      }.freeze
+
+      # @param usb_context [Object, nil]
+      # @param mutex [Mutex]
+      # @raise [BackendNotAvailableError] when usb-ruby is not available
+      # @return [void]
+      def initialize(usb_context: nil, mutex: Mutex.new)
+        raise BackendNotAvailableError, "usb-ruby backend not available" unless defined?(USB::Context)
+
+        @mutex = mutex
+        @usb_context = usb_context || USB::Context.new
+      end
+
+      # @return [void]
+      def finalize
+        synchronize do
+          @usb_context&.close if @usb_context.respond_to?(:close)
+        end
+      end
+
+      # @return [Array<Hash>]
+      def enumerate_devices
+        synchronize do
+          Array(@usb_context.devices).map { |usb_device| DeviceWrapper.new(usb_device).to_h }
+        end
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param raw_device [Object]
+      # @return [Object]
+      def open_device(raw_device)
+        synchronize { raw_device.open }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @return [void]
+      def close_device(device_handle)
+        synchronize { device_handle.close }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param config_value [Integer]
+      # @return [void]
+      def set_configuration(device_handle, config_value)
+        synchronize { device_handle.set_configuration(config_value) }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param interface_number [Integer]
+      # @return [void]
+      def claim_interface(device_handle, interface_number)
+        synchronize { device_handle.claim_interface(interface_number) }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param interface_number [Integer]
+      # @return [void]
+      def release_interface(device_handle, interface_number)
+        synchronize { device_handle.release_interface(interface_number) }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param interface_number [Integer]
+      # @param alternate_setting [Integer]
+      # @return [void]
+      def set_alternate_interface(device_handle, interface_number, alternate_setting)
+        synchronize { device_handle.set_interface_alt_setting(interface_number, alternate_setting) }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param setup [Hash]
+      # @param length [Integer]
+      # @return [Hash]
+      def control_transfer_in(device_handle, setup, length)
+        response = synchronize do
+          device_handle.control_transfer(
+            bmRequestType: build_request_type(setup, :in),
+            bRequest: setup[:request],
+            wValue: setup[:value],
+            wIndex: setup[:index],
+            dataIn: length
+          )
+        end
+
+        { status: TransferStatus::OK, data: response }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param setup [Hash]
+      # @param data [String, nil]
+      # @return [Hash]
+      def control_transfer_out(device_handle, setup, data)
+        bytes_written = synchronize do
+          params = {
+            bmRequestType: build_request_type(setup, :out),
+            bRequest: setup[:request],
+            wValue: setup[:value],
+            wIndex: setup[:index]
+          }
+          params[:dataOut] = data if data
+          device_handle.control_transfer(**params)
+        end
+
+        { status: TransferStatus::OK, bytes_written: bytes_written || data&.bytesize.to_i }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param endpoint [Integer]
+      # @param length [Integer]
+      # @param timeout [Integer]
+      # @return [Hash]
+      def bulk_transfer_in(device_handle, endpoint, length, timeout:)
+        data = synchronize do
+          device_handle.bulk_transfer(
+            endpoint: endpoint | 0x80,
+            dataIn: length,
+            timeout: timeout
+          )
+        end
+
+        { status: TransferStatus::OK, data: data }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param endpoint [Integer]
+      # @param data [String]
+      # @param timeout [Integer]
+      # @return [Hash]
+      def bulk_transfer_out(device_handle, endpoint, data, timeout:)
+        bytes_written = synchronize do
+          device_handle.bulk_transfer(
+            endpoint: endpoint,
+            dataOut: data,
+            timeout: timeout
+          )
+        end
+
+        { status: TransferStatus::OK, bytes_written: bytes_written || data.bytesize }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param endpoint [Integer]
+      # @param packet_lengths [Array<Integer>]
+      # @raise [NotImplementedError] when usb-ruby has no isochronous support
+      # @return [Hash]
+      def isochronous_transfer_in(device_handle, endpoint, packet_lengths)
+        raise NotImplementedError, "isochronous transfers require usb-ruby isochronous support" unless device_handle.respond_to?(:isochronous_transfer)
+
+        transfer = synchronize do
+          device_handle.isochronous_transfer(endpoint: endpoint | 0x80, packet_lengths: packet_lengths)
+        end
+
+        {
+          data: transfer[:data],
+          packets: Array(transfer[:packets]).map { |packet| packet.merge(status: packet.fetch(:status, TransferStatus::OK)) }
+        }
+      rescue NotImplementedError
+        raise
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param endpoint [Integer]
+      # @param data [String]
+      # @param packet_lengths [Array<Integer>]
+      # @raise [NotImplementedError] when usb-ruby has no isochronous support
+      # @return [Hash]
+      def isochronous_transfer_out(device_handle, endpoint, data, packet_lengths)
+        raise NotImplementedError, "isochronous transfers require usb-ruby isochronous support" unless device_handle.respond_to?(:isochronous_transfer)
+
+        transfer = synchronize do
+          device_handle.isochronous_transfer(
+            endpoint: endpoint,
+            dataOut: data,
+            packet_lengths: packet_lengths
+          )
+        end
+
+        {
+          packets: Array(transfer[:packets]).map do |packet|
+            packet.merge(status: packet.fetch(:status, TransferStatus::OK))
+          end
+        }
+      rescue NotImplementedError
+        raise
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @param endpoint [Integer]
+      # @return [void]
+      def clear_halt(device_handle, endpoint)
+        synchronize { device_handle.clear_halt(endpoint) }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param device_handle [Object]
+      # @return [void]
+      def reset_device(device_handle)
+        synchronize { device_handle.reset_device }
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param raw_device [Object]
+      # @return [Hash]
+      def get_device_descriptor(raw_device)
+        DeviceWrapper.new(raw_device).to_h
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      # @param raw_device [Object]
+      # @param index [Integer]
+      # @return [Object]
+      def get_configuration_descriptor(raw_device, index)
+        synchronize do
+          if raw_device.respond_to?(:config_descriptor)
+            raw_device.config_descriptor(index)
+          else
+            Array(raw_device.configurations).fetch(index)
+          end
+        end
+      rescue StandardError => error
+        raise map_error(error)
+      end
+
+      private
+
+      def synchronize(&block)
+        @mutex.synchronize(&block)
+      end
+
+      def build_request_type(setup, direction)
+        direction_bit = direction == :in ? 0x80 : 0x00
+        direction_bit | REQUEST_TYPE_BITS.fetch(setup[:request_type]) | RECIPIENT_BITS.fetch(setup[:recipient])
+      end
+
+      def map_error(error)
+        return error if error.is_a?(UsbKit::Error)
+
+        message = error.message.to_s
+        lowered = message.downcase
+
+        return TimeoutError.new(message) if lowered.include?("timeout")
+        return DeviceBusyError.new(message) if lowered.include?("busy")
+        return DeviceAccessError.new(message) if lowered.include?("access") || lowered.include?("permission")
+        return DeviceNotFoundError.new(message) if lowered.include?("not found")
+        return TransferError.new(message, status: :stall) if lowered.include?("stall")
+        return TransferError.new(message, status: :babble) if lowered.include?("babble")
+
+        Error.new(message.empty? ? error.class.name : message)
+      end
+    end
+  end
+end

data/lib/usbkit/backend/usbfs/ioctl_commands.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module UsbKit
+  module Backend
+    class Usbfs
+      USBDEVFS_CONTROL = 0xC0185500
+      USBDEVFS_BULK = 0xC0185502
+      USBDEVFS_SETINTF = 0x80085504
+      USBDEVFS_SETCONFIG = 0x80045505
+      USBDEVFS_CLAIMINTF = 0x8004550F
+      USBDEVFS_RELEASEINTF = 0x80045510
+      USBDEVFS_CLEAR_HALT = 0x80045515
+      USBDEVFS_RESET = 0x00005514
+    end
+  end
+end

data/lib/usbkit/backend/usbfs/sysfs_reader.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module UsbKit
+  module Backend
+    class Usbfs
+      ##
+      # Reads USB device metadata from Linux sysfs.
+      #
+      class SysfsReader
+        SYSFS_PATH = "/sys/bus/usb/devices"
+
+        # @param sysfs_path [String]
+        # @return [void]
+        def initialize(sysfs_path: SYSFS_PATH)
+          @sysfs_path = sysfs_path
+        end
+
+        # @return [Array<Hash>]
+        def enumerate
+          Dir.glob(File.join(@sysfs_path, "[0-9]*-[0-9]*")).filter_map do |path|
+            next unless File.exist?(File.join(path, "idVendor"))
+
+            read_device_info(path)
+          end
+        end
+
+        private
+
+        def read_device_info(path)
+          {
+            raw_device: {
+              sysfs_path: path,
+              dev_path: derive_dev_path(path)
+            },
+            vendor_id: read_hex(path, "idVendor"),
+            product_id: read_hex(path, "idProduct"),
+            device_class: read_hex(path, "bDeviceClass"),
+            device_subclass: read_hex(path, "bDeviceSubClass"),
+            device_protocol: read_hex(path, "bDeviceProtocol"),
+            device_version_major: bcd_major(read_hex(path, "bcdDevice")),
+            device_version_minor: bcd_minor(read_hex(path, "bcdDevice")),
+            device_version_subminor: bcd_subminor(read_hex(path, "bcdDevice")),
+            usb_version_major: bcd_major(read_hex(path, "version")),
+            usb_version_minor: bcd_minor(read_hex(path, "version")),
+            usb_version_subminor: bcd_subminor(read_hex(path, "version")),
+            manufacturer_name: read_string(path, "manufacturer"),
+            product_name: read_string(path, "product"),
+            serial_number: read_string(path, "serial"),
+            configurations: [],
+            configuration_value: nil,
+            bus_number: read_decimal(path, "busnum"),
+            device_address: read_decimal(path, "devnum")
+          }
+        end
+
+        def derive_dev_path(path)
+          bus_number = read_decimal(path, "busnum")
+          device_number = read_decimal(path, "devnum")
+          return nil unless bus_number && device_number
+
+          format("/dev/bus/usb/%<bus>03d/%<device>03d", bus: bus_number, device: device_number)
+        end
+
+        def read_hex(path, attr)
+          content = read_string(path, attr)
+          return 0 if content.nil? || content.empty?
+
+          content.include?(".") ? decimal_version_to_bcd(content) : content.to_i(16)
+        end
+
+        def read_decimal(path, attr)
+          Integer(read_string(path, attr), 10)
+        rescue ArgumentError, TypeError
+          nil
+        end
+
+        def read_string(path, attr)
+          File.read(File.join(path, attr)).strip
+        rescue Errno::ENOENT
+          nil
+        end
+
+        def decimal_version_to_bcd(content)
+          major, minor = content.split(".", 2)
+          ((major.to_i & 0xFF) << 8) | ((minor.to_i & 0x0F) << 4)
+        end
+
+        def bcd_major(value)
+          (value >> 8) & 0xFF
+        end
+
+        def bcd_minor(value)
+          (value >> 4) & 0x0F
+        end
+
+        def bcd_subminor(value)
+          value & 0x0F
+        end
+      end
+    end
+  end
+end

data/lib/usbkit/backend/usbfs.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module UsbKit
+  module Backend
+    class Usbfs < Base
+    end
+  end
+end
+
+require_relative "usbfs/ioctl_commands"
+require_relative "usbfs/sysfs_reader"
+
+module UsbKit
+  module Backend
+    ##
+    # Linux usbfs fallback backend.
+    #
+    class Usbfs
+      REQUEST_TYPE_BITS = {
+        standard: 0x00,
+        class: 0x20,
+        vendor: 0x40
+      }.freeze
+
+      RECIPIENT_BITS = {
+        device: 0x00,
+        interface: 0x01,
+        endpoint: 0x02,
+        other: 0x03
+      }.freeze
+
+      # @param sysfs_reader [SysfsReader]
+      # @param file_class [Class]
+      # @param linux [Boolean]
+      # @raise [BackendNotAvailableError] unless running on Linux
+      # @return [void]
+      def initialize(sysfs_reader: SysfsReader.new, file_class: File, linux: RUBY_PLATFORM.match?(/linux/i))
+        raise BackendNotAvailableError, "usbfs backend is only available on Linux" unless linux
+
+        @sysfs_reader = sysfs_reader
+        @file_class = file_class
+      end
+
+      # @return [Array<Hash>]
+      def enumerate_devices
+        @sysfs_reader.enumerate
+      end
+
+      # @param raw_device [Hash, String]
+      # @raise [DeviceAccessError, DeviceNotFoundError]
+      # @return [File]
+      def open_device(raw_device)
+        path = raw_device.is_a?(Hash) ? raw_device[:dev_path] : raw_device
+        raise DeviceNotFoundError, "usbfs device path is unavailable" unless path
+
+        @file_class.open(path, "rb+")
+      rescue Errno::EACCES => error
+        raise DeviceAccessError, error.message
+      rescue Errno::ENOENT => error
+        raise DeviceNotFoundError, error.message
+      end
+
+      # @param device_handle [File]
+      # @return [void]
+      def close_device(device_handle)
+        device_handle.close
+      end
+
+      # @param device_handle [File]
+      # @param config_value [Integer]
+      # @return [Integer]
+      def set_configuration(device_handle, config_value)
+        device_handle.ioctl(self.class::USBDEVFS_SETCONFIG, [config_value].pack("I"))
+      end
+
+      # @param device_handle [File]
+      # @param interface_number [Integer]
+      # @return [Integer]
+      def claim_interface(device_handle, interface_number)
+        device_handle.ioctl(self.class::USBDEVFS_CLAIMINTF, [interface_number].pack("I"))
+      end
+
+      # @param device_handle [File]
+      # @param interface_number [Integer]
+      # @return [Integer]
+      def release_interface(device_handle, interface_number)
+        device_handle.ioctl(self.class::USBDEVFS_RELEASEINTF, [interface_number].pack("I"))
+      end
+
+      # @param device_handle [File]
+      # @param interface_number [Integer]
+      # @param alternate_setting [Integer]
+      # @return [Integer]
+      def set_alternate_interface(device_handle, interface_number, alternate_setting)
+        payload = [interface_number, alternate_setting].pack("II")
+        device_handle.ioctl(self.class::USBDEVFS_SETINTF, payload)
+      end
+
+      # @param device_handle [File]
+      # @param setup [Hash]
+      # @param length [Integer]
+      # @return [Hash]
+      def control_transfer_in(device_handle, setup, length)
+        payload = build_control_payload(setup, :in, length: length)
+        device_handle.ioctl(self.class::USBDEVFS_CONTROL, payload)
+        { status: TransferStatus::OK, data: device_handle.read(length) }
+      end
+
+      # @param device_handle [File]
+      # @param setup [Hash]
+      # @param data [String, nil]
+      # @return [Hash]
+      def control_transfer_out(device_handle, setup, data)
+        payload = build_control_payload(setup, :out, data: data.to_s)
+        device_handle.ioctl(self.class::USBDEVFS_CONTROL, payload)
+        { status: TransferStatus::OK, bytes_written: data.to_s.bytesize }
+      end
+
+      # @param device_handle [File]
+      # @param endpoint [Integer]
+      # @param length [Integer]
+      # @param timeout [Integer]
+      # @return [Hash]
+      def bulk_transfer_in(device_handle, endpoint, length, timeout:)
+        payload = [endpoint | 0x80, length, timeout].pack("III")
+        device_handle.ioctl(self.class::USBDEVFS_BULK, payload)
+        { status: TransferStatus::OK, data: device_handle.read(length) }
+      end
+
+      # @param device_handle [File]
+      # @param endpoint [Integer]
+      # @param data [String]
+      # @param timeout [Integer]
+      # @return [Hash]
+      def bulk_transfer_out(device_handle, endpoint, data, timeout:)
+        payload = [endpoint, data.bytesize, timeout].pack("III") + data
+        device_handle.ioctl(self.class::USBDEVFS_BULK, payload)
+        { status: TransferStatus::OK, bytes_written: data.bytesize }
+      end
+
+      # @raise [NotImplementedError]
+      # @return [void]
+      def isochronous_transfer_in(_device_handle, _endpoint, _packet_lengths)
+        raise NotImplementedError, "usbfs isochronous transfers are not implemented"
+      end
+
+      # @raise [NotImplementedError]
+      # @return [void]
+      def isochronous_transfer_out(_device_handle, _endpoint, _data, _packet_lengths)
+        raise NotImplementedError, "usbfs isochronous transfers are not implemented"
+      end
+
+      # @param device_handle [File]
+      # @param endpoint [Integer]
+      # @return [Integer]
+      def clear_halt(device_handle, endpoint)
+        device_handle.ioctl(self.class::USBDEVFS_CLEAR_HALT, [endpoint].pack("I"))
+      end
+
+      # @param device_handle [File]
+      # @return [Integer]
+      def reset_device(device_handle)
+        device_handle.ioctl(self.class::USBDEVFS_RESET, "".b)
+      end
+
+      # @param device_handle [Object]
+      # @return [Object]
+      def get_device_descriptor(device_handle)
+        device_handle
+      end
+
+      # @raise [NotImplementedError]
+      # @return [void]
+      def get_configuration_descriptor(_device_handle, _index)
+        raise NotImplementedError, "usbfs configuration descriptors are not implemented"
+      end
+
+      private
+
+      def build_control_payload(setup, direction, length: 0, data: "".b)
+        [
+          build_request_type(setup, direction),
+          setup[:request],
+          setup[:value],
+          setup[:index],
+          data.bytesize,
+          UsbKit.config.transfer_timeout,
+          length
+        ].pack("CCSSIII") + data
+      end
+
+      def build_request_type(setup, direction)
+        direction_bit = direction == :in ? 0x80 : 0x00
+        direction_bit | REQUEST_TYPE_BITS.fetch(setup[:request_type]) | RECIPIENT_BITS.fetch(setup[:recipient])
+      end
+    end
+  end
+end

data/lib/usbkit/configuration.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module UsbKit
+  ##
+  # Gem-level UsbKit configuration.
+  #
+  class GemConfiguration
+    # @return [Symbol] :auto, :usb_ruby, or :usbfs
+    # @return [Symbol] selected log level
+    # @return [Integer] transfer timeout in milliseconds
+    # @return [Array<Integer>] blocked USB class codes
+    attr_accessor :backend, :log_level, :transfer_timeout, :blocked_classes
+
+    # @return [void]
+    def initialize
+      @backend = :auto
+      @log_level = :warn
+      @transfer_timeout = 5000
+      @blocked_classes = default_blocked_classes
+    end
+
+    private
+
+    def default_blocked_classes
+      [
+        0x01,
+        0x03,
+        0x08,
+        0x0B,
+        0x0E,
+        0x10,
+        0xE0
+      ].freeze
+    end
+  end
+end

data/lib/usbkit/connection_event.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module UsbKit
+  ##
+  # Device connection lifecycle event.
+  #
+  class ConnectionEvent
+    EVENT_TYPES = %i[connect disconnect].freeze
+
+    # @return [Device] related device
+    # @return [Symbol] :connect or :disconnect
+    attr_reader :device, :type
+
+    # @param attrs [Hash]
+    # @raise [ArgumentError] when the event type is unsupported
+    # @return [void]
+    def initialize(attrs)
+      @device = attrs.fetch(:device)
+      @type = validate_type(attrs.fetch(:type))
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      { device: device, type: type }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} type=#{type.inspect} device=#{device.inspect}>"
+    end
+
+    private
+
+    def validate_type(type)
+      return type if EVENT_TYPES.include?(type)
+
+      raise ArgumentError, "Invalid event type: #{type.inspect}"
+    end
+  end
+end