ruby_buzz 0.0.2 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 13ed3645ae22adbdf04423671b8caf8103114680
4
- data.tar.gz: 96e818999e882cd82d77bd8a120a782444cc3c95
3
+ metadata.gz: 687713fa41a053eec7bd135075cb2d8d6fc0cd0f
4
+ data.tar.gz: 1269c37a63ab9049c34efdc072bf71a1028ee803
5
5
  SHA512:
6
- metadata.gz: 4310f00d7c22788182ff3e39efc430315e7d3c81242e36c54cbc1d5d99eb1246e63968c724a625e41cd95e94e7269a49e79f159275cfd498f67046c98a64b775
7
- data.tar.gz: 6732307f59e5db47647edf35c0b950c9dde5c509b6755f142bf528b68085d874ccb4d9b953acc1abd7962c526481c0c64b1f613a9e7928f6fb0e1cce0a24f828
6
+ metadata.gz: 6aaf22d93b2bc61774d6e036a279e9ae17789ad01166073ee67cd5e414ceec46f67254140d93a482698a7b9d22953a27fb67f290c3700695e074d72edc20ba85
7
+ data.tar.gz: 25a1a11aabf2424bff0245d5afe7b6adc0578e2c6dae8329c0d1ddd31f390e7b6f7cde891fc1b4563760873e017c0abc1efe2661f9adb2abbf83d348cac31059
@@ -1,4 +1,24 @@
1
1
  module RubyBuzz
2
+ #
3
+ # Handles a single button on the Buzz controllers.
4
+ #
5
+ # Identified by event code, all between 704 and 723.
6
+ # Also identifiable by pad and name.
7
+ #
8
+ # Possible names:
9
+ #
10
+ # * buzz
11
+ # * yellow
12
+ # * green
13
+ # * orange
14
+ # * blue
15
+ #
16
+ # Initialized in RubyBuzz::Pad.init_mappings
17
+ #
18
+ # Each button holds an array of events, each of which is a
19
+ # Proc to be called without arguments. These are called when
20
+ # the button is pushed.
21
+ #
2
22
  class Button
3
23
 
4
24
  @@buttons = []
@@ -6,6 +26,17 @@ module RubyBuzz
6
26
  # events will be an array of lambdas
7
27
  attr_accessor :name, :code, :events
8
28
 
29
+ #
30
+ # Initialize a button
31
+ #
32
+ # called in RubyBuzz::Pad.init_mappings
33
+ #
34
+ # Arguments:
35
+ #
36
+ # * code - Integer, the evnt code generated by this button (704-723)
37
+ # * name - Symbol, the name of the button, for referncing via the Pad object
38
+ # * pad - RubyBuzz::Pad, the object this button belongs to
39
+ #
9
40
  def initialize(code, name, pad)
10
41
  @code = code
11
42
  @name = name
@@ -14,20 +45,47 @@ module RubyBuzz
14
45
  @@buttons << self
15
46
  end
16
47
 
48
+ #
49
+ # Find a button by its event code. Used by trigger_key
50
+ # to find a button when one is pushed.
51
+ #
52
+ # Arguments:
53
+ #
54
+ # * code - Integer, event code to retrieve button by.
55
+ #
17
56
  def self.find(code)
18
57
  @@buttons.detect { |b| b.code == code }
19
58
  end
20
59
 
60
+ #
61
+ # Add a process to be triggered when this button is pressed.
62
+ #
63
+ # Arguments:
64
+ #
65
+ # * proc - Proc, ruby method to be called, without arguments on button press.
66
+ #
21
67
  def add_event(proc)
22
68
  @events << proc
23
69
  end
24
70
 
71
+ #
72
+ # Trigger every proc in the @events array.
73
+ #
25
74
  def trigger_events
26
75
  @events.each do |event|
27
76
  event.call
28
77
  end
29
78
  end
30
79
 
80
+ #
81
+ # Find a button and run all it's events.
82
+ #
83
+ # Used by RubyBuzz::Device when button is pushed.
84
+ #
85
+ # Arguments:
86
+ #
87
+ # * code - Integer, event code to retrieve button by.
88
+ #
31
89
  def self.trigger_key(code)
32
90
  btn = self.find(code)
33
91
  btn.trigger_events
@@ -1,6 +1,19 @@
1
- #!/usr/bin/env ruby
2
-
3
1
  module RubyBuzz
2
+ #
3
+ # The main interface for the Buzz controllers. Primarily
4
+ # used to monitor key pushes and trigger events. Keep a single
5
+ # instance of the class:
6
+ #
7
+ # `RubyBuzz::Device.new`
8
+ #
9
+ # The `each` method exposes events directly as they come in
10
+ #
11
+ # `device.each { |event| puts event }`
12
+ #
13
+ # The `start_watching` method starts a background job which
14
+ # runs the events bound to each button via the RubyBuzz::Button
15
+ # class. You can end this worker with `stop_watching`.
16
+ #
4
17
  class Device
5
18
 
6
19
  require 'time'
@@ -12,6 +25,8 @@ module RubyBuzz
12
25
 
13
26
  Event = Struct.new(:tv_sec, :tv_usec, :type, :code, :value)
14
27
  # open Event class and add some convenience methods
28
+ #
29
+ # Holds the un-packed data parsed from the raw input from the buzz controller.
15
30
  class Event
16
31
  def time;
17
32
  Time.at(tv_sec)
@@ -25,6 +40,12 @@ module RubyBuzz
25
40
  end
26
41
  end
27
42
 
43
+ #
44
+ # Initialise device, getting event file from /dev/input/by-id/
45
+ #
46
+ # You can override this to a different event, but ruby-buzz only
47
+ # supports a single usb controller.
48
+ #
28
49
  def initialize(filename=nil)
29
50
  @dev = File.open(filename || DEFAULT_FILE_NAME)
30
51
  @block_size = 24
@@ -33,16 +54,24 @@ module RubyBuzz
33
54
  raise er
34
55
  end
35
56
 
57
+ #
58
+ # The format for each 24 bit data chunk taken from the event stream.
59
+ #
36
60
  def format
37
61
  'qqSSl'
38
62
  end
39
63
 
40
-
64
+ #
65
+ # Read a single 24-bit block.
66
+ #
41
67
  def read
42
68
  bin = @dev.read @block_size
43
69
  Event.new *bin.unpack(format)
44
70
  end
45
71
 
72
+ #
73
+ # Expose each event to a block of code as it comes in.
74
+ #
46
75
  def each
47
76
  begin
48
77
  loop do
@@ -55,7 +84,10 @@ module RubyBuzz
55
84
  end
56
85
  end
57
86
 
58
-
87
+ #
88
+ # Start a background worker which scans input file
89
+ # and triggers any events bound to each one.
90
+ #
59
91
  def start_watching
60
92
  return if @worker
61
93
  @worker = Thread.new do
@@ -68,6 +100,9 @@ module RubyBuzz
68
100
  end
69
101
  end
70
102
 
103
+ #
104
+ # Stop the background worker, release it's resources.
105
+ #
71
106
  def stop_watching
72
107
  @worker.kill
73
108
  @worker = nil
@@ -1,29 +1,67 @@
1
1
  module RubyBuzz
2
+ #
3
+ # Each Pad has one LED light under the buzzer button.
4
+ #
5
+ # There are four Light objects, each controls one of these lights.
6
+ #
7
+ # Accessed via Pad:
8
+ #
9
+ # `RubyBuzz::Pad[0].light`
10
+ #
11
+ # Controlled individually:
12
+ #
13
+ # * `RubyBuzz::Pad[0].light.on`
14
+ # * `RubyBuzz::Pad[0].light.off`
15
+ #
16
+ # Controlled together:
17
+ #
18
+ # * RubyBuzz::Light.all_on
19
+ # * RubyBuzz::Light.all_off
20
+ #
2
21
  class Light
3
22
 
4
23
  @@lights = []
5
24
  attr_accessor :file
6
25
 
26
+ #
27
+ # Initialize a buzzer by index 0 to 3.
28
+ #
29
+ # Arguments:
30
+ #
31
+ # * index - Integer, 0 to 3, which light does this represent.
32
+ #
7
33
  def initialize(index)
8
34
  @file = `ls /sys/class/leds/*buzz#{index + 1}/brightness`
9
35
  @@lights << self
10
36
  end
11
37
 
38
+ #
39
+ # Turn the light on
40
+ #
12
41
  def on
13
42
  `echo 1 > #{file}`
14
43
  return nil
15
44
  end
16
45
 
46
+ #
47
+ # Turn the light off
48
+ #
17
49
  def off
18
50
  `echo 0 > #{file}`
19
51
  return nil
20
52
  end
21
53
 
