simple_hid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65df517271a4f786b5f536c3c25c423d50cc3b99f328385964c5b4457ca027b2
+  data.tar.gz: 61550584ab55cd3017dc45f095a571701eec7d920d2ac0f5d7f4c1df06c17c7e
+SHA512:
+  metadata.gz: 26ab7a91eed2083794eb66537c8106fbe02fbe5fc98f049d07ea912fff88d579ef654d47834624aeb088b394097b83cf7d653eb1bd23fb749bb056deeecfc3b1
+  data.tar.gz: cc06048dd9ab119217168d8109d18aa0ecb86f24b404fc9bb7c4a6c10df8593cbceaab14fde9c92e0f6ce6e8f54d0ff257b6e105fbbd09f7a3a755bac8358dba

data/LICENCE

@@ -0,0 +1,9 @@
+MIT License (MIT)
+
+Copyright © 2025 Jesse Fullam
+
+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,109 @@
+# SimpleHID: A Python-Inspired HIDAPI Wrapper for Ruby
+
+This project is a minimal FFI-based Ruby wrapper for the `hidapi` library. It was created to provide a simple interface HID communication, closely mirroring the design and ease of use of the Python `pyhidapi` library.
+
+## Motivation
+
+While other HID libraries for Ruby exist, I found they lacked certain features for advanced device discovery. In particular, the ability to filter devices by `usage_page` and `usage` was not readily available. This functionality is critical for precisely identifying a specific device interface when a single piece of hardware exposes multiple HID interfaces.
+
+## Features & Current Status
+
+The implementation in its current form, is intentionally lightweight and purpose-built. It provides functionality for:
+
+*   **Advanced Device Discovery:** Find devices by VID, PID, `usage_page`, and `usage`.
+*   **Write-Only Operations:** Send command packets to any connected HID device.
+
+It is perfectly suited for projects involving custom peripheral control, especially those that require reverse-engineering a device's USB protocol. The library handles the low-level device connection, allowing you to focus on crafting and sending the correct byte commands.
+
+## Installation
+
+- Ensure the system `hidapi` library is installed:
+  - Arch: `sudo pacman -S hidapi`
+  - Debian/Ubuntu: `sudo apt install libhidapi-hidraw0`
+  - macOS (Homebrew): `brew install hidapi`
+- Install the Ruby gem: `gem install simple_hid`
+
+## Usage
+
+First, require the library in your script:
+
+```ruby
+require 'simple_hid'
+```
+
+### 1. Finding a Specific Device
+
+The primary feature of the library is finding a device by its specific attributes. The `find_path` method will return the system path as a string if a device is found, or `nil` if not.
+
+```ruby
+# Define the attributes of the device you're looking for
+VENDOR_ID = 0x0CF2
+PRODUCT_ID = 0xA102
+USAGE_PAGE = 0xFF72
+USAGE = 0x00A1
+
+# Search for the device path
+path = SimpleHID.find_path(
+  vid: VENDOR_ID,
+  pid: PRODUCT_ID,
+  usage_page: USAGE_PAGE,
+  usage: USAGE
+)
+
+unless path
+  puts "Error: Device not found."
+  exit
+end
+
+puts "Found device at: #{path}"
+```
+
+### 2. Listing All Connected HID Devices
+
+You can also enumerate all HID devices connected to the system, which is useful for discovery. The `enumerate` method returns an array of hashes, with each hash representing one device.
+
+```ruby
+# Get a list of all HID devices
+all_devices = SimpleHID.enumerate
+
+# Print the details for each device found
+all_devices.each do |device_info|
+  puts "Path: #{device_info[:path]}"
+  puts "  Vendor ID:  0x#{device_info[:vendor_id].to_s(16)}"
+  puts "  Product ID: 0x#{device_info[:product_id].to_s(16)}"
+  puts "  Usage Page: 0x#{device_info[:usage_page].to_s(16)}"
+  puts "-" * 20
+end
+```
+
+### 3. Opening a Device and Writing Data
+
+Once you have the device path, you can open it, send commands, and ensure it's closed safely using a `begin...ensure` block.
+
+```ruby
+# (Continuing from the 'find_path' example above...)
+
+begin
+  # 1. Open the device using its path
+  device = SimpleHID::Device.new(path)
+  puts "Device opened successfully."
+
+  # 2. Prepare your command as an array of bytes
+  # This command must match the protocol of your specific device.
+  # Note: The underlying HID report may require padding to a specific length.
+  # This library sends exactly what you provide.
+  command = [0xE0, 0x10, 0x60, 0x01, 0x03, 0x00, 0x00, 0x00]
+
+  # 3. Write the command to the device
+  device.write(command)
+  puts "Command sent."
+
+ensure
+  # 4. The 'ensure' block guarantees the device is closed,
+  # even if an error occurs during the write operation.
+  if device
+    device.close
+    puts "Device closed cleanly."
+  end
+end
+```

data/lib/simple_hid/version.rb

@@ -0,0 +1,3 @@
+module SimpleHID
+  VERSION = "0.1.0"
+end 

data/lib/simple_hid.rb

