Initial implementation

Gareth Adams · Gareth Adams · commit ce4e768ab80c · 2015-07-24T12:34:50.000+01:00
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
diff --git a/.rspec b/.rspec
@@ -0,0 +1,2 @@
+--format documentation
+--color
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,3 @@
+language: ruby
+rvm:
+  - 2.1.5
diff --git a/Gemfile b/Gemfile
@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hid_api.gemspec
+gemspec
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Gareth Adams
+
+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.
diff --git a/README.md b/README.md
@@ -0,0 +1,47 @@
+# HidApi
+
+HidApi is an FFI wrapper around the C library '[hidapi][1]' provided by Signal11.
+
+[1]: http://www.signal11.us/oss/hidapi/
+
+This gem is my first attempt at writing any FFI code, and my first attempt to use USB. It's very possible that conventions will be broken, edge cases missed and that nothing will work if you're not using it exactly how I am. But let me know (open a Github issue, or even better see the Contributing section below) and I might be able to do something about it.
+
+## Dependencies
+
+The gem requires the hidapi library to be installed and available to Ruby. On Mac with homebrew installed, this can be done with the command:
+
+    $ brew install hidapi
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'hid_api'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install hid_api
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/gareth/ruby_hid_api/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
diff --git a/Rakefile b/Rakefile
@@ -0,0 +1,9 @@
+require "bundler/gem_tasks"
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+end
+
+task :default => :spec
diff --git a/bin/console b/bin/console
@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "hid_api"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+require "pry"
+Pry.start
+
+# require "irb"
+# IRB.start
diff --git a/bin/setup b/bin/setup
@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here
diff --git a/hid_api.gemspec b/hid_api.gemspec
@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hid_api/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hid_api"
+  spec.version       = HidApi::VERSION
+  spec.licenses      = ["MIT"]
+  spec.authors       = ["Gareth Adams"]
+  spec.email         = ["g@rethada.ms"]
+
+  spec.summary       = %q{A Ruby FFI wrapper around the System11 hidapi C library}
+  spec.description   = %q{}
+  spec.homepage      = "https://github.com/gareth/ruby_hid_api"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "ffi", "~> 1.9"
+
+  spec.add_development_dependency "bundler", "~> 1.8"
+  spec.add_development_dependency "rake", "~> 10.0"
+
+  spec.add_development_dependency "rspec", "> 0"
+
+  spec.add_development_dependency "pry", "> 0"
+  spec.add_development_dependency "awesome_print", "> 0"
+end
diff --git a/lib/hid_api.rb b/lib/hid_api.rb
@@ -0,0 +1,64 @@
+require 'ffi'
+
+module HidApi
+  class HidError < StandardError; end
+
+  extend FFI::Library
+  ffi_lib 'hidapi'
+
+  autoload :Device,     'hid_api/device'
+  autoload :DeviceInfo, 'hid_api/device_info'
+  autoload :Util,       'hid_api/util'
+  autoload :VERSION,    'hid_api/version'
+  autoload :WideString, 'hid_api/wide_string'
+
+  typedef DeviceInfo.auto_ptr, :hid_device_info
+  typedef WideString, :wide_string
+  typedef Device, :device
+  typedef :int, :vendor_id
+  typedef :int, :product_id
+  typedef :int, :serial_number
+  typedef :int, :length
+  typedef :int, :timeout
+
+  attach_function :hid_init, [], :int
+  attach_function :hid_exit, [], :int
+  attach_function :hid_enumerate, [:int, :int], :hid_device_info
+  attach_function :hid_free_enumeration, [:hid_device_info], :void
+  attach_function :hid_open, [:vendor_id, :product_id, :serial_number], :device
+  attach_function :hid_open_path, [:string], :device
+  attach_function :hid_write, [:device, :buffer_in, :length], :int
+  attach_function :hid_read_timeout, [:device, :buffer_out, :length, :timeout], :int
+  attach_function :hid_read, [:device, :buffer_out, :length], :int
+  attach_function :hid_set_nonblocking, [:device, :int], :int
+  attach_function :hid_send_feature_report, [:device, :buffer_in, :int], :int
+  attach_function :hid_get_feature_report, [:device, :buffer_out, :int], :int
+  attach_function :hid_close, [:device], :void
+  attach_function :hid_get_manufacturer_string, [:device, :buffer_out, :length], :int
+  attach_function :hid_get_product_string, [:device, :buffer_out, :length], :int
+  attach_function :hid_get_serial_number_string, [:device, :buffer_out, :length], :int
+  attach_function :hid_get_indexed_string, [:device, :int, :buffer_out, :length], :int
+  # hid_error will always return a nil except on Windows
+  attach_function :hid_error, [:device], WideString
+
+  class << self
+    alias init hid_init
+    alias exit hid_exit
+    alias enumerate hid_enumerate
+    alias free_enumeration hid_free_enumeration
+    def open vendor_id, product_id, serial_number=nil
+      device = hid_open(vendor_id, product_id, serial_number || 0)
+      raise HidError, "Unable to open #{[vendor_id, product_id, serial_number].inspect}" if device.null?
+      device
+    end
+
+    def open_path path
+      device = hid_open_path(path)
+      raise HidError, "Unable to open #{path.inspect}" if device.null?
+      device
+    end
+  end
+end
+
+# Attempts to extend some core FFI classes with platform-aware string-handling
+FFI::AbstractMemory.include(HidApi::Util::WCHAR)
diff --git a/lib/hid_api/device.rb b/lib/hid_api/device.rb
@@ -0,0 +1,88 @@
+require 'ffi'
+
+module HidApi
+  class Device < FFI::Pointer
+    extend FFI::DataConverter
+    native_type FFI::Type::POINTER
+
+    def self.from_native(value, ctx)
+      new(value)
+    end
+
+    def close
+      HidApi.close(self)
+    end
+
+    def set_nonblocking(int)
+      HidApi.hid_set_nonblocking self, int
+    end
+
+    def get_manufacturer_string
+      get_buffered_string :manufacturer
+    end
+
+    def get_product_string
+      get_buffered_string :product
+    end
+
+    def get_serial_number_string
+      get_buffered_string :serial_number
+    end
+
+    def read(length)
+      buffer = FFI::Buffer.new(1, length, true)
+      with_hid_error_handling do
+        HidApi.hid_read self, buffer, buffer.length
+      end
+      buffer
+    end
+
+    def read_timeout(length, timeout)
+      buffer = FFI::Buffer.new(1, length, true)
+      with_hid_error_handling do
+        HidApi.hid_read_timeout self, buffer, buffer.length, timeout
+      end
+      buffer
+    end
+
+    def write(data)
+      buffer = FFI::Buffer.new(1, data.length, true)
+      case data
+      when String then buffer.put_bytes 0, data
+      when Array then buffer.put_array_of_char 0, data
+      end
+
+      with_hid_error_handling do
+        HidApi.hid_write self, buffer, buffer.length
+      end
+    end
+
+    def get_feature_report(data)
+      raise NotImplementedError
+    end
+
+    def send_feature_report(data)
+      raise NotImplementedError
+    end
+
+    def error
+      # NOTE: hid_error is only implemented on Windows systems and returns nil
+      # on other platforms
+      HidApi.hid_error(self)
+    end
+
+    private
+    def get_buffered_string field
+      buffer = FFI::Buffer.new(1, 255, true)
+      HidApi.send "hid_get_#{field}_string", self, buffer, buffer.length
+      buffer.read_wchar_string
+    end
+
+    def with_hid_error_handling
+      raise ArgumentError, "Block required" unless block_given?
+      yield.tap do |result|
+        raise HidError, error if result == -1
+      end
+    end
+  end
+end
diff --git a/lib/hid_api/device_info.rb b/lib/hid_api/device_info.rb
@@ -0,0 +1,55 @@
+require 'ffi'
+
+module HidApi
+  # Represents the hid_device_info struct returned as part of
+  # the HidApi::hid_enumerate operation
+  #
+  # Because the struct acts as a linked list, every item represents both a
+  # device in the enumeration AND an Enumerable representing the rest of the
+  # list.
+  class DeviceInfo < FFI::Struct
+    include Enumerable
+
+    def self.release(pointer)
+      HidApi.hid_free_enumeration(pointer) unless pointer.null?
+    end
+
+    # Struct layout from http://www.signal11.us/oss/hidapi/hidapi/doxygen/html/structhid__device__info.html
+    layout  :path,                :string,            # char * path
+            :vendor_id,           :ushort,            # unsigned short vendor_id
+            :product_id,          :ushort,            # unsigned short product_id
+            :serial_number,       WideString,         # wchar_t * serial_number
+            :release_number,      :ushort,            # unsigned short release_number
+            :manufacturer_string, WideString,         # wchar_t * manufacturer_string
+            :product_string,      WideString,         # wchar_t * product_string
+            :usage_page,          :ushort,            # unsigned short usage_page
+            :usage,               :ushort,            # unsigned short usage
+            :interface_number,    :int,               # int interface_number
+            :next,                DeviceInfo.auto_ptr # struct hid_device_info * next
+
+    # Makes the struct members available as methods
+    layout.members.each do |f|
+      define_method(f) do
+        self[f]
+      end
+    end
+
+    def inspect
+      product_string.tap do |s|
+        s << " (%s)" % path unless path.empty?
+      end
+    end
+
+    # Exposes the linked list structure in an Enumerable-compatible format
+    def each
+      return enum_for(:each) unless block_given?
+
+      pointer = self
+      loop do
+        break if pointer.null?
+        yield pointer
+        pointer = pointer.next
+      end
+    end
+  end
+end
diff --git a/lib/hid_api/util.rb b/lib/hid_api/util.rb
@@ -0,0 +1,5 @@
+module HidApi
+  module Util
+    autoload :WCHAR, 'hid_api/util/wchar'
+  end
+end
diff --git a/lib/hid_api/util/wchar.rb b/lib/hid_api/util/wchar.rb
diff --git a/lib/hid_api/version.rb b/lib/hid_api/version.rb
diff --git a/lib/hid_api/wide_string.rb b/lib/hid_api/wide_string.rb
diff --git a/spec/hid_api_spec.rb b/spec/hid_api_spec.rb
diff --git a/spec/spec_helper.rb b/spec/spec_helper.rb

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+language: ruby`
	`2`	`+rvm:`
	`3`	`+ - 2.1.5`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +source 'https://rubygems.org'
++
 +# Specify your gem's dependencies in hid_api.gemspec
 +gemspec