ruby_buzz 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 13ed3645ae22adbdf04423671b8caf8103114680
-  data.tar.gz: 96e818999e882cd82d77bd8a120a782444cc3c95
+  metadata.gz: 687713fa41a053eec7bd135075cb2d8d6fc0cd0f
+  data.tar.gz: 1269c37a63ab9049c34efdc072bf71a1028ee803
 SHA512:
-  metadata.gz: 4310f00d7c22788182ff3e39efc430315e7d3c81242e36c54cbc1d5d99eb1246e63968c724a625e41cd95e94e7269a49e79f159275cfd498f67046c98a64b775
-  data.tar.gz: 6732307f59e5db47647edf35c0b950c9dde5c509b6755f142bf528b68085d874ccb4d9b953acc1abd7962c526481c0c64b1f613a9e7928f6fb0e1cce0a24f828
+  metadata.gz: 6aaf22d93b2bc61774d6e036a279e9ae17789ad01166073ee67cd5e414ceec46f67254140d93a482698a7b9d22953a27fb67f290c3700695e074d72edc20ba85
+  data.tar.gz: 25a1a11aabf2424bff0245d5afe7b6adc0578e2c6dae8329c0d1ddd31f390e7b6f7cde891fc1b4563760873e017c0abc1efe2661f9adb2abbf83d348cac31059

data/lib/ruby_buzz/button.rb

@@ -1,4 +1,24 @@
 module RubyBuzz
+  #
+  # Handles a single button on the Buzz controllers.
+  #
+  # Identified by event code, all between 704 and 723.
+  # Also identifiable by pad and name.
+  #
+  # Possible names:
+  #
+  # * buzz
+  # * yellow
+  # * green
+  # * orange
+  # * blue
+  #
+  # Initialized in RubyBuzz::Pad.init_mappings
+  #
+  # Each button holds an array of events, each of which is a
+  # Proc to be called without arguments. These are called when
+  # the button is pushed.
+  #
   class Button
 
     @@buttons = []
@@ -6,6 +26,17 @@ module RubyBuzz
     # events will be an array of lambdas
     attr_accessor :name, :code, :events
 
+    #
+    # Initialize a button
+    #
+    # called in RubyBuzz::Pad.init_mappings
+    #
+    # Arguments:
+    #
+    # * code - Integer, the evnt code generated by this button (704-723)
+    # * name - Symbol, the name of the button, for referncing via the Pad object
+    # * pad - RubyBuzz::Pad, the object this button belongs to
+    #
     def initialize(code, name, pad)
       @code = code
       @name = name
@@ -14,20 +45,47 @@ module RubyBuzz
       @@buttons << self
     end
 
+    #
+    # Find a button by its event code. Used by trigger_key
+    # to find a button when one is pushed.
+    #
+    # Arguments:
+    #
+    # * code - Integer, event code to retrieve button by.
+    #
     def self.find(code)
       @@buttons.detect { |b| b.code == code }
     end
 
+    #
+    # Add a process to be triggered when this button is pressed.
+    #
+    # 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
       @events.each do |event|
         event.call
       end
     end
 
+    #
+    # Find a button and run all it's events.
+    #
+    # Used by RubyBuzz::Device when button is pushed.
+    #
+    # Arguments:
+    #
+    # * code - Integer, event code to retrieve button by.
+    #
     def self.trigger_key(code)
       btn = self.find(code)
       btn.trigger_events

data/lib/ruby_buzz/device.rb

@@ -1,6 +1,19 @@
-#!/usr/bin/env ruby
-
 module RubyBuzz
+  #
+  # The main interface for the Buzz controllers. Primarily
+  # used to monitor key pushes and trigger events. Keep a single
+  # instance of the class:
+  #
+  # `RubyBuzz::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 RubyBuzz::Button
+  # class. You can end this worker with `stop_watching`.
+  #
   class Device
 
     require 'time'
@@ -12,6 +25,8 @@ module RubyBuzz
 
     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)
@@ -25,6 +40,12 @@ module RubyBuzz
       end
     end
 
+    #
+    # Initialise device, getting event file from /dev/input/by-id/
+    #
+    # You can override this to a different event, but ruby-buzz only
+    # supports a single usb controller.
+    #
     def initialize(filename=nil)
       @dev = File.open(filename || DEFAULT_FILE_NAME)
       @block_size = 24
@@ -33,16 +54,24 @@ module RubyBuzz
       raise er
     end
 
+    #
+    # The format for each 24 bit data chunk taken from the event stream.
+    #
     def format
       'qqSSl'
     end
 
-
+    #
+    # Read a single 24-bit 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
@@ -55,7 +84,10 @@ module RubyBuzz
       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
@@ -68,6 +100,9 @@ module RubyBuzz
       end
     end
 
+    #
+    # Stop the background worker, release it's resources.
+    #
     def stop_watching
       @worker.kill
       @worker = nil

