rustle 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a832c77bff50413388dc4b5e7930c623a8807c5e
+  data.tar.gz: 4565b1dfd7ed5ddae95fe044b3419a3dfa850224
+SHA512:
+  metadata.gz: ab2b36845325b8f6ad07c9c78ffbb83c6372b7c167c213d1444ffb1f3c9c18c7ba0fb42f5726c023a04cc2384b450ccf5596129764d41741a0d402bcf56a4774
+  data.tar.gz: 5eeea99ff6e98b0e7d310aa55f5a0b603a5feffa132dc915d6e2d2870c820dd8cc4a010aea53cdfd53a64d1e3dae4cb6f37106573e98d91cf0900a7c8b92bf32

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+dsl_example.rb

data/.rspec

@@ -0,0 +1,2 @@
+--format doc
+--color

data/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Rustle Changelog
+
+## 0.1.1
+
+#### New
+
+* Strip now relies on a new class, Frame, to handle its state changes. With this system in place, serialization of strip state is much more efficient, and thus, timing is more precise, and much higher framerates are achievable. Strip objects now also maintain a queue of their future frames, and expose methods which allow frames to be advanced through.
+* Code is now documented.
+
+#### Fixed
+
+* An oversight where the Strip class tried to call `#off` on itself, which raised a NilClass exception.
+
+#### Deprecated
+
+* `Color#brighten` and `Color#darken` have both been removed due to their apparent uselessness. They may be restored in future versions should a use for them be found.
+

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rustle.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Andrew Hamon and Steven Petryk
+
+MIT License
+
+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/README.md

