launchpad_mk2 0.0.1

data/lib/launchpad_mk2/errors.rb

@@ -0,0 +1,37 @@
+module LaunchpadMk2
+  
+  # Generic launchpad error.
+  class LaunchpadError < StandardError; end
+  
+  # Error raised when the MIDI device specified doesn't exist.
+  class NoSuchDeviceError < LaunchpadError; end
+  
+  # Error raised when the MIDI device specified is busy.
+  class DeviceBusyError < LaunchpadError; end
+  
+  # Error raised when an input has been requested, although
+  # launchpad has been initialized without input.
+  class NoInputAllowedError < LaunchpadError; end
+  
+  # Error raised when an output has been requested, although
+  # launchpad has been initialized without output.
+  class NoOutputAllowedError < LaunchpadError; end
+  
+  # Error raised when <tt>x/y</tt> coordinates outside of the grid
+  # or none were specified.
+  class NoValidGridCoordinatesError < LaunchpadError; end
+  
+  # Error raised when wrong brightness was specified.
+  class NoValidColorError < LaunchpadError; end
+  
+  # Error raised when anything fails while communicating
+  # with the launchpad.
+  class CommunicationError < LaunchpadError
+    attr_accessor :source
+    def initialize(e)
+      super(e.portmidi_error)
+      self.source = e
+    end
+  end
+  
+end

data/lib/launchpad_mk2/interaction.rb