data/lib/ruby_buzz/light.rb

@@ -1,29 +1,67 @@
 module RubyBuzz
+  #
+  # Each Pad has one LED light under the buzzer button.
+  #
+  # There are four Light objects, each controls one of these lights.
+  #
+  # Accessed via Pad:
+  #
+  # `RubyBuzz::Pad[0].light`
+  #
+  # Controlled individually:
+  #
+  # * `RubyBuzz::Pad[0].light.on`
+  # * `RubyBuzz::Pad[0].light.off`
+  #
+  # Controlled together:
+  #
+  # * RubyBuzz::Light.all_on
+  # * RubyBuzz::Light.all_off
+  #
   class Light
 
     @@lights = []
     attr_accessor :file
 
+    #
+    # Initialize a buzzer by index 0 to 3.
+    #
+    # Arguments:
+    #
+    # * index - Integer, 0 to 3, which light does this represent.
+    #
     def initialize(index)
       @file = `ls /sys/class/leds/*buzz#{index + 1}/brightness`
       @@lights << self
     end
 
+    #
+    # Turn the light on
+    #
     def on
       `echo 1 > #{file}`
       return nil
     end
 
+    #
+    # Turn the light off
+    #
     def off
       `echo 0 > #{file}`
       return nil
     end
 
+    #
+    # Turn all lights off
+    #
     def self.all_off
       @@lights.each{|l|l.off}
       return nil
     end
 
+    #
+    # Turn all lights on
+    #
     def self.all_on
       @@lights.each{|l|l.on }
       return nil

data/lib/ruby_buzz/pad.rb

@@ -1,7 +1,38 @@
-# Each of these is an individual players controller
 module RubyBuzz
+  # Each of these is an individual players controller
+  #
+  # Each USB device has four of these.
+  #
+  # Each pad has 5 buttons:
+  #
+  # * buzz
+  # * yellow
+  # * green
+  # * orange
+  # * blue
+  #
+  # Accessed by `pad.buttons[:buzz]` etc
+  #
+  # Each pad has a single LED light under the buzz button.
+  #
+  # Accessed by `pad.light`
+  #
+  # Accessing Pad objects:
+  #
+  # * `Pad.all`
+  # * `Pad[0]` etc.
+  #
+  # Defining an event on a button
+  #
+  # `pad.add_event(:buzz, lambda{ puts 'Buzz pushed!' })`
+  #
+  # Triggering a button event (for debugging)
+  #
+  # `pad.trigger_events(:buzz)`
+  #
   class Pad
 
+    # Event code mappings for each button. Split into pads.
     # {event_code => button_name}
     MAPPINGS = [
       {
@@ -36,6 +67,10 @@ module RubyBuzz
 
     attr_accessor :buttons, :light
 
+    # called by lib/ruby_buzz.rb
+    #
+    # Reads the MAPPINGS constant and creates the 4 pad objects.
+    #
     def self.init_mappings
       @@pads = []
       MAPPINGS.each_with_index do |mapping, index|
@@ -43,14 +78,28 @@ module RubyBuzz
       end
     end
 
+    #
+    # Returns all four pads in index order.
+    #
     def self.all
       @@pads
     end
 
+    #
+    # Call a specific pad by index (0 to 3)
+    #
     def self.[](index)
       @@pads[index]
     end
 
+    #
+    # Initialize pad objects, called by init_mappings
+    #
+    # Arguments:
+    #
+    # * mapping - hash of event codes against button name (from MAPPINGS)
+    # * index - index of this pad, from 0 to 3
+    #
     def initialize(mapping, index)
       @index = index
       @buttons = {}
@@ -60,10 +109,31 @@ module RubyBuzz
       end
     end
 
+    #
+    # Add an event mapping, to be triggered on button push.
+    #
+    # Arguments:
+    #
+    # * button_name - Symbol, name of the button to be pushed
+    # * proc - Proc, a ruby method to be called.
+    #
+    # As the Proc is run on a separate thread, with the same environment,
+    # it is wise to change data in a shared space (for instance, a class
+    # variable or a setter method) for the main body of your code to
+    # respond to instead of doing the heavy lifting in the button event.
+    #
     def add_event(button_name, proc)
       @buttons[button_name].add_event proc
     end
 
+    #
+    # For debugging: Trigger a button event directly.
+    # Also called by watcher in RubyBuzz::Device.
+    #
+    # Arguments:
+    #
+    # * button_name - Symbol name of buzzer (:buzz, :yellow, :green, :orange, :blue)
+    #
     def trigger_event(button_name)
       @buttons[button_name].trigger_events
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby_buzz
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Andrew Faraday
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-09-19 00:00:00.000000000 Z
+date: 2015-09-23 00:00:00.000000000 Z
 dependencies: []
 description: Light control and button event observers for wired Buzz™ controllers
   in Ruby on Linux