monome_serial 1.0.0

data/docs/CONTRIBUTORS

@@ -0,0 +1 @@
+Sam Aaron - samaaron@gmail.com

data/docs/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009 Sam Aaron
+
+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/docs/TODO

@@ -0,0 +1,79 @@
+make some kind of use of these mappings...
+ MMAP_COORDS_256 = {
+    [0,0] => {
+      :top    => ["00001111"],
+      :bottom => ["11110000"],
+      :left   => ["00000000"],
+      :right  => ["11111111"]
+    },
+
+    [15,15] => {
+      :top    => ["11110000"],
+      :bottom => ["00001111"],
+      :left   => ["11111111"],
+      :right  => ["00000000"]
+    },
+
+    [7,7] => {
+      :top    => ["01111000"],
+      :bottom => ["10000111"],
+      :left   => ["01110111"],
+      :right  => ["10001000"]
+    },
+
+    [2,9] => {
+      :top    => ["10011101"],
+      :bottom => ["01100010"],
+      :left   => ["00101001"],
+      :right  => ["11010110"]
+    },
+
+    [10,4] => {
+      :top    => ["01000101"],
+      :bottom => ["10111010"],
+      :left   => ["10100100"],
+      :right  => ["01011011"]
+    }
+  }
+
+  PMAP_COORDS_TO_MMAP_COORDS = {
+      #pmap      #mmap
+      :top    => :right,
+      :bottom => :left,
+      :left   => :top,
+      :right  => :bottom
+  }
+
+  MMAP_ROW_256 = {
+    [1,255] => {
+      #left to right, 11111111
+      :right  => ["01001110", "11111111"],
+      :bottom => ["01011110", "11111111"],
+      :left   => ["01000001", "11111111"],
+      :top    => ["01010001", "11111111"]
+    },
+
+    [1,0] => {
+      #left to right, 00000000
+      :right  => ["01001110", "00000000"],
+      :bottom => ["01011110", "00000000"],
+      :left   => ["01000001", "00000000"],
+      :top    => ["01010001", "00000000"]
+    },
+
+    [1,197] => {
+      #left to right, 10100011
+      :right  => ["01001110", "10100011"],
+      :bottom => ["01011110", "11000101"],
+      :left   => ["01000001", "11000101"],
+      :top    => ["01010001", "10100011"]
+    },
+
+    [1, 197, 47] => {
+      #left to right, 1010001111110100
+      :right  => ["01101110", "11110100", "10100011"],
+      :bottom => ["01111110", "11000101", "00101111"],
+      :left   => ["01100001", "11000101", "00101111"],
+      :top    => ["01110001", "11110100", "10100011"]
+    }
+  }

data/examples/toggler.rb

@@ -0,0 +1,6 @@
+require 'rubygems'
+require 'monome_serial'
+
+thread = MonomeSerial::Examples::Toggle.new.start
+thread.join
+

data/lib/monome_serial.rb

@@ -0,0 +1,40 @@
+#require external libraries
+require 'activesupport'
+require 'fcntl'
+
+require 'monome_serial/serial_communicator'
+require 'monome_serial/serial_communicator/communicator'
+require 'monome_serial/serial_communicator/dummy_communicator'
+require 'monome_serial/serial_communicator/binary_patterns/series'
+require 'monome_serial/serial_communicator/binary_patterns/fourtyh'
+require 'monome_serial/monome_communicator'
+require 'monome_serial/examples/toggle'
+
+module MonomeSerial
+  class NoMonomesFoundError < StandardError ; end
+
+  def self.detect_monome
+    detect_monomes.first
+  end
+
+  def self.detect_monomes
+    find_ttys.map{|tty| MonomeCommunicator.new(tty)}
+  end
+
+  def self.find_ttys
+    possible_monome_io_file_matchers = ['/dev/ttyUSB*', '/dev/tty.usbserial-m*']
+    files = possible_monome_io_file_matchers.inject([]) do |files, to_try|
+      files << Dir[to_try]
+    end
+
+    files.flatten!
+
+    if files.empty? then
+      raise NoMonomesFoundError,
+      "No monomes were found connected to your computer"
+    end
+
+    files
+  end
+end
+

data/lib/monome_serial/examples/toggle.rb