54
+ #
55
+ # Turn all lights off
56
+ #
22
57
  def self.all_off
23
58
  @@lights.each{|l|l.off}
24
59
  return nil
25
60
  end
26
61
 
62
+ #
63
+ # Turn all lights on
64
+ #
27
65
  def self.all_on
28
66
  @@lights.each{|l|l.on }
29
67
  return nil
@@ -1,7 +1,38 @@
1
- # Each of these is an individual players controller
2
1
  module RubyBuzz
2
+ # Each of these is an individual players controller
3
+ #
4
+ # Each USB device has four of these.
5
+ #
6
+ # Each pad has 5 buttons:
7
+ #
8
+ # * buzz
9
+ # * yellow
10
+ # * green
11
+ # * orange
12
+ # * blue
13
+ #
14
+ # Accessed by `pad.buttons[:buzz]` etc
15
+ #
16
+ # Each pad has a single LED light under the buzz button.
17
+ #
18
+ # Accessed by `pad.light`
19
+ #
20
+ # Accessing Pad objects:
21
+ #
22
+ # * `Pad.all`
23
+ # * `Pad[0]` etc.
24
+ #
25
+ # Defining an event on a button
26
+ #
27
+ # `pad.add_event(:buzz, lambda{ puts 'Buzz pushed!' })`
28
+ #
29
+ # Triggering a button event (for debugging)
30
+ #
31
+ # `pad.trigger_events(:buzz)`
32
+ #
3
33
  class Pad
4
34
 
35
+ # Event code mappings for each button. Split into pads.
5
36
  # {event_code => button_name}
6
37
  MAPPINGS = [
7
38
  {
@@ -36,6 +67,10 @@ module RubyBuzz
36
67
 
37
68
  attr_accessor :buttons, :light
38
69
 
70
+ # called by lib/ruby_buzz.rb
71
+ #
72
+ # Reads the MAPPINGS constant and creates the 4 pad objects.
73
+ #
39
74
  def self.init_mappings
40
75
  @@pads = []
41
76
  MAPPINGS.each_with_index do |mapping, index|
@@ -43,14 +78,28 @@ module RubyBuzz
43
78
  end
44
79
  end
45
80
 
81
+ #
82
+ # Returns all four pads in index order.
83
+ #
46
84
  def self.all
47
85
  @@pads
48
86
  end
49
87
 
88
+ #
89
+ # Call a specific pad by index (0 to 3)
90
+ #
50
91
  def self.[](index)
51
92
  @@pads[index]
52
93
  end
53
94
 
95
+ #
96
+ # Initialize pad objects, called by init_mappings
97
+ #
98
+ # Arguments:
99
+ #
100
+ # * mapping - hash of event codes against button name (from MAPPINGS)
101
+ # * index - index of this pad, from 0 to 3
102
+ #
54
103
  def initialize(mapping, index)
55
104
  @index = index
56
105
  @buttons = {}
@@ -60,10 +109,31 @@ module RubyBuzz
60
109
  end
61
110
  end
62
111
 
112
+ #
113
+ # Add an event mapping, to be triggered on button push.
114
+ #
115
+ # Arguments:
116
+ #
117
+ # * button_name - Symbol, name of the button to be pushed
118
+ # * proc - Proc, a ruby method to be called.
119
+ #
120
+ # As the Proc is run on a separate thread, with the same environment,
121
+ # it is wise to change data in a shared space (for instance, a class
122
+ # variable or a setter method) for the main body of your code to
123
+ # respond to instead of doing the heavy lifting in the button event.
124
+ #
63
125
  def add_event(button_name, proc)
64
126
  @buttons[button_name].add_event proc
65
127
  end
66
128
 
129
+ #
130
+ # For debugging: Trigger a button event directly.
131
+ # Also called by watcher in RubyBuzz::Device.
132
+ #
133
+ # Arguments:
134
+ #
135
+ # * button_name - Symbol name of buzzer (:buzz, :yellow, :green, :orange, :blue)
136
+ #
67
137
  def trigger_event(button_name)
68
138
  @buttons[button_name].trigger_events
69
139
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: ruby_buzz
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.0.2
4
+ version: 0.0.3
5
5
  platform: ruby
6
6
  authors:
7
7
  - Andrew Faraday
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2015-09-19 00:00:00.000000000 Z
11
+ date: 2015-09-23 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: Light control and button event observers for wired Buzz™ controllers
14
14
  in Ruby on Linux