@@ -0,0 +1,333 @@
+require 'launchpad_mk2/device'
+require 'launchpad_mk2/logging'
+
+module LaunchpadMk2
+  
+  # This class provides advanced interaction features.
+  # 
+  # Example:
+  # 
+  #   require 'launchpad_mk2'
+  #   
+  #   interaction = Launchpad::Interaction.new
+  #   interaction.response_to(:grid, :down) do |interaction, action|
+  #     interaction.device.change(:grid, action.merge(:red => :high))
+  #   end
+  #   interaction.response_to(:mixer, :down) do |interaction, action|
+  #     interaction.stop
+  #   end
+  #   
+  #   interaction.start
+  class Interaction
+
+    include Logging
+    
+    # Returns the Launchpad::Device the Launchpad::Interaction acts on.
+    attr_reader :device
+    
+    # Returns whether the Launchpad::Interaction is active or not.
+    attr_reader :active
+    
+    # Initializes the interaction.
+    # 
+    # Optional options hash:
+    # 
+    # [<tt>:device</tt>]            Launchpad::Device to act on,
+    #                               optional, <tt>:input_device_id/:output_device_id</tt> will be used if omitted
+    # [<tt>:input_device_id</tt>]   ID of the MIDI input device to use,
+    #                               optional, <tt>:device_name</tt> will be used if omitted
+    # [<tt>:output_device_id</tt>]  ID of the MIDI output device to use,
+    #                               optional, <tt>:device_name</tt> will be used if omitted
+    # [<tt>:device_name</tt>]       Name of the MIDI device to use,
+    #                               optional, defaults to "Launchpad"
+    # [<tt>:latency</tt>]           delay (in s, fractions allowed) between MIDI pulls,
+    #                               optional, defaults to 0.001 (1ms)
+    # [<tt>:logger</tt>]            [Logger] to be used by this interaction instance, can be changed afterwards
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoSuchDeviceError] when device with ID or name specified does not exist
+    # [Launchpad::DeviceBusyError] when device with ID or name specified is busy
+    def initialize(opts = nil)
+      @reader_thread = nil
+      @device = nil
+      opts ||= {}
+
+      self.logger = opts[:logger]
+      logger.debug "initializing Launchpad::Interaction##{object_id} with #{opts.inspect}"
+
+      @device ||= opts[:device]
+      @device ||= Device.new(opts.merge(
+        :input => true,
+        :output => true,
+        :logger => opts[:logger]
+      ))
+      @latency = (opts[:latency] || 0.001).to_f.abs
+      @active = false
+
+      @action_threads = ThreadGroup.new
+    end
+
+    # Sets the logger to be used by the current instance and the device.
+    # 
+    # [+logger+]  the [Logger] instance
+    def logger=(logger)
+      @logger = logger
+      @device.logger = logger if @device
+    end
+
+    # Closes the interaction's device - nothing can be done with the interaction/device afterwards.
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoInputAllowedError] when input is not enabled on the interaction's device
+    # [Launchpad::CommunicationError] when anything unexpected happens while communicating with the    
+    def close
+      logger.debug "closing Launchpad::Interaction##{object_id}"
+      stop
+      @device.close
+    end
+    
+    # Determines whether this interaction's device has been closed.
+    def closed?
+      @device.closed?
+    end
+    
+    # Starts interacting with the launchpad. Resets the device when
+    # the interaction was properly stopped via stop or close.
+    # 
+    # Optional options hash:
+    # 
+    # [<tt>:detached</tt>]  <tt>true/false</tt>,
+    #                       whether to detach the interaction, method is blocking when +false+,
+    #                       optional, defaults to +false+
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoInputAllowedError] when input is not enabled on the interaction's device
+    # [Launchpad::NoOutputAllowedError] when output is not enabled on the interaction's device
+    # [Launchpad::CommunicationError] when anything unexpected happens while communicating with the launchpad
+    def start(opts = nil)
+      logger.debug "starting Launchpad::Interaction##{object_id}"
+
+      opts = {
+        :detached => false
+      }.merge(opts || {})
+
+      @active = true
+
+      @reader_thread ||= Thread.new do
+        begin
+          while @active do
+            @device.read_pending_actions.each do |pending_action|
+              action_thread = Thread.new(pending_action) do |action|
+                respond_to_action(action)
+              end
+              @action_threads.add(action_thread)
+            end
+            sleep @latency# if @latency > 0.0
+          end
+        rescue Portmidi::DeviceError => e
+          logger.fatal "could not read from device, stopping to read actions"
+          raise CommunicationError.new(e)
+        rescue Exception => e
+          logger.fatal "error causing action reading to stop: #{e.inspect}"
+          raise e
+        end
+      end
+      @reader_thread.join unless opts[:detached]
+    end
+    
+    # Stops interacting with the launchpad.
+    # 
+    # Errors raised:
+    # 
+    # [Launchpad::NoInputAllowedError] when input is not enabled on the interaction's device
+    # [Launchpad::CommunicationError] when anything unexpected happens while communicating with the    
+    def stop
+      logger.debug "stopping Launchpad::Interaction##{object_id}"
+      @active = false
+      if @reader_thread
+        # run (resume from sleep) and wait for @reader_thread to end
+        @reader_thread.run if @reader_thread.alive?
+        @reader_thread.join
+        @reader_thread = nil
+      end
+    ensure
+      @action_threads.list.each do |thread|
+        begin
+          thread.kill
+          thread.join
+        rescue Exception => e
+          logger.error "error when killing action thread: #{e.inspect}"
+        end
+      end
+      nil
+    end
+    
+    # Registers a response to one or more actions.
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+types+] one or an array of button types to respond to,
+    #           additional value <tt>:all</tt> for all buttons
+    # [+state+] button state to respond to,
+    #           additional value <tt>:both</tt>
+    # 
+    # Optional options hash:
+    # 
+    # [<tt>:exclusive</tt>] <tt>true/false</tt>,
+    #                       whether to deregister all other responses to the specified actions,
+    #                       optional, defaults to +false+
+    # [<tt>:x</tt>]         x coordinate(s), can contain arrays and ranges, when specified
+    #                       without y coordinate, it's interpreted as a whole column
+    # [<tt>:y</tt>]         y coordinate(s), can contain arrays and ranges, when specified
+    #                       without x coordinate, it's interpreted as a whole row
+    # 
+    # Takes a block which will be called when an action matching the parameters occurs.
+    # 
+    # Block parameters:
+    # 
+    # [+interaction+] the interaction object that received the action
+    # [+action+]      the action received from Launchpad::Device.read_pending_actions
+    def response_to(types = :all, state = :both, opts = nil, &block)
+      logger.debug "setting response to #{types.inspect} for state #{state.inspect} with #{opts.inspect}"
+      types = Array(types)
+      opts ||= {}
+      no_response_to(types, state) if opts[:exclusive] == true
+      Array(state == :both ? %w(down up) : state).each do |current_state|
+        types.each do |type|
+          combined_types(type, opts).each do |combined_type|
+            responses[combined_type][current_state.to_sym] << block
+          end
+        end
+      end
+      nil
+    end
+    
+    # Deregisters all responses to one or more actions.
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+types+] one or an array of button types to respond to,
+    #           additional value <tt>:all</tt> for actions on all buttons
+    #           (but not meaning "all responses"),
+    #           optional, defaults to +nil+, meaning "all responses"
+    # [+state+] button state to respond to,
+    #           additional value <tt>:both</tt>
+    # 
+    # Optional options hash:
+    # 
+    # [<tt>:x</tt>] x coordinate(s), can contain arrays and ranges, when specified
+    #               without y coordinate, it's interpreted as a whole column
+    # [<tt>:y</tt>] y coordinate(s), can contain arrays and ranges, when specified
+    #               without x coordinate, it's interpreted as a whole row
+    def no_response_to(types = nil, state = :both, opts = nil)
+      logger.debug "removing response to #{types.inspect} for state #{state.inspect}"
+      types = Array(types)
+      Array(state == :both ? %w(down up) : state).each do |current_state|
+        types.each do |type|
+          combined_types(type, opts).each do |combined_type|
+            responses[combined_type][current_state.to_sym].clear
+          end
+        end
+      end
+      nil
+    end
+    
+    # Responds to an action by executing all matching responses, effectively simulating
+    # a button press/release.
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+type+]  type of the button to trigger
+    # [+state+] state of the button
+    # 
+    # Optional options hash (see Launchpad for values):
+    # 
+    # [<tt>:x</tt>]     x coordinate
+    # [<tt>:y</tt>]     y coordinate
+    def respond_to(type, state, opts = nil)
+      respond_to_action((opts || {}).merge(:type => type, :state => state))
+    end
+    
+    private
+    
+    # Returns the hash storing all responses. Keys are button types, values are
+    # hashes themselves, keys are <tt>:down/:up</tt>, values are arrays of responses.
+    def responses
+      @responses ||= Hash.new {|hash, key| hash[key] = {:down => [], :up => []}}
+    end
+
+    # Returns an array of grid positions for a range.
+    # 
+    # Parameters:
+    # 
+    # [+range+] the range definitions, can be
+    #           * a Fixnum
+    #           * a Range
+    #           * an Array of Fixnum, Range or Array objects
+    def grid_range(range)
+      return nil if range.nil?
+      Array(range).flatten.map do |pos|
+        pos.respond_to?(:to_a) ? pos.to_a : pos
+      end.flatten.uniq
+    end
+
+    # Returns a list of combined types for the type and opts specified. Combined
+    # types are just the type, except for grid, where the opts are interpreted
+    # and all combinations of x and y coordinates are added as a position suffix.
+    # 
+    # Example:
+    # 
+    # combined_types(:grid, :x => 1..2, y => 2) => [:grid12, :grid22]
+    # 
+    # Parameters (see Launchpad for values):
+    # 
+    # [+type+]  type of the button
+    # 
+    # Optional options hash:
+    # 
+    # [<tt>:x</tt>] x coordinate(s), can contain arrays and ranges, when specified
+    #               without y coordinate, it's interpreted as a whole column
+    # [<tt>:y</tt>] y coordinate(s), can contain arrays and ranges, when specified
+    #               without x coordinate, it's interpreted as a whole row
+    def combined_types(type, opts = nil)
+      if type.to_sym == :grid && opts
+        x = grid_range(opts[:x])
+        y = grid_range(opts[:y])
+        return [:grid] if x.nil? && y.nil?  # whole grid
+        x ||= ['-']                         # whole row
+        y ||= ['-']                         # whole column
+        x.product(y).map {|current_x, current_y| :"grid#{current_x}#{current_y}"}
+      else
+        [type.to_sym]
+      end
+    end
+    
+    # Reponds to an action by executing all matching responses.
+    # 
+    # Parameters:
+    # 
+    # [+action+]  hash containing an action from Launchpad::Device.read_pending_actions
+    def respond_to_action(action)
+      type = action[:type].to_sym
+      state = action[:state].to_sym
+      actions = []
+      if type == :grid
+        actions += responses[:"grid#{action[:x]}#{action[:y]}"][state]
+        actions += responses[:"grid#{action[:x]}-"][state]
+        actions += responses[:"grid-#{action[:y]}"][state]
+      end
+      actions += responses[type][state]
+      actions += responses[:all][state]
+      actions.compact.each {|block| block.call(self, action)}
+      nil
+    rescue Exception => e
+      logger.error "error when responding to action #{action.inspect}: #{e.inspect}"
+      raise e
+    end
+    
+  end
+  
+end