@@ -0,0 +1,44 @@
+module MonomeSerial
+  module Examples
+    class Toggle
+      def initialize
+
+        @monome = MonomeSerial.detect_monome
+        @light_lit = Hash.new(false)
+      end
+
+      # Enter a loop in which you read events from the monome and if the
+      # event is a :keypress, then toggle the led on the monome
+      def start
+        Thread.new do
+          loop do
+            action, x, y = @monome.read
+            toggle_led(x,y) if action == :keydown
+          end
+        end
+      end
+
+      private
+
+      def toggle_led(x,y)
+        toggle_led_on_monome(x,y)
+        toggle_led_status(x,y)
+      end
+
+      # Depending on the state of the @light_lit hash for the given
+      # coordinates, extinguish or illuminate the monome's lamp
+      def toggle_led_on_monome(x,y)
+        if @light_lit[[x,y]]
+          @monome.extinguish_lamp(x,y)
+        else
+          @monome.illuminate_lamp(x,y)
+        end
+      end
+
+      def toggle_led_status(x,y)
+        @light_lit[[x,y]] = !@light_lit[[x,y]]
+      end
+    end
+  end
+end
+

data/lib/monome_serial/monome_communicator.rb

@@ -0,0 +1,90 @@
+module MonomeSerial
+  class MonomeCommunicator
+    #It's important to note that the vanilla behaviour of these methods
+    #doesn't match that of the OSC protocol specification as implemented
+    #by the original OS X MonomeSerial application. In order to match
+    #these behviours it is necessary to map the calls appropriately for
+    #the given device and rotation. This class just provides raw access
+    #to the serial protocol and serves it unadultered.
+
+    attr_reader :communicator, :serial, :protocol
+
+    def initialize(tty_path, protocol="series")
+      raise ArgumentError, "Unexpected protocol type: #{protocol}. Expected 40h or series" unless protocol == "40h" || protocol == "series"
+
+      @protocol = protocol
+
+      #try to pull out serial for the monome represented by
+      #this tty_path
+      match  = tty_path.match /m(\d+h?)-(\d+)/
+      @serial = match ? match[2] : "Serial Unknown"
+
+      #get communicator (will return a DummyCommunicator if the path
+      #isn't correct)
+      @communicator = SerialCommunicator.get_communicator(tty_path)
+
+      #include the correct binary patterns
+      if @protocol == "40h"
+        extend SerialCommunicator::BinaryPatterns::Fourtyh
+      else
+        extend SerialCommunicator::BinaryPatterns::Series
+      end
+    end
+
+    def illuminate_lamp(x,y)
+      @communicator.write([led_on_pattern,  x_y_coord_pattern(x,y)])
+    end
+
+    def extinguish_lamp(x,y)
+      @communicator.write([led_off_pattern, x_y_coord_pattern(x,y)])
+    end
+
+    def illuminate_row(row, pattern)
+      case pattern.size
+      when 8 then
+        @communicator.write([row_of_8_pattern(row), pattern])
+      when 16 then
+        @communicator.write([row_of_16_pattern(row), pattern[0..7], pattern[8..15]])
+      else
+        raise ArgumentError, "Incorrect length of pattern sent to MonomeSerial::Monome#illumninate_row. Expected 8 or 16, got #{pattern.size}"
+      end
+    end
+
+    def illuminate_column(col, pattern)
+      case pattern.size
+      when 8 then
+        @communicator.write([col_of_8_pattern(col), pattern])
+      when 16 then
+        @communicator.write([col_of_16_pattern(col), pattern[0..7], pattern[8..15]])
+      else
+        raise ArgumentError, "Incorrect length of pattern sent to MonomeSerial::Monome#illumninate_col. Expected 8 or 16, got #{pattern.size}"
+      end
+    end
+
+    def illuminate_all
+      @communicator.write([all_pattern])
+    end
+
+    def extinguish_all
+      @communicator.write([clear_pattern])
+    end
+
+    def illuminate_frame(quadrant, patterns)
+      raise ArgumentError, "Incorrect number of patterns sent to MonomeSerial::Monome#illuminate_frame. Expected 8, got #{patterns.size}" unless patterns.size == 8
+      reversed_patterns = patterns.map{|pat| pat.reverse}
+      @communicator.write([frame_pattern(quadrant), *reversed_patterns])
+    end
+
+    def brightness=(intensity)
+      @communicator.write([brightness_pattern(intensity)])
+    end
+
+    def read
+      @communicator.read
+    end
+
+    def is_real?
+      @communicator && @communicator.class != MonomeSerial::SerialCommunicator::DummyCommunicator
+    end
+  end
+end

data/lib/monome_serial/serial_communicator.rb

@@ -0,0 +1,26 @@
+module MonomeSerial
+  module SerialCommunicator
+    class << self
+      attr_accessor :suppress_warnings
+    end
+
+    def self.get_communicator(tty_path)
+      begin
+        raise IOError  unless File.exists?(tty_path)
+        raise RuntimeError unless (RUBY_VERSION.split('.').join.to_i >= 191) && (Object.const_defined?("RUBY_ENGINE") && Object.const_get("RUBY_ENGINE") == "ruby")
+        require 'monome_serial/serial_communicator/real_communicator'
+        require 'termios'
+        return RealCommunicator.new(tty_path)
+      rescue IOError
+        puts "Supplied path tty IO file isn't valid, loading up DummyCommunicator instead of a real one" unless suppress_warnings
+        return DummyCommunicator.new
+      rescue RuntimeError
+        puts "Incorrect Ruby version (want MRI Ruby 1.9.1 or higher), loading up DummyCommunicator instead of a real one" unless suppress_warnings
+        return DummyCommunicator.new
+      rescue LoadError
+        puts "Could not load the termios extension. Please install it. Loading up DummyCommunicator instead of a real one" unless suppress_warnings
+        return DummyCommunicator.new
+      end
+    end
+  end
+end

data/lib/monome_serial/serial_communicator/binary_patterns/fourtyh.rb

@@ -0,0 +1,54 @@
+module MonomeSerial
+  module SerialCommunicator
+    module BinaryPatterns
+      module Fourtyh
+        #please implement me
+        #http://docs.monome.org/doku.php?id=tech:protocol:40h
+
+        def led_on_pattern
+          raise NotImplementedError, "please implement me"
+        end
+
+        def led_off_pattern
+          raise NotImplementedError, "please implement me"
+        end
+
+        def x_y_coord_pattern(x,y)
+          raise NotImplementedError, "please implement me"
+        end
+
+        def row_of_8_pattern(row)
+          raise NotImplementedError, "please implement me"
+        end
+
+        def row_of_16_pattern(row)
+          raise NotImplementedError, "please implement me"
+        end
+
+        def col_of_8_pattern(col)
+          raise NotImplementedError, "please implement me"
+        end
+
+        def col_of_16_pattern(col)
+          raise NotImplementedError, "please implement me"
+        end
+
+        def clear_pattern
+          raise NotImplementedError, "please implement me"
+        end
+
+        def all_pattern
+          raise NotImplementedError, "please implement me"
+        end
+
+        def frame_pattern(quadrant)
+          raise NotImplementedError, "please implement me"
+        end
+
+        def brightness_pattern(brightness)
+          raise NotImplementedError, "please implement me"
+        end
+      end
+    end
+  end
+end

data/lib/monome_serial/serial_communicator/binary_patterns/series.rb