@@ -0,0 +1,64 @@
+![Rustle](rustle_logo.png "Rustle Logo")
+
+Rustle is a gem that aims to allow you to control an addressable RGB LED strip in Ruby (using an Arduino as a middleman). Run it on your computer, a Raspberry Pi, or whatever you want! All you need is a strip, an Arduino, and a serial connection.
+
+## Installation
+
+It's pretty easy.
+
+    $ gem install rustle
+
+## Getting Started
+
+### 1. Set up your Arduino
+
+Upload the [basic.ino](sketches/basic.ino) sketch to your Arduino. Make sure that you take a look at the file first and modify it to suit your physical setup.
+
+**Gotcha**: the Arduino resets itself upon any serial communication. We are currently considering switching to the [firmata protocol](http://firmata.org/wiki/Main_Page) in order to work around this problem. For now, you will need to **place a 10μF capacitor between the `RESET` and `GND` pins on your Arduino after uploading the sketch** if you want to use Rustle from a static Ruby script.
+
+The sketch itself is still being worked on. Our goal, in the future, is to simply allow you to call `rustle arduino:prepare` to automatically generate and upload the sketch (with the number of LEDs, frames per second, etc) to the Arduino using [Ino](http://inotool.org/).
+
+### 2. Connect to the Arduino
+
+The majority of Rustle's actions are performed by calling methods on a receiver's LED strip. First, connect to your receiver:
+
+```ruby
+arduino = Rustle::Receiver.new do
+  # replace this path with the one specified by the Arduino IDE 
+  port_file "/dev/[PORTFILE]"
+
+  # replace this with the number of LEDs connected to your receiver
+  num_leds 30
+end
+```
+
+### 3. Throw a party
+
+That's it! You can now control your LED strip with Ruby. Try out some of the following (this might be easier in a Ruby console):
+
+```ruby
+# Adding on to the code from earlier...
+strip = arduino.strip
+
+# Make the strip red
+strip.to Color.hex('f00')
+
+# Make a fancy-schmancy wipe transition to white
+strip.transition :wipe_to, 2000, color: white
+```
+
+Want to make a custom transition? It's easy! See the [Transition class](lib/rustle/transition.rb) for a quick guide. If you want to make it a part of Rustle, throw it into the [lib/transitions](lib/transitions) folder, and submit a pull request.
+
+## Documentation
+
+    $ yard
+
+Alternatively, view it on [RubyDoc.info](http://rubydoc.info/github/stevenpetryk/rustle).
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/rustle/color.rb

@@ -0,0 +1,230 @@
+module Rustle
+  class Color
+    # @return [Fixnum] the red value of the color
+    attr_reader :r
+
+    # @return [Fixnum] the green value of the color
+    attr_reader :g
+
+    # @return [Fixnum] the blue value of the color
+    attr_reader :b
+
+    # The Regex which verifies that a valid hex color code is supplied. It
+    # merely checks that a string is 6 characters long and consists of 
+    # hexadecimal characters.
+    VALID_HEX_COLOR = /^[0-9a-f]{6}$/i
+    
+    # Creates a new Color object given RGB values in the range +0..255+. Other
+    # values are accepted, but they will be coerced into this range (this is
+    # preferable to throwing exceptions, because there's a slim chance that an
+    # internal method will have some rounding errors).
+    #
+    # @param [Fixnum] r the red value
+    # @param [Fixnum] g the green value
+    # @param [Fixnum] b the blue value
+    # 
+    # @return [Color] a new Color object with the given RGB values.
+    def initialize(r, g, b)
+      @r = normalize_rgb_param(r)
+      @g = normalize_rgb_param(g)
+      @b = normalize_rgb_param(b)
+    end
+
+    # Creates a new Color object given RGB values. Equivalent to {#initialize}.
+    def self.rgb(r, g, b)
+      self.new(r, g, b)
+    end
+
+    # @return [Array<Fixnum>] the Color's RGB values as an array with the 
+    #   format +[r, g, b]+
+    def to_a
+      [@r, @g, @b].map(&:floor)
+    end
+
+    # Serializes a color into a string of +chars+.
+    # Note that each color is coerced into the range +0..254+, since our 
+    # end-of-frame code is 255.
+    #
+    # @return [String] a string representation of the color.
+    def serialize
+      to_a.map { |c| self.class.fit_within_range(c, 0, 254).chr }.join
+    end
+
+    # Checks if a color is equal to another color.
+    #
+    # @param [Color] other the other Color object
+    #
+    # @example
+    #   red_rgb = Rustle::Color.rgb(255, 0, 0)
+    #   red_hex = Rustle::Color.hex('f00')
+    #   blue = Rustle::Color.rgb(0, 0, 255)
+    # 
+    #   red_rgb.eql? red_hex # => true
+    #   red_rgb.eql? blue    # => false
+    #
+    # @return [Boolean] true if the colors are equal, false if they are not.
+    def eql?(other)
+      [:r, :g, :b].all? { |c| self.send(c) == other.send(c) }
+    end
+
+    # Creates a new color object given a hexadecimal value.
+    # 
+    # @param [String] hex_value the hexadecimal representation of a color
+    #
+    # @return [Color] a new Color object based on the given hexadecimal value.
+    #
+    # @example
+    #   # Valid
+    #   Color.hex('#faa')
+    #   Color.hex('fa03f2')
+    #   Color.hex('#fa03f2')
+    # 
+    #   # Invalid (will raise)
+    #   Color.hex('fzx') 
+    #   Color.hex('af3d')
+    def self.hex(hex_value)
+      # Remove leading hash
+      hex_value = hex_value[1..-1] if hex_value[0] == '#'
+
+      # Convert f00 to ff0000
+      if hex_value.length == 3
+        hex_value = hex_value.split("").map { |s| s+s }.join
+      end
+
+      # Validate the format
+      raise InvalidHexColorCode unless hex_value =~ VALID_HEX_COLOR
+
+      self.new *( hex_value.scan(/.{2}/).map(&:hex) )
+    end
+
+    # Creates a new Color object given HSB color values.
+    #
+    # @param [Fixnum] hue the color's hue (between 0 and 360)
+    # @param [Float] sat the color's saturation (between 0 and 1)
+    # @param [Float] bri the color's brightness (between 0 and 1)
+    #
+    # @return [Color] a new color object based on the given HSB values.
+    def self.hsb(hue, sat, bri)
+      hue = fit_within_range(hue, 0, 360)
+      sat = fit_within_range(sat, 0, 1)
+      bri = fit_within_range(bri, 0, 1)
+
+      if sat == 0
+        r = g = b = bri
+      else
+        hh = hue % 360 
+        hh /= 60.0
+        i = hh.to_i
+        f = hh - i
+
+        p = bri * (1 - sat)
+        q = bri * (1 - sat * f)
+        t = bri * (1 - sat * (1 - f))
+
+        case i
+        when 0
+          r = bri
+          g = t
+          b = p
+        when 1
+          r = q
+          g = bri
+          b = p
+        when 2
+          r = p
+          g = bri
+          b = t
+        when 3
+          r = p
+          g = q
+          b = bri
+        when 4
+          r = t
+          g = p
+          b = bri
+        else
+          r = bri
+          g = p
+          b = q
+        end
+      end
+
+      self.new *( [r, g, b].map { |c| (c * 255 + 0.5) } )
+    end
+
+    # Converts the Color object to an array of HSB values in the format 
+    # [hue, saturation, brightness].
+    #
+    # @return [Array<Fixnum>] the color as an HSB array
+    def to_hsb
+      r = @r / 255.0
+      g = @g / 255.0
+      b = @b / 255.0
+      max = [r, g, b].max
+      min = [r, g, b].min
+      delta = max - min
+      hue = 0.0
+      brightness = max
+      saturation = max == 0 ? 0 : (max - min) / max
+
+      if delta != 0
+        if r == max
+          hue = (g - b) / delta
+        else
+          if g == max
+            hue = 2 + (b - r) / delta
+          else
+            hue = 4 + (r - g) / delta
+          end
+        end
+
+        hue *= 60
+        hue += 360 if hue < 0
+      end
+      [hue, saturation, brightness]
+    end
+
+    # Creates an intermediate between the current Color object and another
+    # Color object. It does so by simple linear RGB transitioning, which seems
+    # to work just fine when working with RGB LED strips (even though, in most)
+    # cases, HSB transitioning would be better, it is not worth the extra
+    # processing time).
+    # 
+    # @param [Color] other the other Color object
+    # @param [Float] amount the degree to which the color should be transitioned
+    #   +(0..1)+.
+    #
+    # @return [Color] the new, partially transitioned Color object
+    #
+    # @example
+    #   red = Color.new(255, 0, 0)
+    #   blue = Color.new(0, 0, 255)
+    #
+    #   red.transition_to(blue, 0.5) # => <Color r=127, g=0, b=127>
+    def transition_to(other, amount)
+      old_col = self.to_a
+      new_col = other.to_a
+
+      diff = old_col.each_with_index.map { |v, i| (new_col[i] - v) * amount }
+
+      self.class.rgb *old_col.each_with_index.map { |v, i| v + diff[i] }
+    end
+
+    private
+
+      # Forces `val` into the range 0..255
+      def normalize_rgb_param(value)
+        self.class.fit_within_range(value, 0, 255)
+      end
+
+      # Coerces `value` into the range given
+      def self.fit_within_range(value, min_allowed, max_allowed)
+        if (value <= max_allowed) && (value >= min_allowed)
+          value 
+        else
+          value > max_allowed ? max_allowed : min_allowed
+        end
+      end
+
+  end
+end

data/lib/rustle/exceptions.rb

@@ -0,0 +1,10 @@
+module Rustle
+  # A general Rustle exception
+  class Error < StandardError; end
+
+  # Raised when user fails to provide a port_file
+  class PortFileNotSpecified < Error; end
+
+  # Raised when a user provides an invalid hexadecimal color
+  class InvalidHexColorCode < Error; end
+end

data/lib/rustle/frame.rb

@@ -0,0 +1,42 @@
+module Rustle
+  # = Frames
+  #
+  # All strip changes are sent by serializing frames and sending them to the 
+  # receiver. Serialization of a frame is done by serializing all {Color} 
+  # objects in the +leds+ array (see {Color#serialize}), and then appending the 
+  # +char+ 255 to the end. Serialized frames are, thus, strings of +chars+, 
+  # where each +char+ is a single RGB color channel.
+  #
+  # It is worth noting that, since 255 is our end-of-frame code, all color data
+  # sent as an integer in the range +0..254+. It is safe to assume that an
+  # approximate 1/255th drop in brightness is not noticeable. There is, however,
+  # the option of modifying the sketch to multiply each RGB channel by
+  # 1.004 and +floor+ing the value.
+  #
+  # Coercion of RGB values into the range +0..254+ is handled in 
+  # {Color#serialize}.
+  class Frame
+    # LEDs in a frame are represented as an array of {Color} objects. Each Color
+    # object corresponds to a given LED. The idea is that any physical LED 
+    # matches its corresponding Color object.
+    #
+    # @return [Array<Color>] an array of {Color} objects (LEDs).
+    attr_reader :leds
+
+    # Initializes a new frame.
+    #
+    # @param [Array] leds n array of {Color} objects, whose length is the same
+    #   as the number of LEDs connected to the strip.
+    def initialize(leds)
+      @leds = leds
+    end
+
+    # Serializes all LED {Color} objects (see {Color#serialize}) and appends
+    # the end-of-frame code (+255.chr+)
+    # 
+    # @return [String] the serialized frame, represented as a string of +chars+.
+    def serialize
+      @leds.map(&:serialize).join + 255.chr
+    end
+  end
+end

data/lib/rustle/receiver.rb

@@ -0,0 +1,73 @@
+require 'serialport'
+
+module Rustle
+  # = Receivers
+  # 
+  # Your receiver is, effectively, your Arduino. The receiver class's purpose is
+  # to manage the serial communication between Ruby and your Arduino, and to
+  # ensure that changes made to a Strip object are reflected immediately on the
+  # actual LED strip. This class, however, is *not* responsible for actual 
+  # serialization; the Frame and Color classes serialize themselves.
+  #
+  # The Receiver class is initialized using a block.
+  #
+  #   bedroom_arduino = Rustle::Receiver.new do
+  #     port_file "/dev/[PORT_FILE]"
+  #     num_leds 30
+  #   end
+  #
+  # Your port file can be found using the Arduino IDE.
+  class Receiver
+    # When your receiver is instantiated, a {Strip} object is automatically
+    # created alongside it.
+    # @return [Strip] the strip associated with the Receiver
+    attr_reader :strip
+
+    # Initializes a new receiver.
+    #
+    # @example
+    #   kitchen_arduino = Rustle::Receiver.new do
+    #     port_file "/dev/tty.usbmodem411" # replace this
+    #     num_leds 60
+    #   end
+    #
+    # @yieldparam [String] port_file the location of serial port file. It can be
+    #   found in the Arduino IDE (or via Ino).
+    # @yieldparam [Fixnum] baud (optional) the serial baud rate (make sure it matches the one in
+    #   your sketch)
+    # @yieldparam [Fixnum] num_leds (optional) the total number of LEDs connected to your 
+    #   receiver. Note that this attribute only affects how the {Strip} object
+    #   is instantiated; the number of LEDs is not actually stored in the
+    #   Receiver object.
+    def initialize(&block)
+      # Default value
+      @baud = 921_600
+
+      instance_eval &block
+
+      init_serialport
+    end
+
+    # Serializes +frame+ and sends it off to the the serial port. +push_frame+
+    # is used internally, so its direct use is discouraged, but it would work
+    # in theory.
+    # @param [Frame] frame a frame object
+    def push_frame(frame)
+      @port.write frame.serialize
+    end
+
+    private
+
+      # instance_eval-specific methods for our DSL
+      def port_file(file); @port_file = file; end
+      def baud(int);       @baud = int;       end
+      def num_leds(count)
+        @strip = Strip.new(self, count)
+      end
+
+      # Instantiates a new serial port
+      def init_serialport
+        @port = SerialPort.new @port_file, @baud, 8, 1, SerialPort::NONE
+      end
+  end
+end

data/lib/rustle/strip.rb

@@ -0,0 +1,95 @@
+require 'active_support/inflector'
+
+module Rustle
+  # = Strips
+  # 
+  # The Strip class' purpose is to respond to requests to change the color of
+  # the physical strip, and send changes to the {Receiver} when appropriate.
+  # All Strip objects also have a buffer, which is simply an array of {Frame} 
+  # objects. Calling any method which advances to the next frame causes the 
+  # Strip to request the Receiver class to push an update over the serial port.
+  # 
+  # New strips cannot be instantiated outside of the {Receiver} class.
+  # See {Receiver#initialize} for details on how Strips are instantiated.
+  class Strip
+    # @return [Receiver] the receiver associated with the strip
+    attr_reader :receiver
+
+    # @return [Fixnum] the number of LEDs connected to the strip
+    attr_reader :num_leds
+
+    # Initializes a new strip given a {Receiver} object and the number of LEDs
+    # attached to the strip.
+    #
+    # @param [Receiver] receiver
+    # @param [Fixnum] num_leds the number of LEDs connected to the strip.
+    def initialize(receiver, num_leds = 32)
+      @receiver = receiver
+      @num_leds = num_leds
+      @queue = []
+    end
+
+    # @return [Frame] the next frame in the buffer. If the buffer only has one
+    #   frame, it returns the current frame.
+    def next_frame
+      @queue[1] || current_frame
+    end
+
+    # Advances the strip to the next frame.
+    def next_frame!
+      @receiver.push_frame(next_frame)
+      @queue.shift if @queue.length > 1
+    end
+
+    # @return [Frame] the current frame being displayed by the strip.
+    def current_frame
+      @queue.first
+    end
+
+    # Queues an array of frames for transitions. Note: this does *not* 
+    # cause any physical changes; it merely prepares a list thereof.
+    # 
+    # @param [Array<Frame>] frames an array of frames to load into the queue.
+    def queue_frames(frames)
+      @queue += frames
+    end
+
+    # Turns off all LEDs on the strip
+    def off!
+      @queue << Frame.new([Color.new(0,0,0)] * @num_leds)
+      next_frame!
+    end
+
+    # Changes all LEDs to a particular color
+    #
+    # @param [Color] color 
+    def to(color)
+      @queue << Frame.new([color] * @num_leds)
+      next_frame!
+    end
+
+    # Instantiates and executes a {Transition} subclass. 
+    #
+    # @example
+    #   strip = # [initialized strip...]
+    #   
+    #   # Transition the strip to red in 2 seconds using the wipe-to transition
+    #   strip.transition :wipe_to, 2000, color: Rustle::Color.new(255, 0, 0)
+    #  
+    # @param [Symbol] klass a symbol representing the name of the class (e.g.
+    #   for {WipeToTransition}, the corresponding symbol would be +:wipe_to+).
+    # @param [Fixnum] duration the duration of the transition in milliseconds
+    # @param [Hash] opts a hash containing transition-specific options
+    #
+    # @return [Transition] an instance of a Transition subclass
+    def transition(klass, duration, opts = {})
+      # Default to white
+      opts[:color] ||= Color.rgb(255, 255, 255)
+
+      # :fade_to => FadeToTransition
+      klass = "#{klass.to_s.camelize}Transition".constantize
+      
+      klass.new(self, duration, opts).frames
+    end
+  end
+end

data/lib/rustle/transition.rb

@@ -0,0 +1,86 @@
+module Rustle
+  # = Transitions
+  # 
+  # Transitions are created by subclassing this class. See {FadeToTransition}
+  # for the most basic example.
+  #
+  # == Creating a Transition
+  # You'll need to create a subclass of {Transition} and require it in your 
+  # project.
+  #
+  # === Override the subclass's {#setup} and {#animate} methods.
+  # Use +setup+ to create any instance variables you may need to calculate
+  # before the transitio renders. The +opts+ passed in when calling 
+  # {Strip#transition} are preserved and sent to this method.
+  #
+  # {#animate} is called once-per-LED-per-frame, and expects you to return a 
+  # {Color object}.
+  class Transition
+    attr_reader :frames, :duration
+
+    def initialize(strip, duration, opts = {})
+      @strip = strip
+      @duration = duration
+      @total_frames = (duration.to_f / (1000/Rustle::FRAME_RATE.to_f)).ceil
+      @frame_duration = 1.0/Rustle::FRAME_RATE
+
+      self.setup(opts)
+
+      render
+    end
+
+    # Gets called before the transition begins. Override it to set up any
+    # instance variables you need in the {#animate} method.
+    #
+    # @param [Hash] opts the options hash that is passed in when calling 
+    #   {Strip#serialize}
+    #
+    # Within this method, you also have the following available:
+    # * +@total_frames+: the total number of frames in the animation
+    # * +@duration+: the duration of the animation in milliseconds
+    # * +@frame_duration+: the duration of an individual frame (generally only
+    #   used internally)
+    def setup(opts); end
+
+    # Gets called once-per-LED-per-frame. Override it, and do your calculations
+    # therein. You will have access to any instance variables you declare in
+    # {#setup}.
+    #
+    # @param [Fixnum] led_index the index of the current LED, starting at 0.
+    # @param [Color] starting_color the color that the current LED was 
+    #   displaying before the transition began
+    # @param [Fixnum] frame_num the current frame number in the transition
+    #
+    # @return [Color] a color object corresponding to what the new LED color
+    #   should be.
+    #
+    # Within this method, you also have the following available:
+    # * +@total_frames+: the total number of frames in the animation
+    # * +@duration+: the duration of the animation in milliseconds
+    # * +@frame_duration+: the duration of an individual frame (generally only
+    #   used internally)
+    def animate(led_index, starting_color, frame_num); end
+
+    private
+
+      def render
+        starting_frame = @strip.current_frame
+
+        @frames = Array.new(@total_frames) do |frame_num|
+          Frame.new(
+            Array.new(@strip.num_leds) do |led_index|
+              # Gets called once per LED per frame
+              animate(led_index, starting_frame.leds[led_index], frame_num)
+            end
+          )
+        end
+
+        @strip.queue_frames @frames
+
+        @total_frames.times do
+          @strip.next_frame!
+          sleep @frame_duration
+        end
+      end
+  end
+end

data/lib/rustle/transitions/fade_to_transition.rb

@@ -0,0 +1,14 @@
+class FadeToTransition < Rustle::Transition
+  def name
+    :fade_to
+  end
+
+  def setup(opts)
+    @new_color = opts[:color]
+  end
+
+  # Return a color object
+  def animate(led_index, start_color, frame_num)
+    start_color.transition_to @new_color, (frame_num.to_f+1) / @total_frames.to_f
+  end
+end

data/lib/rustle/transitions/wipe_to_transition.rb

@@ -0,0 +1,20 @@
+class WipeToTransition < Rustle::Transition
+  def name
+    :wipe_to
+  end
+
+  def setup(opts)
+    @adj_factor = @total_frames.to_f/@strip.num_leds.to_f
+    @new_color = opts[:color]
+  end
+
+  def animate(led_index, start_color, frame_num)
+    amount = 1.0 / 
+             (@total_frames-(led_index)*@adj_factor) *
+             ((frame_num+1) - (led_index)*@adj_factor)
+
+    amount = [amount, 0.0].max
+
+    start_color.transition_to @new_color, amount
+  end
+end

data/lib/rustle/version.rb

@@ -0,0 +1,3 @@
+module Rustle
+  VERSION = "0.1.1"
+end

data/lib/rustle.rb

@@ -0,0 +1,14 @@
+require "rustle/version"
+
+require "rustle/receiver"
+require "rustle/strip"
+require "rustle/color"
+require "rustle/frame"
+require "rustle/transition"
+require "rustle/transitions/wipe_to_transition"
+require "rustle/transitions/fade_to_transition"
+require "rustle/exceptions"
+
+module Rustle
+  FRAME_RATE = 60
+end

data/rustle.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rustle/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rustle"
+  spec.version       = Rustle::VERSION
+  spec.authors       = ["Andrew Hamon", "Steven Petryk"]
+  spec.email         = ["and.ham95@gmail.com", "petryk.steven@gmail.com"]
+  spec.description   = %q{Rustle is a gem that allows you to control an individually-addressable RGB LED strip via Ruby (with an Arduino acting as a middleman for PWM controls).}
+  spec.summary       = %q{Control an individually-addressable RGB LED strip in Ruby.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib", "lib/transitions"]
+
+  spec.add_runtime_dependency 'active_support', '~> 3.0', '>= 3.0.0'
+  spec.add_runtime_dependency 'serialport', '~> 1.3', '>= 1.3.0'
+
+  spec.add_development_dependency 'bundler', "~> 1.3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency 'rspec', '~> 2.14', '>= 2.14.1'
+end

data/sketches/basic.ino

@@ -0,0 +1,82 @@
+/**
+ * A basic, one-way Rustle template sketch.
+ *
+ * LICENSE: This source file is subject to the MIT License, which is available
+ * through the World Wide Web at http://opensource.org/licenses/MIT, and is also
+ * included as a part of this repository.
+ *
+ * @author     Andrew Hamon <and.ham95@gmail.com>
+ * @author     Steven Petryk <petryk.steven@gmail.com>
+ * @copyright  2014 Andrew Hamon
+ * @license    MIT License
+ */
+
+#include <Adafruit_NeoPixel.h>
+
+/*
+ * Ensure that these directives match your physical setup.
+ *
+ * Note: The baud rate may need to be decreased depending on your setup. The Uno
+ * seems to handle 921,600 just fine, and it's what Rustle defaults to.
+ */
+#define STRIP_LENGTH 30
+#define STRIP_PIN 6
+#define BAUD 921600
+
+// Initialize LED strip
+Adafruit_NeoPixel myStrip = Adafruit_NeoPixel(STRIP_LENGTH, STRIP_PIN,
+  NEO_GRB + NEO_KHZ800);
+
+// Current LED index within a frame
+byte led_index;
+
+// Each LED is an RGB array. `k` is just a counter (0,1,2  == R,G,B).
+byte current_led[3];
+byte k;
+
+void setup() {
+  // Ensure this matches the baud in your receiver initialization.
+  Serial.begin(BAUD);
+
+  // Initialize counters
+  led_index = 0;
+  k = 0;
+
+  // Here we go
+  myStrip.begin();
+  myStrip.show();
+}
+
+void serialEvent() {
+  while(Serial.available()) {
+    byte x = Serial.read();
+
+    // 255 is the end-of-frame code, so we can assume that all other values
+    // are actual RGB values.
+    if (x == 255) {
+      myStrip.show();
+
+      k = led_index = 0;
+    }
+
+    else if (x < 255) {
+      // Data is sent [r,g,b,r,g,b,...] so we must accumulate an entire RGB
+      // triplet before writing to the LED strip.
+      current_led[k] = x;
+      k++;
+
+      // If we've accumulated a triplet...
+      if(k > 2) {
+        // ... we send the pixel.
+        myStrip.setPixelColor(led_index, 
+          current_led[0], current_led[1], current_led[2]);
+
+        k = 0;
+        led_index++;
+      }
+    }
+  }
+}
+
+// Empty loop because sketch is entirely serial event driven
+void loop() {};

data/spec/color_spec.rb

@@ -0,0 +1,156 @@
+require 'spec_helper'
+
+describe Rustle::Color do
+
+  let(:color) { Rustle::Color.rgb(128,128,128) }
+
+  context "when initialized" do
+    let(:color_with_invalid_params) { Rustle::Color.new(-100,1000,0) }
+
+    it "corrects negative rgb values to zero" do
+      (color_with_invalid_params.r).should eq(0)
+    end
+
+    it "corrects very large rgb values to 255" do
+      (color_with_invalid_params.g).should eq(255)
+    end
+
+    it "makes no changes to rgb values between 0 and 255" do
+      color1 = Rustle::Color.new(0,0,0)
+      (color1.r).should eq(0)
+      (color1.g).should eq(0)
+      (color1.b).should eq(0)
+
+      color2 = Rustle::Color.new(255,255,255)
+      (color2.r).should eq(255)
+      (color2.g).should eq(255)
+      (color2.b).should eq(255)
+    end
+  end
+
+  describe "#to_a" do
+    it "returns an array" do
+      (color.to_a).should be_a(Array)
+    end
+
+    it "the array has the correct [r,g,b] values" do
+      (color.to_a).should eq([128,128,128])
+    end
+
+    it "rounds decimal values down to the nearest whole number" do
+      fractional_rgbs = Rustle::Color.rgb(0.5,10.7,99.9)
+      (fractional_rgbs.to_a).should eq([0, 10, 99])
+    end
+  end
+
+  describe "#to_s" do
+    it "returns a string with information about the color" do
+      (color.to_s).should eq("rgb(128, 128, 128)")
+    end
+
+    it "pads strings so that even small rgb values align properly" do
+      other_color = Rustle::Color.rgb(0,1,2)
+      (other_color.to_s).should eq("rgb(  0,   1,   2)")
+    end
+  end
+
+  describe "#eql?" do
+    let(:colorA) { Rustle::Color.rgb(128,128,128) }
+    let(:another_colorA) { Rustle::Color.rgb(128,128,128) }
+    let(:colorB) { Rustle::Color.rgb(0, 0, 0) }
+
+    it "returns true if the reciever and parameter objects hold equivalent rgb values" do
+      (colorA.eql?(another_colorA)).should be_true
+    end
+
+    it "returns false if the reciever and parameter objects differ in rgb values" do
+      (colorA.eql?(colorB)).should be_false
+    end
+  end
+
+  describe "Rustle::Color.hex factory method" do
+    let(:badass_rgb) { Rustle::Color.rgb(186, 218, 85) }
+
+    context "understands hex color codes WITHOUT a leading hash" do
+      let (:badass) { Rustle::Color.hex "BADA55" }
+
+      it "creates a color object" do
+        (badass).should be_a(Rustle::Color)
+      end
+
+      it "has the proper rgb values" do
+        (badass).should eql(badass_rgb)
+      end
+    end
+
+    context "understands hex color codes WITH a leading hash" do
+      let(:badass) { Rustle::Color.hex "#BADA55" }
+
+      it "creates a color object" do
+        (badass).should be_a(Rustle::Color)
+      end
+
+      it "has the right rgb values" do
+        (badass).should eql(badass_rgb)
+      end
+    end
+
+    context "understands hex color codes in three character format" do
+      let(:bad_hex) { Rustle::Color.hex "#BAD" }
+      let(:bad_rgb) { Rustle::Color.rgb 187, 170, 221 }
+
+      it "creates a color object" do
+        (bad_hex).should be_a(Rustle::Color)
+      end
+
+      it "should have the correct rgb values" do
+        (bad_hex).should eql(bad_rgb)
+      end
+    end
+
+    it "is case insensitive" do
+      first_badass = Rustle::Color.hex "#BADa55"
+      second_badass = Rustle::Color.hex "#badA55"
+      (first_badass).should eql(second_badass)
+    end
+
+    it "raises an error when given an invalid color code string" do
+      expect { Rustle::Color.hex "#ABCDEFABCDEF" }.to raise_error(Rustle::InvalidHexColorCode)
+    end
+  end
+
+  describe "Rustle::Color.hsb factory method" do
+    let(:rgb) { Rustle::Color.rgb 187, 170, 221 }
+    let(:hsb) { Rustle::Color.hsb 260, 0.23, 0.866 }
+    # Color: #BBAADD
+    # RGB: (187, 170, 221)
+    # HSV: 260 (260), saturation: 23 (23.0769), value: 87 (86.6667)
+
+    it "produces a color object" do
+      hsb.should be_a(Rustle::Color)
+    end
+
+    it "has the correct rgb properties" do
+      # Use be_within to give some allowance for rounting errors
+      (hsb.r).should be_within(3).of(rgb.r)
+      (hsb.g).should be_within(3).of(rgb.g)
+      (hsb.b).should be_within(3).of(rgb.b)
+    end
+  end
+
+  describe "#to_hsb" do
+    let(:hsb) { Rustle::Color.hsb 180, 0.5, 0.8 }
+
+    it "returns an array of [h,s,v] coordinates" do
+      color.to_hsb.should be_a(Array)
+    end
+
+    it "should have the (approximate) [h,s,v] coordinates" do
+      hsb_arr = hsb.to_hsb
+      hsb_arr[0].should be_within(1).of(180)
+      hsb_arr[1].should be_within(0.1).of(0.5)
+      hsb_arr[2].should be_within(0.1).of(0.8)
+    end
+
+  end
+end

data/spec/receiver_spec.rb

@@ -0,0 +1,5 @@
+require 'spec_helper'
+
+describe Rustle::Receiver do
+  it "does nothing"
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'bundler/setup'
+
+require 'rustle'
+
+RSpec.configure do |config|
+  
+end

metadata

@@ -0,0 +1,163 @@
+--- !ruby/object:Gem::Specification
+name: rustle
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Andrew Hamon
+- Steven Petryk
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-02-17 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: active_support
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: serialport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 1.3.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.14'
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: 2.14.1
+description: Rustle is a gem that allows you to control an individually-addressable
+  RGB LED strip via Ruby (with an Arduino acting as a middleman for PWM controls).
+email:
+- and.ham95@gmail.com
+- petryk.steven@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/rustle.rb
+- lib/rustle/color.rb
+- lib/rustle/exceptions.rb
+- lib/rustle/frame.rb
+- lib/rustle/receiver.rb
+- lib/rustle/strip.rb
+- lib/rustle/transition.rb
+- lib/rustle/transitions/fade_to_transition.rb
+- lib/rustle/transitions/wipe_to_transition.rb
+- lib/rustle/version.rb
+- rustle.gemspec
+- rustle_logo.png
+- sketches/basic.ino
+- spec/color_spec.rb
+- spec/receiver_spec.rb
+- spec/spec_helper.rb
+homepage: ''
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+- lib/transitions
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Control an individually-addressable RGB LED strip in Ruby.
+test_files:
+- spec/color_spec.rb
+- spec/receiver_spec.rb
+- spec/spec_helper.rb
+has_rdoc: