ruby_hid 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: aa992e562d3a8c3cf63778551f1343426ffddf5b
+  data.tar.gz: 3f95ab6dc3e1af2b4eb455011efe18c19d45dae2
+SHA512:
+  metadata.gz: bfcb6375e83f35e706e75d9e681182d78e934ca5885a9891a3bf569014d8d63cfbcc2516e606b21638f4b90faca6080ec5fb7189fdf69ddd066d09ff33f22d01
+  data.tar.gz: fbc72ad1244eaff5e9d56b4c599b8c820137d0355fe694a52acf9ac230cc71399d1be1ab9030c1c712d21afc206e3c659e34019c349dc9b2a0f22f91becfcd7d

data/LICENCE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Andrew Faraday
+
+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,340 @@
+ruby-hid
+==========
+
+A ruby library for observing HID game controllers. Currently supports
+
+* Ubuntu Linux
+
+Currently this only handles one controller at a time.
+
+*Warning:* ruby_hid has to change some rights down in the /sys and /dev
+folders of Linux in order to access the kernel. You will be asked for
+your password in order to use ruby_hid.
+
+Example Scripts
+===============
+
+devices.rb
+----------
+
+```bash
+$ ruby scripts/devices.rb
+```
+
+This lists the devices known to ruby_hid. e.g.:
+
+```bash
+$ ruby scripts/devices.rb
+/dev/input/by-id/usb-Saitek_ST200_Stick-event-joystick
+/dev/input/by-id/usb-MY-POWER_CO._LTD._2In1_USB_Joystick-event-joystick
+```
+
+All of the other example scripts take part the device names as
+an argument. For instance:
+
+```bash
+$ ruby scripts/read.rb Saitek
+$ ruby scripts/read.rb MY-POWER
+```
+
+But they can all be called without an argument, in
+this case they'll use the first one on the list.
+
+-----------------------
+
+read.rb
+-------
+
+```bash
+$ ruby scripts/read.rb 
+```
+
+This outputs the raw information from each event sent
+by the controller. e.g.:
+
+```bash
+$ ruby scripts/read.rb 
+2015-10-07T20:01:03+01:00 type: 1 code: 288 value: 1
+2015-10-07T20:01:03+01:00 type: 1 code: 288 value: 0
+2015-10-07T20:01:04+01:00 type: 1 code: 289 value: 1
+2015-10-07T20:01:04+01:00 type: 1 code: 289 value: 0
+2015-10-07T20:01:05+01:00 type: 3 code: 16 value: -1
+2015-10-07T20:01:05+01:00 type: 3 code: 16 value: 0
+2015-10-07T20:01:07+01:00 type: 3 code: 1 value: 99
+2015-10-07T20:01:07+01:00 type: 3 code: 1 value: 85
+2015-10-07T20:01:07+01:00 type: 3 code: 1 value: 73
+2015-10-07T20:01:07+01:00 type: 3 code: 1 value: 61
+```
+
+buttons.rb
+----------
+
+```bash
+$ ruby scripts/buttons.rb 
+```
+
+This reads the button-type events, outputting them as
+names and values. e.g.:
+
+```bash
+$ ruby scripts/buttons.rb 
+btn_1 pushed: 1
+btn_1 pushed: 0
+l1 pushed: 1
+l1 pushed: 0
+select pushed: 1
+select pushed: 0
+```
+
+axes.rb
+----------
+
+```bash
+$ ruby scripts/axes.rb 
+```
+
+This reads the axis-type events, outputting them as
+names and values. e.g.:
+
+```bash
+$ ruby scripts/axes.rb 
+left_x changed: 125
+left_x changed: 110
+left_x changed: 101
+left_x changed: 90
+left_x changed: 74
+left_x changed: 56
+left_x changed: 38
+left_x changed: 20
+left_x changed: 1
+left_x changed: 0
+left_x changed: 10
+left_x changed: 128
+```
+
+move_cursor.rb
+--------------
+
+A very simple movement script with ASCII output.
+It reads the left hand stick of a joypad.
+
+```bash
+$ ruby scripts/axes.rb 
++----------------------------------------+
+|                                        |
+|                                        |
+|                                        |
+|                                        |
+|                                        |
+|                                        |
+|                                        |
+|                                        |
+|              #                         |
+|                                        |
+|                                        |
+|                                        |
+|                                        |
+|                                        |
+|                                        |
++----------------------------------------+
+x: 14   - y: 8
+```
+
+Using it in your code
+=====================
+
+Button Events
+-------------
+
+Include the ruby_hid library
+
+`require 'ruby_hid'`
+
+Buttons are binary controls, events on button changes can
+have one of two values:
+
+* 1 - button down
+* 0 - button up
+
+You can find buttons with the RubyHid::Button class. Find
+the names or codeds in the EVENTS hash.
+
+```ruby
+RubyHid::Button.find(297)
+RubyHid::Button.find_by_name(:l1)
+```
+
+And define an event to be run 
+
+```ruby
+button = RubyHid::Button.find_by_name(:l1)
+button.add_event(
+  lambda {|value|
+    if value == 1
+      puts "You pushed L1"
+    else
+      puts "Lou released L1"
+    end 
+  }
+)
+```
+
+You can debug the actions you've added to a button with trigger_events
+
+```ruby
+# test button down event
+button.trigger_events(1)
+# test button up event
+button.trigger_events(0)
+```
+
+How about getting it to run when you press the button?
+
+The RubyHid::Device class is responsible for reading the raw input
+from the Buzz controllers via the linux terminal. Because it's reading
+a data stream, it needs to start a background process to allow it to 
+work while other ruby code is operating.
+
+You can start background process, which executes the events you added
+to the buttons, with start_watching.
+
+```ruby
+device = RubyHid::Device.new
+
+button = RubyHid::Button.find_by_name(:l1)
+button.add_event(
+  lambda {|value|
+    if value == 1
+      puts "You pushed L1"
+    else
+      puts "You released L1"
+    end 
+  }
+)
+
+device.start_watching
+```
+
+Note: This process will end when your ruby process ends, but if you
+want to stop it before that stage, you can call `device.stop_watching`
+
+If you want to do nothing other than watch the buttons, you may want
+to follow start_watching with an empty loop in order to keep your
+ruby process, and the the forked process which watches the controller
+alive. 
+
+```ruby
+device = RubyHid::Device.new(RubyHid::Device.list[0])
+
+button = RubyHid::Button.find_by_name(:l1)
+button.add_event(
+  lambda {|value|
+    if value == 1
+      puts "You pushed L1"
+    else
+      puts "You released L1"
+    end 
+  }
+)
+
+device.start_watching20
+
+loop do
+  sleep 1
+end 
+```
+
+Axis Events
+-----------
+
+Axes are continuous control events coming from a controller. Usually
+these are joysticks or throttles. 
+
+They differ from buttons in that they have a wider range of values,
+often the event is triggered a large number of times as the event is 
+triggered.
+ 
+They work in the same ways as buttons, only they are accessed via the 
+RubyHid::Axis class.
+
+*Note:* as the observers work on a separate process, and because axes 
+send a large number of messages it is wise to keep the events on your
+axes as small as possible, and modify a shared object.
+  
+```ruby
+require 'ostruct'
+require_relative '../lib/ruby_hid.rb'
+
+@cursor = OpenStruct.new(
+  :x => 50.0, :y => 50.0,
+  :x_speed => 0, :y_speed => 0
+)
+
+axis = RubyHid::Axis.find_by_name(:left_y)
+axis.add_event(
+  lambda do |value|
+    # value / 255 is from 0 to 1
+    @cursor.y_speed = ((value.to_f / 255.0) - 0.5)
+  end
+)
+
+axis = RubyHid::Axis.find_by_name(:left_x)
+axis.add_event(
+  lambda do |value|
+    # value / 255 is from 0 to 1
+    @cursor.x_speed = ((value.to_f / 255.0) - 0.5)
+  end
+)
+
+device = RubyHid::Device.new(RubyHid::Device.list[0])
+device.start_watching
+
+loop do
+  # Observers have set x_speed and y_speed
+  # each step increments both dimensions by it's own speed
+  @cursor.x += @cursor.x_speed
+  @cursor.y += @cursor.y_speed
+
+  puts "x: #{@cursor.x.to_i.to_s.ljust(4)} - y: #{@cursor.y.to_i}"
+  sleep 0.1
+end
+``` 
+
+Helping Out
+===========
+
+Testing
+-------
+
+ruby_hid is currently in a very early beta, it has only been tested
+on Ubuntu Linux with a small number of game controllers. I'd love 
+to hear if you managed to use it, what devices you've got to work and
+if you had any difficulty using the library.
+
+Contact me on @MarmiteJunction or andrewfaraday@hotmail.co.uk
+
+Contributing
+------------
+
+I'd love to have any complete improvements, these could include:
+
+* Support for other Linux distros, or Max OS
+* Bug fixes
+* Mappings for buttons or axes on other devices 
+ 
+To contribute:
+
+1. Fork www.github.com/ajfaraday/ruby-hid
+2. Make your changes (preferably on a named fix or feature branch)
+3. Create a pull request back to the base repo
+
+Acknowledgements
+===============
+
+This repo includes a modified version of the devinput class from
+https://github.com/kamaradclimber/libdevinput
+which was forked from
+https://github.com/prullmann/libdevinput
+
+Without that clone of libdev, written in ruby, I would not have been
+able to 

data/lib/ruby_hid/axis.rb

@@ -0,0 +1,44 @@
+module RubyHid
+
+  #
+  # An axis is a continuous control coming from a HID device.
+  # These are most often the output from joysticks.
+  #
+  # The most common values for axes range from 0 to 255.
+  # In this case the central (resting) position is 128.
+  #
+  # Axis includes d-pad axes, which have a distinctly
+  # different set of values.
+  #
+  # * -1 up or left
+  # * 0 centre
+  # * 1 down or right
+  #
+  class Axis < RubyHid::Observer
+
+    #
+    # List of Axes, with names
+    #
+    # Naming is mostly the stick name followed
+    # by x or y for the direction.
+    #
+    EVENTS = {
+      0 => :left_x,
+      1 => :left_y,
+      2 => :right_x,
+      5 => :right_y,
+      6 => :throttle,
+      16 => :dpad_x,
+      17 => :dpad_y
+    }
+
+    #
+    # Quick summary of the button
+    #
+    def to_s
+      "Axis: #{code} - #{name}"
+    end
+
+  end
+
+end

data/lib/ruby_hid/button.rb

@@ -0,0 +1,48 @@
+module RubyHid
+
+  #
+  # Button objects are observers of buttons on a controller.
+  # Buttons which are currently available are listed, by name
+  # in the EVENTS constant.
+  #
+  # Buttons can have 2 values passed to each event:
+  #
+  # * 1 - button down event
+  # * 0 - button up event
+  #
+  # To set the actions for a button use add_event:
+  #
+  #   button = Button.find_by_name(:btn_1)
+  #   button.add_event(lambda{ |value| puts "Button 1: #{value}" })
+  #
+  #
+  class Button < RubyHid::Observer
+
+    #
+    # List of button types, with names
+    #
+    EVENTS = {
+      # joy pads
+      288 => :btn_1,
+      289 => :btn_2,
+      290 => :btn_3,
+      291 => :btn_4,
+      292 => :l1,
+      293 => :r1,
+      294 => :l2,
+      295 => :r2,
+      296 => :select,
+      297 => :start,
+      298 => :l_stick,
+      299 => :r_stick
+    }
+
+    #
+    # Quick summary of the button
+    #
+    def to_s
+      "Button: #{code} - #{name}"
+    end
+
+  end
+end