data/lib/launchpad_mk2/logging.rb

@@ -0,0 +1,27 @@
+require 'logger'
+
+module LaunchpadMk2
+
+  # This module provides logging facilities. Just include it to be able to log
+  # stuff.
+  module Logging
+
+    # Returns the logger to be used by the current instance.
+    # 
+    # Returns:
+    # 
+    # the logger set externally or a logger that swallows everything
+    def logger
+      @logger ||= Logger.new(nil)
+    end
+
+    # Sets the logger to be used by the current instance.
+    # 
+    # [+logger+]  the [Logger] instance
+    def logger=(logger)
+      @logger = logger
+    end
+
+  end
+
+end

data/lib/launchpad_mk2/midi_codes.rb

@@ -0,0 +1,40 @@
+module LaunchpadMk2
+  
+  # Module defining constants for MIDI codes.
+  module MidiCodes
+    
+    # Module defining MIDI status codes.
+    module Status
+      NIL           = 0x00
+      OFF           = 0x80
+      ON            = 0x90
+      CC            = 0xB0
+    end
+    
+    # Module defininig MIDI data 1 (note) codes for control buttons.
+    module ControlButton
+      UP            = 0x68
+      DOWN          = 0x69
+      LEFT          = 0x6A
+      RIGHT         = 0x6B
+      SESSION       = 0x6C
+      USER1         = 0x6D
+      USER2         = 0x6E
+      MIXER         = 0x6F
+    end
+    
+    # Module defininig MIDI data 1 (note) codes for scene buttons.
+    module SceneButton
+      SCENE1        = 0x59
+      SCENE2        = 0x4F
+      SCENE3        = 0x45
+      SCENE4        = 0x3B
+      SCENE5        = 0x31
+      SCENE6        = 0x27
+      SCENE7        = 0x1D
+      SCENE8        = 0x13
+    end
+    
+  end
+  
+end

