usbkit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a316c9064db6d4e7cf6c446bd732a5b90ebd86b7e93d9770f782a339ebbbf4bc
+  data.tar.gz: 176a74ed2d34cd1d354b7d2a2162d324357cbc2d512af93603804774323446ea
+SHA512:
+  metadata.gz: a37ddbfd7d868ab4c1a63e8c69c41c768764ff6a11da7c581f15ad27601835691015bb6d699f62c13b3bbf33c2a1d4b6e2e08a303025ea5d1356db67e237ac15
+  data.tar.gz: 959235c30c65d104f73d8d17c420284686c8b69d25e4295b7b67460c2904ce3a93c6d99e789d6015c65bfb9c284c8f2ff5daa42c6946cededfb46398d8ef5bde

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## [0.1.0] - 2026-03-27
+
+- Initial release

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,152 @@
+# UsbKit
+
+UsbKit is a Ruby gem that brings a WebUSB-style API to Ruby applications. It exposes `Context`, `Device`, descriptor objects, transfer result objects, hotplug callbacks, and an async wrapper while keeping the public API close to the WebUSB mental model.
+
+## Installation
+
+Add the gem to your application:
+
+```ruby
+gem "usbkit"
+```
+
+Or install it directly:
+
+```bash
+gem install usbkit
+```
+
+UsbKit uses `usb-ruby` as the primary backend and falls back to Linux `usbfs` where available.
+
+## System Requirements
+
+- Ruby 3.1+
+- `libusb` when using the `usb-ruby` backend
+
+Install `libusb` with one of the following:
+
+```bash
+brew install libusb
+sudo apt-get install libusb-1.0-0-dev
+choco install libusb
+```
+
+## Quick Start
+
+```ruby
+require "usbkit"
+
+context = UsbKit::Context.new
+devices = context.get_devices
+
+devices.each do |device|
+  puts "#{device.vendor_id.to_s(16)}:#{device.product_id.to_s(16)} #{device.product_name}"
+end
+```
+
+Request a device and communicate with it:
+
+```ruby
+require "usbkit"
+
+context = UsbKit::Context.new
+device = context.request_device(filters: [{ vendor_id: 0x2341 }])
+
+device.with_session do |usb_device|
+  usb_device.select_configuration(1)
+  usb_device.claim_interface(0)
+  result = usb_device.transfer_in(1, 64)
+  puts result.data if result.status == :ok
+end
+```
+
+## API Overview
+
+### `UsbKit::Context`
+
+- `get_devices(filters: nil)` enumerates visible devices
+- `request_device(filters:)` returns the first matching device
+- `on(:connect)` and `on(:disconnect)` register hotplug callbacks
+- `start_event_monitoring` and `stop_event_monitoring` manage the polling thread
+
+### `UsbKit::Device`
+
+- Session: `open`, `close`, `forget`, `with_session`
+- Configuration: `select_configuration`
+- Interfaces: `claim_interface`, `release_interface`, `select_alternate_interface`
+- Transfers: `control_transfer_in`, `control_transfer_out`, `transfer_in`, `transfer_out`
+- Utilities: `clear_halt`, `reset`
+- Async: `async.transfer_in(...)`
+
+## WebUSB Mapping
+
+| WebUSB | UsbKit |
+| --- | --- |
+| `navigator.usb` | `UsbKit::Context` |
+| `USBDevice` | `UsbKit::Device` |
+| `USBConfiguration` | `UsbKit::Configuration` |
+| `USBInterface` | `UsbKit::Interface` |
+| `USBAlternateInterface` | `UsbKit::AlternateInterface` |
+| `USBEndpoint` | `UsbKit::Endpoint` |
+
+## Backend Selection
+
+UsbKit resolves a backend automatically by default:
+
+```ruby
+UsbKit.backend
+```
+
+You can pin a backend explicitly:
+
+```ruby
+UsbKit.configure do |config|
+  config.backend = :usb_ruby
+  config.transfer_timeout = 2_000
+end
+```
+
+Available values:
+
+- `:auto`
+- `:usb_ruby`
+- `:usbfs` on Linux only
+
+## Async Usage
+
+```ruby
+future = device.async.transfer_in(1, 64)
+result = future.value(timeout: 1.0)
+```
+
+The async wrapper uses a Ruby `Thread` and returns a `UsbKit::Async::Future`.
+
+## Troubleshooting
+
+- `BackendNotAvailableError`: install `usb-ruby` and ensure `libusb` is available.
+- `DeviceAccessError`: fix OS-level permissions for the device node.
+- `DeviceNotOpenedError`: call `open` or use `with_session`.
+- `TimeoutError`: increase `UsbKit.config.transfer_timeout`.
+
+On Linux you may need a udev rule for non-root access. On macOS you typically need `libusb` installed via Homebrew.
+
+## Development
+
+Install dependencies and run the verification suite:
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec yard doc --output-dir doc/
+gem build usbkit.gemspec
+```
+
+Examples live in `examples/`.
+
+## Contributing
+
+Bug reports and pull requests are welcome. Keep changes covered by tests and update the README and changelog when behavior changes.
+
+## License
+
+Released under the MIT License. See `LICENSE.txt`.

data/lib/usbkit/alternate_interface.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module UsbKit
+  ##
+  # Immutable USB alternate interface descriptor.
+  #
+  class AlternateInterface
+    # @return [Integer] alternate setting number
+    # @return [Integer] interface class code
+    # @return [Integer] interface subclass code
+    # @return [Integer] interface protocol code
+    # @return [String, nil] human-readable interface name
+    # @return [Array<Endpoint>] endpoints exposed by this alternate
+    attr_reader :alternate_setting,
+                :interface_class,
+                :interface_subclass,
+                :interface_protocol,
+                :interface_name,
+                :endpoints
+
+    # @param attrs [Hash]
+    # @return [void]
+    def initialize(attrs)
+      @alternate_setting = attrs.fetch(:alternate_setting)
+      @interface_class = attrs.fetch(:interface_class)
+      @interface_subclass = attrs.fetch(:interface_subclass)
+      @interface_protocol = attrs.fetch(:interface_protocol)
+      @interface_name = attrs[:interface_name]
+      @endpoints = Array(attrs.fetch(:endpoints, [])).map { |endpoint| build_endpoint(endpoint) }.freeze
+      freeze
+    end
+
+    # @return [Hash]
+    def to_h
+      {
+        alternate_setting: alternate_setting,
+        interface_class: interface_class,
+        interface_subclass: interface_subclass,
+        interface_protocol: interface_protocol,
+        interface_name: interface_name,
+        endpoints: endpoints.map(&:to_h)
+      }
+    end
+
+    # @return [String]
+    def inspect
+      "#<#{self.class} alternate_setting=#{alternate_setting.inspect} endpoints=#{endpoints.size}>"
+    end
+
+    private
+
+    def build_endpoint(endpoint)
+      endpoint.is_a?(Endpoint) ? endpoint : Endpoint.new(endpoint)
+    end
+  end
+end

data/lib/usbkit/async.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module UsbKit
+  module Async
+    ##
+    # Thread-backed future for asynchronous device operations.
+    #
+    class Future
+      # @yieldreturn [Object]
+      # @return [void]
+      def initialize(&block)
+        @thread = Thread.new(&block)
+      end
+
+      # @param timeout [Numeric, nil]
+      # @raise [TimeoutError] when the background operation does not finish in time
+      # @return [Object]
+      def value(timeout: nil)
+        @thread.join(timeout)
+        raise TimeoutError, "Async operation timed out" if @thread.alive?
+
+        @thread.value
+      end
+
+      # @return [Boolean]
+      def ready?
+        !@thread.alive?
+      end
+    end
+
+    ##
+    # Async wrapper around transfer-oriented device methods.
+    #
+    class AsyncProxy
+      TRANSFER_METHODS = %i[
+        transfer_in
+        transfer_out
+        control_transfer_in
+        control_transfer_out
+        isochronous_transfer_in
+        isochronous_transfer_out
+      ].freeze
+
+      # @param device [Device]
+      # @return [void]
+      def initialize(device)
+        @device = device
+      end
+
+      TRANSFER_METHODS.each do |method_name|
+        define_method(method_name) do |*args|
+          Future.new { @device.public_send(method_name, *args) }
+        end
+      end
+    end
+  end
+end

data/lib/usbkit/backend/base.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module UsbKit
+  module Backend
+    ##
+    # Abstract backend contract for USB operations.
+    #
+    class Base
+      # @return [Array<Hash>]
+      def enumerate_devices
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @return [Object]
+      def open_device(device_handle)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @return [void]
+      def close_device(device_handle)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @param config_value [Integer]
+      # @return [void]
+      def set_configuration(device_handle, config_value)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @param interface_number [Integer]
+      # @return [void]
+      def claim_interface(device_handle, interface_number)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @param interface_number [Integer]
+      # @return [void]
+      def release_interface(device_handle, interface_number)
+        raise NotImplementedError
+      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)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @param setup [Hash]
+      # @param length [Integer]
+      # @return [Hash]
+      def control_transfer_in(device_handle, setup, length)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @param setup [Hash]
+      # @param data [String, nil]
+      # @return [Hash]
+      def control_transfer_out(device_handle, setup, data)
+        raise NotImplementedError
+      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:)
+        raise NotImplementedError
+      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:)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @param endpoint [Integer]
+      # @param packet_lengths [Array<Integer>]
+      # @return [Hash]
+      def isochronous_transfer_in(device_handle, endpoint, packet_lengths)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @param endpoint [Integer]
+      # @param data [String]
+      # @param packet_lengths [Array<Integer>]
+      # @return [Hash]
+      def isochronous_transfer_out(device_handle, endpoint, data, packet_lengths)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @param endpoint [Integer]
+      # @return [void]
+      def clear_halt(device_handle, endpoint)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @return [void]
+      def reset_device(device_handle)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @return [Hash]
+      def get_device_descriptor(device_handle)
+        raise NotImplementedError
+      end
+
+      # @param device_handle [Object]
+      # @param index [Integer]
+      # @return [Object]
+      def get_configuration_descriptor(device_handle, index)
+        raise NotImplementedError
+      end
+    end
+  end
+end

data/lib/usbkit/backend/usb_ruby/device_wrapper.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module UsbKit
+  module Backend
+    class UsbRuby
+      ##
+      # Adapter that normalizes usb-ruby descriptors into UsbKit hashes.
+      #
+      class DeviceWrapper
+        ENDPOINT_TYPE_MAP = {
+          0 => :control,
+          1 => EndpointType::ISOCHRONOUS,
+          2 => EndpointType::BULK,
+          3 => EndpointType::INTERRUPT
+        }.freeze
+
+        # @param usb_device [Object]
+        # @return [void]
+        def initialize(usb_device)
+          @usb_device = usb_device
+          @descriptor = usb_device.device_descriptor
+        end
+
+        # @return [Hash]
+        def to_h
+          {
+            raw_device: @usb_device,
+            vendor_id: value_for(@descriptor, :vendor_id, :id_vendor),
+            product_id: value_for(@descriptor, :product_id, :id_product),
+            device_class: value_for(@descriptor, :device_class, :b_device_class, default: 0),
+            device_subclass: value_for(@descriptor, :device_sub_class, :device_subclass, :b_device_sub_class, default: 0),
+            device_protocol: value_for(@descriptor, :device_protocol, :b_device_protocol, default: 0),
+            device_version_major: bcd_major(value_for(@descriptor, :bcd_device, default: 0)),
+            device_version_minor: bcd_minor(value_for(@descriptor, :bcd_device, default: 0)),
+            device_version_subminor: bcd_subminor(value_for(@descriptor, :bcd_device, default: 0)),
+            usb_version_major: bcd_major(value_for(@descriptor, :bcd_usb, default: 0)),
+            usb_version_minor: bcd_minor(value_for(@descriptor, :bcd_usb, default: 0)),
+            usb_version_subminor: bcd_subminor(value_for(@descriptor, :bcd_usb, default: 0)),
+            manufacturer_name: value_for(@usb_device, :manufacturer_name, :manufacturer, default: nil),
+            product_name: value_for(@usb_device, :product_name, :product, default: nil),
+            serial_number: value_for(@usb_device, :serial_number, default: nil),
+            configurations: extract_configurations,
+            configuration_value: nil,
+            bus_number: value_for(@usb_device, :bus_number, default: nil),
+            device_address: value_for(@usb_device, :device_address, :address, default: nil)
+          }
+        end
+
+        private
+
+        def extract_configurations
+          configurations = if @usb_device.respond_to?(:configurations)
+                             Array(@usb_device.configurations)
+                           else
+                             count = value_for(@descriptor, :num_configurations, :b_num_configurations, default: 0)
+                             Array.new(count) { |index| @usb_device.config_descriptor(index) }
+                           end
+
+          configurations.map { |configuration| extract_configuration(configuration) }
+        rescue StandardError
+          []
+        end
+
+        def extract_configuration(configuration)
+          {
+            configuration_value: value_for(configuration, :configuration_value, :b_configuration_value, default: 0),
+            configuration_name: value_for(configuration, :configuration_name, :description, default: nil),
+            interfaces: extract_interfaces(configuration)
+          }
+        end
+
+        def extract_interfaces(configuration)
+          interfaces = collection_for(configuration, :interfaces, :interface_descriptors)
+
+          interfaces.each_with_index.map do |interface_descriptor, index|
+            alternates = collection_for(interface_descriptor, :alternates, :alt_settings, :alternate_settings)
+            alternates = [interface_descriptor] if alternates.empty?
+
+            {
+              interface_number: value_for(interface_descriptor, :interface_number, :b_interface_number, default: index),
+              alternate_setting: value_for(alternates.first, :alternate_setting, :b_alternate_setting, default: 0),
+              alternates: alternates.map { |alternate| extract_alternate(alternate) }
+            }
+          end
+        end
+
+        def extract_alternate(alternate)
+          {
+            alternate_setting: value_for(alternate, :alternate_setting, :b_alternate_setting, default: 0),
+            interface_class: value_for(alternate, :interface_class, :b_interface_class, default: 0),
+            interface_subclass: value_for(alternate, :interface_subclass, :b_interface_sub_class, default: 0),
+            interface_protocol: value_for(alternate, :interface_protocol, :b_interface_protocol, default: 0),
+            interface_name: value_for(alternate, :interface_name, :description, default: nil),
+            endpoints: extract_endpoints(alternate)
+          }
+        end
+
+        def extract_endpoints(alternate)
+          collection_for(alternate, :endpoints, :endpoint_descriptors).map do |endpoint|
+            address = value_for(endpoint, :endpoint_address, :b_endpoint_address, default: 0)
+            {
+              endpoint_number: address & 0x0F,
+              direction: (address & 0x80).zero? ? Direction::OUT : Direction::IN,
+              type: endpoint_type(endpoint),
+              packet_size: value_for(endpoint, :max_packet_size, :w_max_packet_size, default: 0)
+            }
+          end
+        end
+
+        def endpoint_type(endpoint)
+          raw_type = value_for(endpoint, :transfer_type, :attributes, default: EndpointType::BULK)
+          return raw_type if EndpointType.valid?(raw_type)
+
+          mapped = ENDPOINT_TYPE_MAP[raw_type.to_i & 0x03]
+          EndpointType.valid?(mapped) ? mapped : EndpointType::BULK
+        end
+
+        def collection_for(object, *methods)
+          methods.each do |method_name|
+            return Array(object.public_send(method_name)) if object.respond_to?(method_name)
+          end
+
+          []
+        end
+
+        def value_for(object, *methods, default: nil)
+          methods.each do |method_name|
+            return object.public_send(method_name) if object.respond_to?(method_name)
+          end
+
+          default
+        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