data/lib/ruby_hid/device.rb

@@ -0,0 +1,149 @@
+class NoFileSpecifiedError < RuntimeError
+
+end
+
+module RubyHid
+  #
+  # The main interface for the Buzz controllers. Primarily
+  # used to monitor key pushes and trigger events. Keep a single
+  # instance of the class:
+  #
+  # `RubyHid::Device.new`
+  #
+  # The `each` method exposes events directly as they come in
+  #
+  # `device.each { |event| puts event }`
+  #
+  # The `start_watching` method starts a background job which
+  # runs the events bound to each button via the RubyHid::Button
+  # class. You can end this worker with `stop_watching`.
+  #
+  class Device
+
+    #
+    # Event types we're interested in, used to filter out meta-data.
+    #
+    # 1 - button (0, 1)
+    # 3 - axis (usually 0 - 255, centred on 128)
+    #
+    BUTTON_TYPE = 1
+    AXIS_TYPE = 3
+
+    ALLOWED_EVENT_TYPES = [
+      BUTTON_TYPE,
+      AXIS_TYPE
+    ]
+
+    #
+    # List possible devices from /dev/input/by-id/
+    #
+    # Or, list devices containing a string with search_term argument
+    #
+    def Device.list(search_term=nil)
+      if search_term
+        Dir["/dev/input/by-id/*#{search_term}*event-joystick*"]
+      else
+        Dir['/dev/input/by-id/*event-joystick*']
+      end
+    end
+
+    require 'time'
+
+    # The worker is a thread which is watching the device
+    attr_accessor :worker
+
+    Event = Struct.new(:tv_sec, :tv_usec, :type, :code, :value)
+    # open Event class and add some convenience methods
+    #
+    # Holds the un-packed data parsed from the raw input from the buzz controller.
+    class Event
+      def time;
+        Time.at(tv_sec)
+      end
+
+      def to_s
+        type_s = type.to_s
+        code_s = code.to_s
+        value_s = value.to_s
+        "#{time.iso8601} type: #{type_s} code: #{code_s} value: #{value_s}"
+      end
+    end
+
+    #
+    # Initialise device, getting event file from /dev/input/by-id/
+    #
+    def initialize(filename=nil, block_size=24)
+      raise NoFileSpecifiedError if filename.nil?
+      @dev = File.open(filename)
+      @block_size = block_size
+    rescue NoFileSpecifiedError, Errno::ENOENT => er
+      puts "Could not find device: are your controllers plugged in?"
+      raise er
+    end
+
+    #
+    # The format string which RubyHid uses to decode raw data.
+    #
+    def format
+      @format ||= case @block_size
+                    when 16
+                      'llSSl'
+                    when 24
+                      'qqSSl'
+                  end
+    end
+
+    #
+    # Read a single block.
+    #
+    def read
+      bin = @dev.read @block_size
+      Event.new *bin.unpack(format)
+    end
+
+    #
+    # Expose each event to a block of code as it comes in.
+    #
+    def each
+      begin
+        loop do
+          event = read
+          if event
+            next unless ALLOWED_EVENT_TYPES.include?(event.type)
+            yield event
+          end
+        end
+      rescue Errno::ENODEV
+      end
+    end
+
+    #
+    # Start a background worker which scans input file
+    # and triggers any events bound to each one.
+    #
+    def start_watching
+      return if @worker
+      @worker = Thread.new do
+        loop do
+          event = read
+          next unless ALLOWED_EVENT_TYPES.include?(event.type)
+          case event.type
+            when BUTTON_TYPE
+              RubyHid::Button.trigger_event(event.code, event.value)
+            when AXIS_TYPE
+              RubyHid::Axis.trigger_event(event.code, event.value)
+          end
+        end
+      end
+    end
+
+    #
+    # Stop the background worker, release it's resources.
+    #
+    def stop_watching
+      @worker.kill
+      @worker = nil
+    end
+
+  end
+end

data/lib/ruby_hid/observer.rb

@@ -0,0 +1,174 @@
+module RubyHid
+
+  #
+  # Observer parent class, shared code used by all the
+  # controller observer classes:
+  #
+  # * Button
+  #
+  # Shared functionality keeps an in-memory array of
+  # each controller event which has been referred to.
+  #
+  class Observer
+
+    #
+    # Dummy events hash, this should be set in
+    # the individual observer classes.
+    #
+    EVENTS = {}
+
+    @@observers = []
+
+    # events will be an array of lambdas
+    attr_accessor :name, :code, :events
+
+    #
+    # Create an observer object to observe all of this kind of observer
+    #
+    # If this isn't called directly, it will be created as
+    # required when find or find_by_name are called.
+    #
+    def self.build
+      self::EVENTS.each { |code, name| self.new(code, name) }
+    end
+
+    #
+    # Initialize a control observer
+    #
+    # Arguments:
+    #
+    # * code - Integer, the event code generated by this button
+    # * name - Symbol, the name of the button
+    #
+    def initialize(code, name)
+      @code = code
+      @name = name
+      @events = []
+      @@observers << self
+    end
+
+    #
+    # Find an observer of this type by its event code.
+    # Used by trigger_key to find an observer when
+    # its controller is used.
+    #
+    # Arguments:
+    #
+    # * code - Integer, event code to retrieve button by.
+    #
+    def self.find(code)
+      btn = @@observers.detect { |b| b.code == code }
+      if btn.nil?
+        btn = self.make_from_code(code)
+      end
+      btn
+    end
+
+    #
+    # Create an observer object of this type from a known code.
+    # used by find when the observer has not been initialised.
+    #
+    # Arguments:
+    #
+    # * code - Integer, event code to retrieve button by.
+    #
+    def self.make_from_code(code)
+      name = EVENTS[code]
+      if name
+        self.new(code, name)
+      else
+        nil
+      end
+    end
+
+    #
+    # Find an observer of this type by its event code.
+    #
+    # Arguments:
+    #
+    # * name - Symbol, a known button name (from BUTTONS)
+    #
+    def self.find_by_name(name)
+      btn = @@observers.detect { |b| b.name == name }
+      if btn.nil?
+        btn = self.make_from_name(name)
+      end
+      btn
+    end
+
+    #
+    # Create an observer of this type from a known name.
+    # Used in find_by_name when the observer has not been
+    # initialised.
+    #
+    # Arguments:
+    #
+    # * name - symbol, a known button name
+    #
+    def self.make_from_name(name)
+      code, btn_name = self::EVENTS.detect { |code, btn_name| btn_name == name }
+      if code
+        self.new(code, name)
+      else
+        nil
+      end
+    end
+
+
+    #
+    # Add a process to be triggered when this observers
+    # controller is changed.
+    #
+    # Arguments:
+    #
+    # * proc - Proc, ruby method to be called, without arguments on button press.
+    #
+    def add_event(proc)
+      @events << proc
+    end
+
+    #
+    # Trigger every proc in the @events array.
+    #
+    def trigger_events(value=nil)
+      @events.each do |event|
+        event.call(value)
+      end
+    end
+
+    #
+    # Find an observer of this type and run all
+    # of it's events.
+    #
+    # Used by RubyHid::Device when a control change
+    # is detected.
+    #
+    # Arguments:
+    #
+    # * code - Integer, event code to retrieve button by.
+    #
+    def self.trigger_event(code, value=nil)
+      btn = self.find(code)
+      if btn
+        btn.trigger_events(value)
+      else
+        puts unmapped_event_message(code)
+      end
+    rescue => er
+      puts "Error in observer #{code} event: #{er.message}"
+      puts er.backtrace
+    end
+
+    def self.unmapped_event_message(code)
+      <<-TEXT
+         ==============================================================
+         #{self} with event code #{code} has not been mapped.
+         Please add it to #{self}::EVENTS with a name.
+         ==============================================================
+
+      TEXT
+    end
+
+  end
+
+end

