usbkit 0.1.0

data/lib/usbkit/transfer_results.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module UsbKit
+  module TransferResultValidation
+    private
+
+    def validate_status(status)
+      return status if TransferStatus.valid?(status)
+
+      raise ArgumentError, "Invalid transfer status: #{status.inspect}"
+    end
+  end
+
+  ##
+  # Result for control and bulk IN transfers.
+  #
+  class InTransferResult
+    include TransferResultValidation
+
+    # @return [String, nil] received data
+    # @return [Symbol] transfer status
+    attr_reader :data, :status
+
+    # @param attrs [Hash]
+    # @return [void]
+    def initialize(attrs)
+      @data = attrs[:data]
+      @status = validate_status(attrs.fetch(:status))
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      { data: data, status: status }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} status=#{status.inspect} bytes=#{data&.bytesize || 0}>"
+    end
+  end
+
+  ##
+  # Result for control and bulk OUT transfers.
+  #
+  class OutTransferResult
+    include TransferResultValidation
+
+    # @return [Integer] number of bytes written
+    # @return [Symbol] transfer status
+    attr_reader :bytes_written, :status
+
+    # @param attrs [Hash]
+    # @return [void]
+    def initialize(attrs)
+      @bytes_written = attrs.fetch(:bytes_written)
+      @status = validate_status(attrs.fetch(:status))
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      { bytes_written: bytes_written, status: status }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} status=#{status.inspect} bytes_written=#{bytes_written.inspect}>"
+    end
+  end
+
+  ##
+  # Per-packet result for isochronous IN transfers.
+  #
+  class IsochronousInTransferPacket
+    include TransferResultValidation
+
+    # @return [String, nil] packet payload
+    # @return [Symbol] packet status
+    attr_reader :data, :status
+
+    # @param attrs [Hash]
+    # @return [void]
+    def initialize(attrs)
+      @data = attrs[:data]
+      @status = validate_status(attrs.fetch(:status))
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      { data: data, status: status }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} status=#{status.inspect} bytes=#{data&.bytesize || 0}>"
+    end
+  end
+
+  ##
+  # Result for isochronous IN transfers.
+  #
+  class IsochronousInTransferResult
+    # @return [String, nil] concatenated transfer data
+    # @return [Array<IsochronousInTransferPacket>] packet-level results
+    attr_reader :data, :packets
+
+    # @param attrs [Hash]
+    # @return [void]
+    def initialize(attrs)
+      @packets = Array(attrs.fetch(:packets, [])).map { |packet| build_packet(packet) }.freeze
+      @data = attrs.key?(:data) ? attrs[:data] : packets.filter_map(&:data).join
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      { data: data, packets: packets.map(&:to_h) }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} packets=#{packets.size} bytes=#{data&.bytesize || 0}>"
+    end
+
+    private
+
+    def build_packet(packet)
+      packet.is_a?(IsochronousInTransferPacket) ? packet : IsochronousInTransferPacket.new(packet)
+    end
+  end
+
+  ##
+  # Per-packet result for isochronous OUT transfers.
+  #
+  class IsochronousOutTransferPacket
+    include TransferResultValidation
+
+    # @return [Integer] number of bytes written for the packet
+    # @return [Symbol] packet status
+    attr_reader :bytes_written, :status
+
+    # @param attrs [Hash]
+    # @return [void]
+    def initialize(attrs)
+      @bytes_written = attrs.fetch(:bytes_written)
+      @status = validate_status(attrs.fetch(:status))
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      { bytes_written: bytes_written, status: status }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} status=#{status.inspect} bytes_written=#{bytes_written.inspect}>"
+    end
+  end
+
+  ##
+  # Result for isochronous OUT transfers.
+  #
+  class IsochronousOutTransferResult
+    # @return [Array<IsochronousOutTransferPacket>] packet-level results
+    attr_reader :packets
+
+    # @param attrs [Hash]
+    # @return [void]
+    def initialize(attrs)
+      @packets = Array(attrs.fetch(:packets, [])).map { |packet| build_packet(packet) }.freeze
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      { packets: packets.map(&:to_h) }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} packets=#{packets.size}>"
+    end
+
+    private
+
+    def build_packet(packet)
+      packet.is_a?(IsochronousOutTransferPacket) ? packet : IsochronousOutTransferPacket.new(packet)
+    end
+  end
+end

