launchpad 0.0.2 → 0.1.0

data/README.rdoc

@@ -1,23 +1,70 @@
 = launchpad
 
-This gem provides an interface to access novation's launchpad programmatically. LEDs can be lighted and button presses can be evaluated using launchpad's MIDI input/output.
+This gem provides an interface to access novation's launchpad programmatically. LEDs can be lighted and button presses can be responded to. Internally, launchpad's MIDI input/output is used to accomplish this.
 
-This is the first version, nothing sophisticated, but you can access the launchpad already. In and out. The API might change quite a bit during the next releases, so don't rely on it, this is work in progress. If you need anything or think the interface could be improved in any way, please contact me.
+The interfaces should be rather stable now, so experiment with them and comment on their usability. This still is work in progress. If you need anything or think the interfaces could be improved in any way, please contact me.
 
-Sometimes, the launchpad won't react to anything. Don't despair, just dis- and reconnect the thing. It seems that some (unexpected) MIDI signals make it hickup.
+Sometimes, the launchpad won't react to anything or react to/light up the wrong LEDs. Don't despair, just dis- and reconnect the thing. It seems that some (unexpected) MIDI signals make it hickup.
 
 
 == Requirements
 
-* Jan Krutisch's portmidi gem
-* Roger B. Dannenberg's portmidi library
+* Roger B. Dannenberg's {portmidi library}[http://sourceforge.net/projects/portmedia/]
+* Jan Krutisch's {portmidi gem}[http://github.com/halfbyte/portmidi]
+
+
+== Installation
+
+The gem is hosted on Gemcutter[http://gemcutter.org/], so in order to use it, you're gonna install the gemcutter gem (for details, see their site):
+
+  gem install gemcutter
+  gem tumble
+
+After that, it's a simple gem install:
+
+  gem install launchpad
+
+
+== Usage
+
+There are two main entry points:
+
+* require 'launchpad/device', providing Launchpad::Device, which handles all the basic input/output stuff
+* require 'launchpad/interaction' or just 'launchpad', additionally providing Launchpad::Interaction, which lets you respond to actions (button presses/releases)
+
+This is a simple example (only requiring the device for output) that switches on all LEDs (for testing), resets the launchpad again and then lights the grid button at position 4/4 (from top left).
+
+  require 'rubygems'
+  require 'launchpad/device'
+  
+  device = Launchpad::Device.new
+  device.test_leds
+  sleep 1
+  device.reset
+  sleep 1
+  device.change :grid, :x => 4, :y => 4, :red => :high, :green => :low
+
+This is an interaction example lighting all grid buttons in red when pressed and keeping them lit.
+
+  require 'rubygems'
+  require 'launchpad'
+  
+  interaction = Launchpad::Interaction.new
+  interaction.response_to(:grid, :down) do |interaction, action|
+    interaction.device.change(:grid, action.merge(:red => :high))
+  end
+  
+  interaction.start
+
+
+For more details, see the examples. examples/color_picker.rb is the most complex example with interaction.
 
 
 == Near future plans
 
-* dedicated interaction with control buttons (top and right row)
-* listeners for presses on single buttons/button areas
-* double buffering (already there but has some glitches)
+* close devices properly as soon as halfbyte's pulled my changes to portmidi
+* interaction responses for presses on single grid buttons/button areas
+* double buffering
 * bitmap rendering
 
 

data/Rakefile

@@ -14,7 +14,8 @@ begin
     gem.version = Launchpad::VERSION
     gem.authors = ['Thomas Jachmann']
     gem.add_dependency('portmidi')
-    #gem.add_development_dependency 'thoughtbot-shoulda', '>= 0'
+    gem.add_development_dependency('thoughtbot-shoulda', '>= 0')
+    gem.add_development_dependency('mocha')
     # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
   end
   Jeweler::GemcutterTasks.new

data/examples/color_picker.rb

@@ -0,0 +1,99 @@
+require File.join(File.dirname(__FILE__), 'setup')
+
+# need to declare as instance variables here for being able to access
+# @interaction within interactors created by create_interactor_block
+device = Launchpad::Device.new
+interaction = Launchpad::Interaction.new(:device => device)
+
+# build color arrays for color display views
+colors_single = [
+  [ 0,  1,  2,  3,  0,  0,  0,  0],
+  [16, 17, 18, 19,  0,  0,  0,  0],
+  [32, 33, 34, 35,  0,  0,  0,  0],
+  [48, 49, 50, 51,  0,  0,  0,  0],
+  [0] * 8,
+  [0] * 8,
+  [0] * 8,
+  [0] * 8,
+  [0] * 8
+]
+colors_double = [
+  [ 0,  0,  1,  1,  2,  2,  3,  3],
+  [ 0,  0,  1,  1,  2,  2,  3,  3],
+  [16, 16, 17, 17, 18, 18, 19, 19],
+  [16, 16, 17, 17, 18, 18, 19, 19],
+  [32, 32, 33, 33, 34, 34, 35, 35],
+  [32, 32, 33, 33, 34, 34, 35, 35],
+  [48, 48, 49, 49, 50, 50, 51, 51],
+  [48, 48, 49, 49, 50, 50, 51, 51],
+  [0] * 8
+]
+colors_mirrored = [
+  [ 0,  1,  2,  3,  3,  2,  1,  0],
+  [16, 17, 18, 19, 19, 18, 17, 16],
+  [32, 33, 34, 35, 35, 34, 33, 32],
+  [48, 49, 50, 51, 51, 50, 49, 48],
+  [48, 49, 50, 51, 51, 50, 49, 48],
+  [32, 33, 34, 35, 35, 34, 33, 32],
+  [16, 17, 18, 19, 19, 18, 17, 16],
+  [ 0,  1,  2,  3,  3,  2,  1,  0],
+  [0] * 8
+]
+
+# setup color display views
+def display_color_view(colors)
+  lambda do |interaction, action|
+    # set color
+    interaction.device.change_all(colors)
+    # register mute interactor on scene buttons
+    interaction.response_to(%w(scene1 scene2 scene3 scene4 scene5 scene6 scene7 scene8), :down, :exclusive => true, &@mute)
+  end
+end
+interaction.response_to(:up, :down, &display_color_view(colors_single + [48, 16, 16, 16]))
+interaction.response_to(:down, :down, &display_color_view(colors_double + [16, 48, 16, 16]))
+interaction.response_to(:left, :down, &display_color_view(colors_mirrored + [16, 16, 48, 16]))
+
+# setup color picker view
+def display_color(opts)
+  lambda do |interaction, action|
+    @red = opts[:red] if opts[:red]
+    @green = opts[:green] if opts[:green]
+    colors = [(@green * 16 + @red)] * 64
+    scenes = [@red == 3 ? 51 : 3, @red == 2 ? 51 : 2, @red == 1 ? 51 : 1, @red == 0 ? 51 : 0, @green == 3 ? 51 : 48, @green == 2 ? 51 : 32, @green == 1 ? 51 : 16, @green == 0 ? 51 : 0]
+    interaction.device.change_all(colors + scenes + [16, 16, 16, 48])
+  end
+end
+interaction.response_to(:right, :down) do |interaction, action|
+  @red = 0
+  @green = 0
+  # register color picker interactors on scene buttons
+  interaction.response_to(:scene1, :down, :exclusive => true, &display_color(:red => 3))
+  interaction.response_to(:scene2, :down, :exclusive => true, &display_color(:red => 2))
+  interaction.response_to(:scene3, :down, :exclusive => true, &display_color(:red => 1))
+  interaction.response_to(:scene4, :down, :exclusive => true, &display_color(:red => 0))
+  interaction.response_to(:scene5, :down, :exclusive => true, &display_color(:green => 3))
+  interaction.response_to(:scene6, :down, :exclusive => true, &display_color(:green => 2))
+  interaction.response_to(:scene7, :down, :exclusive => true, &display_color(:green => 1))
+  interaction.response_to(:scene8, :down, :exclusive => true, &display_color(:green => 0))
+  # display color
+  interaction.respond_to(:scene8, :down)
+end
+
+# mixer button terminates interaction on button up
+interaction.response_to(:mixer) do |interaction, action|
+  interaction.device.change(:mixer, :red => action[:state] == :down ? :hi : :off)
+  interaction.stop if action[:state] == :up
+end
+
+# setup mute display interactors on all unused buttons
+@mute = display_color_view([0] * 72 + [16, 16, 16, 16])
+interaction.response_to(%w(session user1 user2 grid), :down, &@mute)
+
+# display mute view
+interaction.respond_to(:session, :down)
+
+# start interacting
+interaction.start
+
+# sleep so that the messages can be sent before the program terminates
+sleep 0.1

data/examples/colors.rb

@@ -1,20 +1,21 @@
 require File.join(File.dirname(__FILE__), 'setup')
 
-l = Launchpad.new(:input => false, :output => true)
-
-sleep 1
+device = Launchpad::Device.new(:input => false, :output => true)
 
 pos_x = pos_y = 0
 4.times do |red|
   4.times do |green|
-    l.single :x => pos_x, :y => pos_y, :red => red, :green => green, :mode => :buffering
-    l.single :x => 7 - pos_x, :y => pos_y, :red => red, :green => green, :mode => :buffering
-    l.single :x => pos_x, :y => 7 - pos_y, :red => red, :green => green, :mode => :buffering
-    l.single :x => 7 - pos_x, :y => 7 - pos_y, :red => red, :green => green, :mode => :buffering
+    device.change :grid, :x => pos_x, :y => pos_y, :red => red, :green => green
+    device.change :grid, :x => 7 - pos_x, :y => pos_y, :red => red, :green => green
+    device.change :grid, :x => pos_x, :y => 7 - pos_y, :red => red, :green => green
+    device.change :grid, :x => 7 - pos_x, :y => 7 - pos_y, :red => red, :green => green
     pos_y += 1
+    # sleep, otherwise the connection drops some messages - WTF?
+    sleep 0.01
   end
   pos_x += 1
   pos_y = 0
 end
 
-sleep 1
+# sleep so that the messages can be sent before the program terminates
+sleep 0.1

data/examples/doodle.rb

@@ -0,0 +1,68 @@
+require File.join(File.dirname(__FILE__), 'setup')
+
+interaction = Launchpad::Interaction.new
+
+current_color = {
+  :red    => :hi,
+  :green  => :hi,
+  :mode   => :normal
+}
+
+def update_scene_buttons(d, color)
+  on = {:red => :hi, :green => :hi}
+  d.change(:scene1, color[:red] == :hi ? on : {:red => :hi})
+  d.change(:scene2, color[:red] == :med ? on : {:red => :med})
+  d.change(:scene3, color[:red] == :lo ? on : {:red => :lo})
+  d.change(:scene4, color[:red] == :off ? on : {:red => :off})
+  d.change(:scene5, color[:green] == :hi ? on : {:green => :hi})
+  d.change(:scene6, color[:green] == :med ? on : {:green => :med})
+  d.change(:scene7, color[:green] == :lo ? on : {:green => :lo})
+  d.change(:scene8, color[:green] == :off ? on : {:green => :off})
+  d.change(:user1, :green => color[:mode] == :normal ? :lo : :hi, :mode => :flashing)
+  d.change(:user2, :green => color[:mode] == :normal ? :hi : :lo)
+end
+
+def choose_color(color, opts)
+  lambda do |interaction, action|
+    color.update(opts)
+    update_scene_buttons(interaction.device, color)
+  end
+end
+
+# register color picker interactors on scene buttons
+interaction.response_to(:scene1, :down, &choose_color(current_color, :red => :hi))
+interaction.response_to(:scene2, :down, &choose_color(current_color, :red => :med))
+interaction.response_to(:scene3, :down, &choose_color(current_color, :red => :lo))
+interaction.response_to(:scene4, :down, &choose_color(current_color, :red => :off))
+interaction.response_to(:scene5, :down, &choose_color(current_color, :green => :hi))
+interaction.response_to(:scene6, :down, &choose_color(current_color, :green => :med))
+interaction.response_to(:scene7, :down, &choose_color(current_color, :green => :lo))
+interaction.response_to(:scene8, :down, &choose_color(current_color, :green => :off))
+
+# register mode picker interactors on user buttons
+interaction.response_to(:user1, :down, &choose_color(current_color, :mode => :flashing))
+interaction.response_to(:user2, :down, &choose_color(current_color, :mode => :normal))
+
+# update scene buttons and start flashing
+update_scene_buttons(interaction.device, current_color)
+interaction.device.flashing_auto
+
+# feedback for grid buttons
+interaction.response_to(:grid, :down) do |interaction, action|
+  #coord = 16 * action[:y] + action[:x]
+  #brightness = flags[coord] ? :off : :hi
+  #flags[coord] = !flags[coord]
+  interaction.device.change(:grid, action.merge(current_color))
+end
+
+# mixer button terminates interaction on button up
+interaction.response_to(:mixer) do |interaction, action|
+  interaction.device.change(:mixer, :red => action[:state] == :down ? :hi : :off)
+  interaction.stop if action[:state] == :up
+end
+
+# start interacting
+interaction.start
+
+# sleep so that the messages can be sent before the program terminates
+sleep 0.1

data/examples/drawing_board.rb

@@ -0,0 +1,25 @@
+require File.join(File.dirname(__FILE__), 'setup')
+
+interaction = Launchpad::Interaction.new
+
+flags = Hash.new(false)
+
+# yellow feedback for grid buttons
+interaction.response_to(:grid, :down) do |interaction, action|
+  coord = 16 * action[:y] + action[:x]
+  brightness = flags[coord] ? :off : :hi
+  flags[coord] = !flags[coord]
+  interaction.device.change(:grid, action.merge(:red => brightness, :green => brightness))
+end
+
+# mixer button terminates interaction on button up
+interaction.response_to(:mixer) do |interaction, action|
+  interaction.device.change(:mixer, :red => action[:state] == :down ? :hi : :off)
+  interaction.stop if action[:state] == :up
+end
+
+# start interacting
+interaction.start
+
+# sleep so that the messages can be sent before the program terminates
+sleep 0.1

data/examples/feedback.rb

@@ -1,5 +1,34 @@
 require File.join(File.dirname(__FILE__), 'setup')
 
-Launchpad.start do |l, x, y, state|
-  l.single(:x => x, :y => y, :red => state ? 3 : 0)
+interaction = Launchpad::Interaction.new
+
+def brightness(action)
+  action[:state] == :down ? :hi : :off
+end
+
+# yellow feedback for grid buttons
+interaction.response_to(:grid) do |interaction, action|
+  b = brightness(action)
+  interaction.device.change(:grid, action.merge(:red => b, :green => b))
 end
+
+# red feedback for top control buttons
+interaction.response_to([:up, :down, :left, :right, :session, :user1, :user2, :mixer]) do |interaction, action|
+  interaction.device.change(action[:type], :red => brightness(action))
+end
+
+# green feedback for scene buttons
+interaction.response_to([:scene1, :scene2, :scene3, :scene4, :scene5, :scene6, :scene7, :scene8]) do |interaction, action|
+  interaction.device.change(action[:type], :green => brightness(action))
+end
+
+# mixer button terminates interaction on button up
+interaction.response_to(:mixer, :up) do |interaction, action|
+  interaction.stop
+end
+
+# start interacting
+interaction.start
+
+# sleep so that the messages can be sent before the program terminates
+sleep 0.1

data/examples/reset.rb

@@ -0,0 +1,6 @@
+require File.join(File.dirname(__FILE__), 'setup')
+
+Launchpad::Device.new.reset
+
+# sleep so that the messages can be sent before the program terminates
+sleep 0.1

data/examples/setup.rb

@@ -1,3 +1,5 @@
 # normally, this is done by rubygems (or whatever you use for your library management)
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
 require 'rubygems'
-require File.join(File.dirname(__FILE__), '..', 'lib', 'launchpad')
+require 'launchpad'

data/launchpad.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{launchpad}
-  s.version = "0.0.2"
+  s.version = "0.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Thomas Jachmann"]
-  s.date = %q{2009-11-08}
+  s.date = %q{2009-11-13}
   s.description = %q{This gem provides an interface to access novation's launchpad programmatically. LEDs can be lighted and button presses can be evaluated using launchpad's MIDI input/output.}
   s.email = %q{tom.j@gmx.net}
   s.extra_rdoc_files = [
@@ -22,15 +22,24 @@ Gem::Specification.new do |s|
      "LICENSE",
      "README.rdoc",
      "Rakefile",
+     "examples/color_picker.rb",
      "examples/colors.rb",
+     "examples/doodle.rb",
+     "examples/drawing_board.rb",
      "examples/feedback.rb",
+     "examples/reset.rb",
      "examples/setup.rb",
      "experiments/wandering_dot.rb",
      "launchpad.gemspec",
      "lib/launchpad.rb",
+     "lib/launchpad/device.rb",
+     "lib/launchpad/errors.rb",
+     "lib/launchpad/interaction.rb",
+     "lib/launchpad/midi_codes.rb",
      "lib/launchpad/version.rb",
      "test/helper.rb",
-     "test/test_launchpad-gem.rb"
+     "test/test_device.rb",
+     "test/test_interaction.rb"
   ]
   s.homepage = %q{http://github.com/thomasjachmann/launchpad}
   s.rdoc_options = ["--charset=UTF-8"]
@@ -39,9 +48,14 @@ Gem::Specification.new do |s|
   s.summary = %q{A gem for accessing novation's launchpad programmatically and easily.}
   s.test_files = [
     "test/helper.rb",
-     "test/test_launchpad-gem.rb",
+     "test/test_device.rb",
+     "test/test_interaction.rb",
+     "examples/color_picker.rb",
      "examples/colors.rb",
+     "examples/doodle.rb",
+     "examples/drawing_board.rb",
      "examples/feedback.rb",
+     "examples/reset.rb",
      "examples/setup.rb"
   ]
 
@@ -51,11 +65,17 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<portmidi>, [">= 0"])
+      s.add_development_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_development_dependency(%q<mocha>, [">= 0"])
     else
       s.add_dependency(%q<portmidi>, [">= 0"])
+      s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+      s.add_dependency(%q<mocha>, [">= 0"])
     end
   else
     s.add_dependency(%q<portmidi>, [">= 0"])
+    s.add_dependency(%q<thoughtbot-shoulda>, [">= 0"])
+    s.add_dependency(%q<mocha>, [">= 0"])
   end
 end
 

data/lib/launchpad.rb

@@ -1,167 +1,2 @@
-require 'portmidi'
-
-class Launchpad
-  
-  class LaunchpadError < StandardError; end
-  class NoInputAllowed < LaunchpadError; end
-  class NoOutputAllowed < LaunchpadError; end
-  class NoLocationError < LaunchpadError; end
-  class CommunicationError < LaunchpadError
-    attr_accessor :source
-    def initialize(e)
-      super(e.portmidi_error)
-      self.source = e
-    end
-  end
-  
-  OFF = 0x80
-  ON = 0x90
-  CC = 0xB0
-  
-  def initialize(opts = nil)
-    opts = {
-      :device_name  => 'Launchpad',
-      :input        => true,
-      :output       => true
-    }.merge(opts || {})
-    Portmidi.start
-    if opts[:input]
-      input_device = Portmidi.input_devices.select {|device| device.name == opts[:device_name]}.first
-      @input = Portmidi::Input.new(input_device.device_id)
-    end
-    if opts[:output]
-      output_device = Portmidi.output_devices.select {|device| device.name == opts[:device_name]}.first
-      @output = Portmidi::Output.new(output_device.device_id)
-      reset
-    end
-    @buffering = false
-  end
-  
-  def self.start(opts = nil, &block)
-    opts ||= {}
-    latency = (opts.delete(:latency) || 0.001).to_f
-    launchpad = Launchpad.new(opts.merge({:input => true, :output => true}))
-    loop do
-      messages = launchpad.input
-      if messages
-        messages.each do |message|
-          message = parse_message(message)
-          if message[:code] == ON
-            block.call(launchpad, message[:x], message[:y], message[:state])
-          end
-        end
-      end
-      sleep latency
-    end
-  rescue Portmidi::DeviceError => e
-    raise CommunicationError.new(e)
-  ensure
-    launchpad.reset if launchpad
-  end
-  
-  # Reset the launchpad - all settings are reset and all LEDs are switched off
-  def reset
-    output(CC, 0x00, 0x00)
-  end
-  
-  # Light all LEDs (for testing purposes)
-  # takes an optional parameter brightness (1-3, defaults to 3)
-  def light_all(brightness = 3)
-    output(CC, 0x00, 124 + min_max_color(brightness, false))
-  end
-  
-  def start_buffering
-    output(CC, 0x00, 0x31)
-    @buffering = true
-  end
-  
-  def flush_buffer(end_buffering = true)
-    output(CC, 0x00, 0x34)
-    if end_buffering
-      output(CC, 0x00, 0x30)
-      @buffering = false
-    end
-  end
-  
-  # Switches a single LED
-  # * :x      => x coordinate (0 based from top left, mandatory)
-  # * :y      => y coordinate (0 based from top left, mandatory)
-  # * :red    => brightness of red LED (0-3, optional, defaults to 0)
-  # * :green  => brightness of red LED (0-3, optional, defaults to 0)
-  # * :mode   => button behaviour (:normal, :flashing, :buffering, optional, defaults to :normal)
-  def single(opts)
-    location = location(opts)
-    velocity = velocity(opts)
-    output(ON, location, velocity)
-  end
-  
-  def multi(*velocities)
-    output(CC, 0x01, 0x00)
-    output(0x92, *velocities)
-  end
-  
-  # Switches LEDs marked as flashing on (when using custom timer for flashing)
-  def custom_flashing_on
-    output(CC, 0x00, 0x20)
-  end
-  
-  # Switches LEDs marked as flashing off (when using custom timer for flashing)
-  def custom_flashing_off
-    output(CC, 0x00, 0x21)
-  end
-  
-  # Starts flashing LEDs marked as flashing automatically
-  def start_auto_flashing
-    output(CC, 0x00, 0x28)
-  end
-  
-  # Stops flashing LEDs marked as flashing automatically (turning them on)
-  alias_method :stop_auto_flashing, :custom_flashing_on
-  
-  def coordinates(location)
-    [location % 16, location / 16]
-  end
-  
-  def input
-    raise NoInputAllowed if @input.nil?
-    @input.read(16)
-  end
-  
-  def output(*args)
-    raise NoOutputAllowed if @output.nil?
-    @output.write([{:message => args, :timestamp => 0}])
-  end
-  
-  private
-  
-  def self.parse_message(message)
-    message = message[:message]
-    {
-      :code   => message[0],
-      :x      => message[1] % 16,
-      :y      => message[1] / 16,
-      :state  => message[2] == 127
-    }
-  end
-  
-  def location(opts)
-    raise NoLocationError.new('you need to specify a location (x/y, 0 based from top left)') if (y = opts[:y]).nil? || (x = opts[:x]).nil?
-    y * 16 + x
-  end
-  
-  def velocity(opts)
-    red = min_max_color(opts[:red] || 0)
-    green = min_max_color(opts[:green] || 0)
-    flags = case opts[:mode]
-    when :flashing  then  8
-    when :buffering then  0
-    else                  12
-    end
-    (16 * (green)) + red + flags
-  end
-  
-  def min_max_color(color, with_off = true)
-    [[with_off ? 0 : 1, color.to_i].max, 3].min
-  end
-  
-end
+require 'launchpad/device'
+require 'launchpad/interaction'