data/lib/launchpad_mk2/version.rb

@@ -0,0 +1,3 @@
+module LaunchpadMk2
+  VERSION = '0.0.1'
+end

data/test/helper.rb

@@ -0,0 +1,45 @@
+require 'minitest/spec'
+require 'minitest/autorun'
+
+begin
+  require 'minitest/reporters'
+  MiniTest::Reporters.use!
+rescue LoadError
+  # ignore when it's not there - must be ruby 1.8
+end
+
+require 'mocha/setup'
+
+require 'launchpad_mk2'
+
+# mock Portmidi for tests
+module Portmidi
+  
+  class Input
+    attr_accessor :device_id
+    def initialize(device_id)
+      self.device_id = device_id
+    end
+    def read(*args); nil; end
+    def close; nil; end
+  end
+  
+  class Output
+    attr_accessor :device_id
+    def initialize(device_id)
+      self.device_id = device_id
+    end
+    def write(*args); nil; end
+    def write_sysex(*args); nil; end
+    def close; nil; end
+  end
+  
+  def self.input_devices; mock_devices; end
+  def self.output_devices; mock_devices; end
+  def self.start; end
+  
+end
+
+def mock_devices(opts = {})
+  [Portmidi::Device.new(opts[:id] || 1, 0, 0, opts[:name] || Launchpad::Device::MK2_DEVICE_NAME)]
+end