@@ -0,0 +1,151 @@
+require "ffi"
+require "simple_hid/version"
+
+module SimpleHID
+  extend FFI::Library
+
+  begin
+    # Try for common library names across platforms -> the first found will be used
+    ffi_lib [
+      "hidapi-hidraw",
+      "hidapi-libusb",
+      "hidapi",
+      "libhidapi-hidraw.so.0",
+      "libhidapi-hidraw.so"
+    ]
+  rescue LoadError => e
+    raise LoadError, (
+      "Could not load the hidapi shared library. " \
+      "Original error: #{e.message}"
+    )
+  end
+
+  enum :hid_bus_type, [
+  :unknown,   0x00,
+  :usb,       0x01,
+  :bluetooth, 0x02,
+  :i2c,       0x03,
+  :spi,       0x04,
+  :virtual,   0x05
+]
+  # Define the C structure for DeviceInfo
+  class DeviceInfo < FFI::Struct 
+    layout :path,                :string, 
+           :vendor_id,           :ushort, 
+           :product_id,          :ushort, 
+           :serial_number,       :pointer, 
+           :release_number,      :ushort,
+           :manufacturer_string, :pointer, 
+           :product_string,      :pointer, 
+           :usage_page,          :ushort,
+           :usage,               :ushort, 
+           :interface_number,    :int, 
+           :next,                :pointer, 
+           :bus_type,            :hid_bus_type
+  end
+
+  # Attach the raw C functions from the loaded library 
+  attach_function :hid_init, [], :int
+  attach_function :hid_exit, [], :void
+  attach_function :hid_enumerate, [:ushort, :ushort], :pointer
+  attach_function :hid_free_enumeration, [:pointer], :void
+  attach_function :hid_open_path, [:string], :pointer
+  attach_function :hid_write, [:pointer, :pointer, :size_t], :int
+  attach_function :hid_close, [:pointer], :void
+  # wchar_t handling 
+  attach_function :hid_get_manufacturer_string, [:pointer, :pointer, :size_t], :int
+  attach_function :hid_get_product_string,      [:pointer, :pointer, :size_t], :int
+  attach_function :hid_get_serial_number_string,[:pointer, :pointer, :size_t], :int
+
+  # Enumeration method 
+  def self.enumerate(vid: 0, pid: 0)
+    devices = []
+    head = hid_enumerate(vid, pid)
+
+    begin
+      return [] if head.null?
+      current_ptr = head
+      until current_ptr.null?
+        info_struct = DeviceInfo.new(current_ptr)
+        
+        # Convert the FFI::Struct to a plain Ruby Hash
+        device_info = {
+          path: info_struct[:path].dup, 
+          vendor_id: info_struct[:vendor_id],
+          product_id: info_struct[:product_id],
+          release_number: info_struct[:release_number],
+          usage_page: info_struct[:usage_page],
+          usage: info_struct[:usage],
+          interface_number: info_struct[:interface_number],
+          bus_type: info_struct[:bus_type]
+        }
+        devices << device_info
+        current_ptr = info_struct[:next]
+      end
+    ensure
+      hid_free_enumeration(head) unless head.null?
+    end
+
+    devices
+  end
+
+  # Helper method 
+  def self.find_path(vid: 0, pid: 0, usage_page: nil, usage: nil)
+    all_devices = self.enumerate(vid: vid, pid: pid)
+    found_device = all_devices.find do |dev|
+      match_usage_page = usage_page.nil? || dev[:usage_page] == usage_page
+      match_usage = usage.nil? || dev[:usage] == usage
+      match_usage_page && match_usage
+    end
+    found_device ? found_device[:path] : nil
+  end
+
+  class Device
+
+    MAX_STR_LEN = 255 
+
+    def initialize(path)
+      @handle = SimpleHID.hid_open_path(path)
+      raise "Unable to open HID device at path: #{path}" if @handle.null?
+    end
+
+    def write(byte_array)
+      raise "Device is closed." if @handle.nil?
+      data_string = byte_array.pack('C*')
+      data_ptr = FFI::MemoryPointer.from_string(data_string)
+      SimpleHID.hid_write(@handle, data_ptr, data_string.bytesize)
+    end
+
+    def close
+      return if @handle.nil? 
+      SimpleHID.hid_close(@handle)
+      @handle = nil
+    end
+
+    def manufacturer_string
+      read_wide_string_with(:hid_get_manufacturer_string)
+    end
+
+    def product_string
+      read_wide_string_with(:hid_get_product_string)
+    end
+
+    def serial_number_string
+      read_wide_string_with(:hid_get_serial_number_string)
+    end
+
+    private
+
+    def read_wide_string_with(c_function_name)
+      raise "Device is closed." if @handle.nil?
+      buffer = FFI::MemoryPointer.new(:wchar_t, MAX_STR_LEN)
+      result = SimpleHID.send(c_function_name, @handle, buffer, MAX_STR_LEN)
+      raise "HIDAPI error while reading string." if result == -1
+
+      return buffer.read_wstring
+    end
+  end
+
+  self.hid_init
+  at_exit { self.hid_exit }
+end 

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: simple_hid
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jesse Fullam
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.15'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Provides simple device enumeration by VID/PID/usage and write-only communication
+  for HID devices.
+email: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENCE
+- README.md
+- lib/simple_hid.rb
+- lib/simple_hid/version.rb
+homepage: https://github.com/bell-arch/Simple_HID
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/bell-arch/Simple_HID
+  changelog_uri: https://github.com/bell-arch/Simple_HID/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.6'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Minimal FFI-based HIDAPI wrapper for Ruby, inspired by Python's hid library.
+test_files: []