@@ -0,0 +1,283 @@
+module MonomeSerial
+  module SerialCommunicator
+    module BinaryPatterns
+      module Series
+        #       monmome serial protocol series 256/128/64
+        #       brian crabtree - tehn@monome.org
+        #
+        #       revision: 070903
+        #
+        #
+        #       from device:
+        #
+        #       message id:     (0) keydown
+        #       bytes:          2
+        #       format:         iiii.... xxxxyyyy
+        #                               i (message id) = 0
+        #                               x (x value) = 0-15 (four bits)
+        #                               y (y value) = 0-15 (four bits)
+        #       decode:         id match: byte 0 >> 4 == 0
+        #                               x: byte 1 >> 4
+        #                               y: byte 1 & 0x0f
+        #
+        #
+        #       message id:     (1) keyup
+        #       bytes:          2
+        #       format:         iiii.... xxxxyyyy
+        #                               i (message id) = 1
+        #                               x (x value) = 0-15 (four bits)
+        #                               y (y value) = 0-15 (four bits)
+        #       decode:         id match: byte 0 >> 4 == 1
+        #                               x: byte 1 >> 4
+        #                               y: byte 1 & 0x0f
+        #
+        #
+        #
+        #       to device:
+        #
+        #       message id:     (2) led_on
+        #       bytes:          2
+        #       format:         iiii.... xxxxyyyy
+        #                               i (message id) = 2
+        #                               x (x value) = 0-15 (four bits)
+        #                               y (y value) = 0-15 (four bits)
+        #       encode:         byte 0 = (id) << 4 = 32
+        #                               byte 1 = (x << 4) | y
+        #
+        #
+        #       message id:     (3) led_off
+        #       bytes:          2
+        #       format:         iiii.... xxxxyyyy
+        #                               i (message id) = 3
+        #                               x (x value) = 0-15 (four bits)
+        #                               y (y value) = 0-15 (four bits)
+        #       encode:         byte 0 = (id) << 4 = 48
+        #                               byte 1 = (x << 4) | y
+        #
+        #
+        #       message id:     (4) led_row1
+        #       bytes:          2
+        #       format:         iiiiyyyy aaaaaaaa
+        #                               i (message id) = 4
+        #                               y (row to update) = 0-15 (4 bits)
+        #                               a (row data 0-7) = 0-255 (8 bits)
+        #       encode:         byte 0 = ((id) << 4) | y = 64 + y
+        #                               byte 1 = a
+        #
+        #
+        #       message id:     (5) led_col1
+        #       bytes:          2
+        #       format:         iiiixxxx aaaaaaaa
+        #                               i (message id) = 5
+        #                               x (col to update) = 0-15 (4 bits)
+        #                               a (col data 0-7) = 0-255 (8 bits)
+        #       encode:         byte 0 = ((id) << 4) | x = 80 + x
+        #                               byte 1 = a
+        #
+        #
+        #       message id:     (6) led_row2
+        #       bytes:          3
+        #       format:         iiiiyyyy aaaaaaaa bbbbbbbb
+        #                               i (message id) = 6
+        #                               y (row to update) = 0-15 (4 bits)
+        #                               a (row data 0-7) = 0-255 (8 bits)
+        #                               b (row data 8-15) = 0-255 (8 bits)
+        #       encode:         byte 0 = ((id) << 4) | y = 96 + y
+        #                               byte 1 = a
+        #                               byte 2 = b
+        #
+        #
+        #       message id:     (7) led_col2
+        #       bytes:          3
+        #       format:         iiiixxxx aaaaaaaa bbbbbbbb
+        #                               i (message id) = 7
+        #                               x (col to update) = 0-15 (4 bits)
+        #                               a (col data 0-7) = 0-255 (8 bits)
+        #                               b (col data 8-15) = 0-255 (8 bits)
+        #       encode:         byte 0 = ((id) << 4) | x = 112 + x
+        #                               byte 1 = a
+        #                               byte 2 = b
+        #
+        #
+        #       message id:     (8) led_frame
+        #       bytes:          9
+        #       format:         iiii..qq aaaaaaaa bbbbbbbb cccccccc dddddddd eeeeeeee ffffffff gggggggg hhhhhhhh
+        #                               i (message id) = 8
+        #                               q (quadrant) = 0-3 (2 bits)
+        #                               a-h (row data 0-7, per row) = 0-255 (8 bits)
+        #       encode:         byte 0 = ((id) << 4) | q = 128 + q
+        #                               byte 1,2,3,4,5,6,7,8 = a,b,c,d,e,f,g,h
+        #       note:           quadrants are from top left to bottom right, as shown:
+        #                               0 1
+        #                               2 3
+        #
+        #       message id:     (9) clear
+        #       bytes:          1
+        #       format:         iiii---c
+        #                               i (message id) = 9
+        #                               c (clear state) = 0-1 (1 bit)
+        #       encode:         byte 0 = ((id) << 4) | c = 144 + c
+        #       note:           clear state of 0 turns off all leds.
+        #                               clear state of 1 turns on all leds.
+        #
+        #
+        #       message id:     (10) intensity
+        #       bytes:          1
+        #       format:         iiiibbbb
+        #                               i (message id) = 10
+        #                               b (brightness) = 0-15 (4 bits)
+        #       encode:         byte 0 = ((id) << 4) | b = 160 + b
+        #
+        #
+        #       message id:     (11) mode
+        #       bytes:          1
+        #       format:         iiii..mm
+        #                               i (message id) = 11
+        #                               m (mode) = 0-3 (2 bits)
+        #       encode:         byte 0 = ((id) << 4) | m = 176 + m
+        #       note:           mode = 0 : normal
+        #                               mode = 1 : test (all leds on)
+        #                               mode = 2 : shutdown (all leds off)
+        #
+        #
+        #
+        #
+        #
+        #       auxiliary ports
+        #
+        #       to device:
+        #
+        #       message id:     (12) activate port
+        #       bytes:          1
+        #       format:         iiiiaaaa
+        #                               i (message id) = 12
+        #                               a (which port) = 0-15 (four bits)
+        #       encode:         byte 0 = (id) << 4 = 192 + a
+        #
+        #
+        #       message id:     (13) deactivate port
+        #       bytes:          1
+        #       format:         iiiiaaaa
+        #                               i (message id) = 13
+        #                               a (which port) = 0-15 (four bits)
+        #       encode:         byte 0 = (id) << 4 = 208 + a
+        #
+        #
+        #       from device:
+        #
+        #       message id:     (14) auxiliary input
+        #       bytes:          2
+        #       format:         iiiiaaaa dddddddd
+        #                               i (message id) = 14
+        #                               a (port number) = 0-15 (four bits)
+        #                               d (data) = 0-255 (eight bits)
+        #       decode:         id match: byte 0 >> 4 == 1
+        #                               a: byte 0 & 0x0f
+        #                               d: byte 1
+        INT_TO_BIN_STRING = {
+          0  => "0000",
+          1  => "0001",
+          2  => "0010",
+          3  => "0011",
+          4  => "0100",
+          5  => "0101",
+          6  => "0110",
+          7  => "0111",
+          8  => "1000",
+          9  => "1001",
+          10 => "1010",
+          11 => "1011",
+          12 => "1100",
+          13 => "1101",
+          14 => "1110",
+          15 => "1111"
+        }
+
+        X_Y_COORD_PATTERNS = (0..15).inject({}) do |hash, x|
+          (0..15).each {|y| hash[[x,y]] = INT_TO_BIN_STRING[x] + INT_TO_BIN_STRING[y]}
+          hash
+        end
+
+        EIGHT_LIGHT_ROW_PATTTERNS = (0..15).inject({}) do |hash, row|
+          hash[row] = "0100" + INT_TO_BIN_STRING[row]
+          hash
+        end
+
+        SIXTEEN_LIGHT_ROW_PATTERNS = (0..15).inject({}) do |hash, row|
+          hash[row] = "0110" + INT_TO_BIN_STRING[row]
+          hash
+        end
+
+
+        EIGHT_LIGHT_COL_PATTERNS = (0..15).inject({}) do |hash, row|
+          hash[row] = "0101" + INT_TO_BIN_STRING[row]
+          hash
+        end
+
+        SIXTEEN_LIGHT_COL_PATTERNS = (0..15).inject({}) do |hash, row|
+          hash[row] = "0111" + INT_TO_BIN_STRING[row]
+          hash
+        end
+
+        def led_on_pattern
+          "00100000"
+        end
+
+        def led_off_pattern
+          "00110000"
+        end
+
+        def x_y_coord_pattern(x, y)
+          X_Y_COORD_PATTERNS[[x,y]]
+        end
+
+        def row_of_8_pattern(row)
+          EIGHT_LIGHT_ROW_PATTTERNS[row]
+        end
+
+        def col_of_8_pattern(col)
+          EIGHT_LIGHT_COL_PATTERNS[col]
+        end
+
+        def row_of_16_pattern(row)
+          SIXTEEN_LIGHT_ROW_PATTERNS[row]
+        end
+
+        def col_of_16_pattern(col)
+          SIXTEEN_LIGHT_COL_PATTERNS[col]
+        end
+
+        def clear_pattern
+          "10010000"
+        end
+
+        def all_pattern
+          "10010001"
+        end
+
+        def frame_pattern(quadrant)
+          unless quadrant >= 1 && quadrant <= 4 then
+            raise ArgumentError,
+            "Expecting quadrant to be between 1 and 4 inclusively, got #{quadrant}"
+          end
+
+          quadrant_pattern = case quadrant
+                             when 1 then "00"
+                             when 2 then "01"
+                             when 3 then "10"
+                             when 4 then "11"
+                             end
+          "100000" + quadrant_pattern
+        end
+
+
+        def brightness_pattern(brightness)
+          raise ArgumentError, "Expecting a brightness between 0 and 15 inclusively, got #{brightness}" unless brightness >= 0 && brightness <= 15
+
+          "1010" + INT_TO_BIN_STRING[brightness]
+        end
+
+      end
+    end
+  end
+end