data/lib/usbkit/usb_configuration.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module UsbKit
+  ##
+  # Immutable USB configuration descriptor.
+  #
+  class Configuration
+    # @return [Device, nil] parent device
+    # @return [Integer] USB configuration value
+    # @return [String, nil] configuration name
+    # @return [Array<Interface>] interfaces for the configuration
+    attr_reader :device, :configuration_value, :configuration_name, :interfaces
+
+    # @param attrs [Hash]
+    # @param device [Device, nil]
+    # @return [void]
+    def initialize(attrs, device: nil)
+      @device = device
+      @configuration_value = attrs.fetch(:configuration_value)
+      @configuration_name = attrs[:configuration_name]
+      @interfaces = Array(attrs.fetch(:interfaces, [])).map { |interface| build_interface(interface) }.freeze
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        configuration_value: configuration_value,
+        configuration_name: configuration_name,
+        interfaces: interfaces.map(&:to_h)
+      }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} configuration_value=#{configuration_value.inspect} interfaces=#{interfaces.size}>"
+    end
+
+    private
+
+    def build_interface(interface)
+      interface.is_a?(Interface) ? interface : Interface.new(interface)
+    end
+  end
+end

data/lib/usbkit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module UsbKit
+  VERSION = "0.1.0"
+end

data/lib/usbkit.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "usbkit/version"
+require_relative "usbkit/errors"
+require_relative "usbkit/constants"
+require_relative "usbkit/configuration"
+require_relative "usbkit/endpoint"
+require_relative "usbkit/alternate_interface"
+require_relative "usbkit/interface"
+require_relative "usbkit/usb_configuration"
+require_relative "usbkit/transfer_results"
+require_relative "usbkit/connection_event"
+require_relative "usbkit/filter"
+require_relative "usbkit/device"
+require_relative "usbkit/context"
+require_relative "usbkit/backend/base"
+
+##
+# WebUSB-inspired USB access toolkit for Ruby.
+#
+module UsbKit
+  class << self
+    attr_writer :config
+
+    # @return [GemConfiguration] current gem-level configuration
+    def config
+      @config ||= GemConfiguration.new
+    end
+
+    # Configure UsbKit.
+    #
+    # @yieldparam config [GemConfiguration]
+    # @return [GemConfiguration, Enumerator]
+    def configure
+      return enum_for(__method__) unless block_given?
+
+      yield(config)
+    end
+
+    # @return [Backend::Base] resolved backend implementation
+    # @raise [BackendNotAvailableError] when no backend can be resolved
+    def backend
+      @backend ||= resolve_backend
+    end
+
+    # @return [void]
+    def reset_backend!
+      @backend = nil
+    end
+
+    # @return [Context]
+    def context
+      Context.new
+    end
+
+    private
+
+    def resolve_backend
+      case config.backend
+      when :auto
+        try_usb_ruby || try_usbfs || raise(BackendNotAvailableError, "No USB backend available")
+      when :usb_ruby
+        try_usb_ruby || raise(BackendNotAvailableError, "usb-ruby backend not available")
+      when :usbfs
+        try_usbfs || raise(BackendNotAvailableError, "usbfs backend not available")
+      else
+        raise ArgumentError, "Unknown backend: #{config.backend.inspect}"
+      end
+    end
+
+    def try_usb_ruby
+      require_relative "usbkit/backend/usb_ruby"
+      Backend::UsbRuby.new
+    rescue LoadError, BackendNotAvailableError
+      nil
+    end
+
+    def try_usbfs
+      return nil unless RUBY_PLATFORM.match?(/linux/i)
+
+      require_relative "usbkit/backend/usbfs"
+      Backend::Usbfs.new
+    rescue LoadError, BackendNotAvailableError
+      nil
+    end
+  end
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: usbkit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- UsbKit Contributors
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: usb-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: UsbKit provides a WebUSB API-compatible interface for communicating with
+  USB devices from Ruby using usb-ruby with a Linux usbfs fallback.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/usbkit.rb
+- lib/usbkit/alternate_interface.rb
+- lib/usbkit/async.rb
+- lib/usbkit/backend/base.rb
+- lib/usbkit/backend/usb_ruby.rb
+- lib/usbkit/backend/usb_ruby/device_wrapper.rb
+- lib/usbkit/backend/usbfs.rb
+- lib/usbkit/backend/usbfs/ioctl_commands.rb
+- lib/usbkit/backend/usbfs/sysfs_reader.rb
+- lib/usbkit/configuration.rb
+- lib/usbkit/connection_event.rb
+- lib/usbkit/constants.rb
+- lib/usbkit/context.rb
+- lib/usbkit/device.rb
+- lib/usbkit/endpoint.rb
+- lib/usbkit/errors.rb
+- lib/usbkit/filter.rb
+- lib/usbkit/interface.rb
+- lib/usbkit/transfer_results.rb
+- lib/usbkit/usb_configuration.rb
+- lib/usbkit/version.rb
+homepage: https://github.com/usbkit-rb/usbkit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/usbkit-rb/usbkit
+  source_code_uri: https://github.com/usbkit-rb/usbkit
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby implementation of the WebUSB API for cross-platform USB access
+test_files: []