data/lib/ruby_hid.rb

@@ -0,0 +1,10 @@
+`sudo chmod 777 /sys/class/leds/*/brightness`
+`sudo chmod 777 /dev/input/event*`
+
+require_relative './ruby_hid/device.rb'
+require_relative './ruby_hid/observer.rb'
+require_relative './ruby_hid/button.rb'
+require_relative './ruby_hid/axis.rb'
+
+RubyHid::Axis.build
+RubyHid::Button.build

metadata

@@ -0,0 +1,51 @@
+--- !ruby/object:Gem::Specification
+name: ruby_hid
+version: !ruby/object:Gem::Version
+  version: 0.0.0
+platform: ruby
+authors:
+- Andrew Faraday
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-10-07 00:00:00.000000000 Z
+dependencies: []
+description: HID device observer library for Ruby applications. Currently only ubuntu
+  Linux distributions.
+email: andrewfaraday@hotmail.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENCE
+- README.md
+- lib/ruby_hid.rb
+- lib/ruby_hid/axis.rb
+- lib/ruby_hid/button.rb
+- lib/ruby_hid/device.rb
+- lib/ruby_hid/observer.rb
+homepage: https://github.com/AJFaraday/ruby-hid
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: HID game controller support for Ruby in Linux
+test_files: []