apa102_rbpi 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a5cfb6606ad602a8898f7ec7b89975f748209df1
-  data.tar.gz: 59ed02cca9b2b04f99b127bfef1137cfd5264a3b
+  metadata.gz: 40336d05916f6d9efd8ed00b90b0e0c470bf3f90
+  data.tar.gz: cdc426844412559ffd66de9a3c744105c938a766
 SHA512:
-  metadata.gz: a95f04120c75c6374e8a76c23023ac2e5dee45db4dd1c116cf1450b0fbf8101d5670b01a338e456855e00ea2e75a00378a4c27f113fe7e9de33e897dded0e705
-  data.tar.gz: 1ebe65ebaa9162a1466d8cb6cbd6d4206bc7524f00c52e9fe91aef32c92a1a4e6258a4c8fa115b167e75367dddce548afd629c040a8ee3adf879de696e797f75
+  metadata.gz: a73f59c02624d41198d4cda1b8cb1250bd8659c2a69c2e5a47b3c5d66930892a296f72ffc0c3c38c1fed6c32b6226b3547c09d061b130ff8693c15cbdfbc2a9b
+  data.tar.gz: b9f570c6e1feefa82b0e0eaf2f400016f352fd8a7a244d448c224fa2c0c629c5f6a3a7de685e162090d77496628d6c6503b50381d72eec04fed2bdf8da66e05a

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 1.0.0
+- Add multistrip support
+- Add simulation support
+- Remake base objects, add cleaner configuration
+
 ## 0.2.0
 -Set pi_piper as regular dependency
 -Added some utility functions

data/README.md

@@ -1,8 +1,8 @@
 # Apa102Rbpi
-
 Simple library to drive APA102/Dotstar LEDs using a Raspberry Pi
 
-## Installation
+## Setup
+The Pi can communicate directly with a APA102 LED strip through the [SPI bus](https://www.raspberrypi.org/documentation/hardware/raspberrypi/spi/README.md). Connect the data and clock inputs on the strip to the MOSI and SCLK pins on the Pi board. Be sure to use a 5V power adapter and a logic level shifter for the APA102 inputs as the Pi only outputs 3.3V. After handling the hardware, you're ready to tackle the fun part!
 
 Add this line to your application's Gemfile:
 
@@ -12,33 +12,112 @@ gem 'apa102_rbpi'
 
 And then execute:
 
-    $ bundle
+```
+$ bundle
+```
 
 Or install it yourself as:
 
-    $ gem install apa102_rbpi
+```
+$ gem install apa102_rbpi
+```
 
 ## Usage
+I recommend playing around in the ruby console when getting started.
+
+Note that you must have root permissions to use SPI! Use:
+```
+sudo irb
+```
+or
+```
+sudo bundle exec pretty_lights.rb
+```
 
 Simple blinker:
+
 ```ruby
 require 'apa102_rbpi'
-include Apa102Rbpi
-
-led = Apa102.new(1)
+my_strip = Apa102Rbpi.strip
 loop do
-  led.set_pixel!(0, 0xffffff)
+  my_strip.set_pixel!(0, 0xffffff)
   sleep 1
-  led.set_pixel!(0, 0)
+  my_strip.set_pixel!(0, 0)
   sleep 1
 end
 ```
 
-## Development
+## Configuration
+```ruby
+Apa102Rbpi.configure do |c|
+  c.num_leds = 100
+  c.led_frame_rgb_offsets = {
+    red: 3,
+    blue: 2,
+    green: 1
+  }
+  c.brightness = 31
+  c.spi_hz = 8000000
+  c.simulate = ENV['simulate'] || false
+end
+```
+
+#### num_leds
+Set this to your strip's total leds.
+
+#### led_frame_rgb_offsets
+Some strips are manufactured under different specifications such that the red/green/blue data frames are in different positions. If you try to input a [r,g,b] color into your strip and end up seeing [b,g,r], for example, you should pass in:
+```
+  {red: 3, green: 2, blue: 1}
+```
+
+#### brightness
+Sets the strip's default brightness a range of 0-31
+
+#### spi_hz
+Controls how fast data is sent through the SPI bus. The default should be fine for most.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `bin/console` for an interactive prompt that will allow you to experiment.
+#### simulate
+Set this to `true` if you wish to print your strip to the console rather than to the actual hardware strip. Terminal colors will simulate the strip, allowing you to test out patterns anywhere without needing a PI or a connected LED strip.
+
+## Multi-strip usage
+The Pi only has a single SPI bus, so it can technically only communicate with a single, contiguous strip. However you can link multiple strips in a chain using [connectors](http://www.ebay.com/itm/10pcs-10mm-4-Pin-two-Connector-with-Cable-For-SMD-LED-5050-RGB-Strip-Light-/181896959852). To ease development with multiple strips, this library offers a few convenience methods for addressing these. See the example below:
+```ruby
+# Assume 2 connected strips parallel to each other:
+# [0,  1,  2,  3,  4,  5,  6,  7,  8,  9] ====\
+# [19, 18, 17, 16, 15, 14, 13, 12, 11, 10] ===/
+
+Apa102Rbpi.configure do |c|
+  c.num_leds = 20
+end
+
+entire_strip = Apa102Rbpi.strip
+top_strip = Apa102Rbpi::Strip.new([0,9])
+bottom_strip = Apa102Rbpi::Strip.new([10,19],
+  {
+    # lets you set different offsets if your connected strips have different specs
+    led_frame_rgb_offsets: {red: 3, green: 1, blue: 2},
+    brightness: 10
+  })
+
+# sets pixel 10 red, because the 0th pixel of bottom_strip is at idx 10
+bottom_strip.set_pixel!(0, 0xff0000)
+# sets that same pixel blue
+entire_strip.set_pixel!(10, 0x0000ff)
+
+# sets both the top and bottom strip to display the same content
+top_strip.mirror(bottom_strip)
+top_strip.clear!
+top_strip.set_pixel!(2, 0x00ff00)
+# at this point, both pixel 2 and 12 are lit
+
+top_strip.clear!
+# reverses the indices of the bottom strip only
+bottom_strip.reverse
+top_strip.set_pixel!(2, 0x00ff00)
+# at this point, pixel 2 and 17 are lit.
+```
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/apa102_rbpi.gemspec

@@ -28,4 +28,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.9'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_dependency 'pi_piper', '~> 1.9'
+  spec.add_dependency 'paint'
 end

data/lib/apa102_rbpi.rb

@@ -1,6 +1,27 @@
+require 'pi_piper'
+require 'apa102_rbpi/spi_simulator'
+require 'apa102_rbpi/strip'
 require 'apa102_rbpi/apa102'
 require 'apa102_rbpi/utils'
 require 'apa102_rbpi/version'
 
 module Apa102Rbpi
+  def self.configure
+    clear_config!
+    yield base
+    strip.clear!
+  end
+
+  def self.base
+    @base ||= Apa102.new
+  end
+
+  def self.clear_config!
+    @base = nil
+    @strip = nil
+  end
+
+  def self.strip
+    @strip ||= Strip.new
+  end
 end

data/lib/apa102_rbpi/apa102.rb

@@ -1,77 +1,65 @@
-require 'pi_piper'
-
 module Apa102Rbpi
   class Apa102
-    include PiPiper
-
-    START_FRAME = [0x00] * 4
 
-    attr_accessor :brightness
-    attr_reader :num_leds, :spi_hz, :led_frame_rgb_offsets
+    attr_accessor :brightness, :spi_hz, :led_frame_rgb_offsets, :led_frames
+    attr_reader :num_leds, :interface, :start_frame, :end_frame, :simulate
 
-    def initialize(num_leds, opts = {})
-      @num_leds   = num_leds          || 1
+    def initialize
+      @num_leds = 1
 
       # default brightness, must be within 0-31
-      @brightness = opts[:brightness] || 31
-      @spi_hz     = opts[:spi_hz]     || 8000000
+      @brightness = 31
 
       # some strips may have different led frame specs
       # set offsets if using a non-default strip
       # offset:    0      1    2    3
       # frame = [header|blue|green|red],
-      @led_frame_rgb_offsets  = opts[:led_frame_rgb_offsets] || { red: 3, green: 2, blue: 1 }
+      @led_frame_rgb_offsets = {
+        red: 3,
+        green: 2,
+        blue: 1
+       }
+      @spi_hz = 8000000
+      @simulate = false
+
+      @interface = PiPiper::Spi
+      @start_frame = [0x00] * 4
+      @end_frame = calculate_end_frame
 
-      @led_frames = []
-      @end_frame = [0x00] * (@num_leds / 2.0).ceil
 
-      clear!
+      @led_frames = []
+      @substrips = {}
+      @mirrors = {}
     end
 
-    # Sets color of a single pixel at specified position in the strip
-    # accepts an array of [r,g,b] values or a single 3 byte value
-    def set_pixel(pos, color, brightness = @brightness)
-      idx = pos * 4
-      if color.is_a?(Integer)
-        @led_frames[idx] = led_frame_hdr(brightness)
-        @led_frames[idx + @led_frame_rgb_offsets[:red]] = (color & 0xFF0000) >> 16
-        @led_frames[idx + @led_frame_rgb_offsets[:green]] = (color & 0x00FF00) >> 8
-        @led_frames[idx + @led_frame_rgb_offsets[:blue]] = (color & 0x0000FF)
-      elsif color.is_a?(Array)
-        @led_frames[idx] = led_frame_hdr(brightness)
-        @led_frames[idx + @led_frame_rgb_offsets[:red]] = color[0]
-        @led_frames[idx + @led_frame_rgb_offsets[:green]] = color[1]
-        @led_frames[idx + @led_frame_rgb_offsets[:blue]] = color[2]
+    def simulate=(bool)
+      @simulate = bool
+      if @simulate
+        @interface = ::Apa102Rbpi::SpiSimulator #TODO
       else
-        raise 'Invalid color'
+        @interface = PiPiper::Spi
       end
     end
 
-    def set_pixel!(pos, color, brightness = @brightness)
-      set_pixel(pos, color, brightness)
-      show!
+    def num_leds=(num)
+      @num_leds = num
+      @end_frame = calculate_end_frame
     end
 
-    def clear!
-      @num_leds.times do |l|
-        set_pixel(l, 0)
-      end
-      show!
+    def calculate_end_frame
+      [0x00] * (@num_leds / 2.0).ceil
     end
 
-    # Writes out the led frames to the strip
     def show!
-      Spi.begin do |s|
+      interface.begin do |s|
         s.clock(@spi_hz)
-        s.write(START_FRAME + @led_frames + @end_frame)
+        s.write(@start_frame + @led_frames + @end_frame)
       end
     end
 
-    private
-
-    # First 3 bits high, then 5 bits for brightness
-    def led_frame_hdr(brightness)
-      (brightness & 0b00011111) | 0b11100000
+    def print
+      ::Apa102Rbpi::SpiSimulator.display(@led_frames)
     end
   end
 end
+

data/lib/apa102_rbpi/spi_simulator.rb

@@ -0,0 +1,52 @@
+require 'paint'
+
+module Apa102Rbpi
+  module SpiSimulator
+    class << self
+      def begin
+        yield self
+      end
+
+      # Placeholder method, no-op
+      def clock(data)
+      end
+
+      # Prints a strip in place
+      def write(data)
+        # strip off header frame bytes
+        base.start_frame.size.times { data.shift }
+        # strip off end frame byes
+        base.end_frame.size.times { data.pop }
+
+        # carriage return at the end lets us update strip display in place
+        print "[#{extract_pixels(data)}]\r"
+      end
+
+      # Prints a strip on its own line
+      def display(led_frames)
+        puts "[#{extract_pixels(led_frames)}]"
+      end
+
+      def extract_pixels(led_frames)
+        pixels = ""
+        (led_frames.size / 4).times do |idx|
+          idx *= 4
+          # frame data is 32 bytes:
+          # first byte is brightness (unused)
+          # next 3 bytes depend on the frame offsets
+
+          r = led_frames[idx + base.led_frame_rgb_offsets[:red]] || 0
+          g = led_frames[idx + base.led_frame_rgb_offsets[:green]] || 0
+          b = led_frames[idx + base.led_frame_rgb_offsets[:blue]] || 0
+          pixels << Paint['•', [r, g, b]]
+        end
+
+        pixels
+      end
+
+      def base
+        Apa102Rbpi.base
+      end
+    end
+  end
+end

data/lib/apa102_rbpi/strip.rb

@@ -0,0 +1,108 @@
+module Apa102Rbpi
+  class Strip
+
+    attr_reader :mirrors, :head, :tail, :num_leds
+    attr_accessor :led_frame_rgb_offsets, :brightness
+
+    def initialize(len = base.num_leds, opts = {})
+      if len.is_a?(Array)
+        @head = len[0]
+        @tail = len[1]
+        if @head > @tail
+          raise "Beginning of strip can't be a higher index than end"
+        end
+        @num_leds = (@tail - @head) + 1
+      else
+        @num_leds = len
+        @head = 0
+        @tail = @num_leds - 1
+      end
+
+      @reverse = false
+
+      @led_frame_rgb_offsets = opts[:led_frame_rgb_offsets] || base.led_frame_rgb_offsets
+      @brightness = opts[:brightness] || base.brightness
+      @mirrors = Set.new
+    end
+
+    def reverse
+      @reverse = !@reverse
+    end
+
+    def reversed?
+      @reverse
+    end
+
+    def mirror(strip)
+      if strip.num_leds == @num_leds
+        @mirrors.add(strip)
+        strip.mirrors.add(self)
+      else
+        raise 'Strips must be of same length to be mirrored!'
+      end
+    end
+
+    def show!
+      base.show!
+    end
+
+    def set_pixel(pos, color, brightness = @brightness)
+      q = [self]
+      seen = Set.new([self])
+      frames = base.led_frames
+      while(substrip = q.pop)
+        substrip.mirrors.each do |mirror|
+          unless seen.include?(mirror)
+            q.push(mirror)
+            seen.add(mirror)
+          end
+        end
+
+        idx = if substrip.reversed?
+                4 * ((substrip.tail - pos) % base.num_leds)
+              else
+                4 * ((pos + substrip.head) % base.num_leds)
+              end
+
+        if color.is_a?(Integer)
+          frames[idx] = substrip.led_frame_hdr(brightness)
+          frames[idx + substrip.led_frame_rgb_offsets[:red]] = (color & 0xFF0000) >> 16
+          frames[idx + substrip.led_frame_rgb_offsets[:green]] = (color & 0x00FF00) >> 8
+          frames[idx + substrip.led_frame_rgb_offsets[:blue]] = (color & 0x0000FF)
+        elsif color.is_a?(Array)
+          frames[idx] = substrip.led_frame_hdr(brightness)
+          frames[idx + substrip.led_frame_rgb_offsets[:red]] = color[0]
+          frames[idx + substrip.led_frame_rgb_offsets[:green]] = color[1]
+          frames[idx + substrip.led_frame_rgb_offsets[:blue]] = color[2]
+        else
+          raise 'Invalid color'
+        end
+      end
+    end
+
+    def set_pixel!(pos, color, brightness = @brightness)
+      set_pixel(pos, color, brightness)
+      show!
+    end
+
+    def clear
+      @num_leds.times do |l|
+        set_pixel(l, 0)
+      end
+    end
+
+    def clear!
+      clear
+      show!
+    end
+
+    def led_frame_hdr(brightness = @brightness)
+      (brightness & 0b00011111) | 0b11100000
+    end
+
+    def base
+      Apa102Rbpi.base
+    end
+  end
+end
+

data/lib/apa102_rbpi/version.rb

@@ -1,3 +1,3 @@
 module Apa102Rbpi
-  VERSION = '0.2.0'
+  VERSION = '1.0.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: apa102_rbpi
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors:
 - matl33t
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-22 00:00:00.000000000 Z
+date: 2016-06-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,6 +52,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.9'
+- !ruby/object:Gem::Dependency
+  name: paint
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: 
 email:
 - leung.mattp@gmail.com
@@ -60,6 +74,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rspec"
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
@@ -70,6 +85,8 @@ files:
 - bin/setup
 - lib/apa102_rbpi.rb
 - lib/apa102_rbpi/apa102.rb
+- lib/apa102_rbpi/spi_simulator.rb
+- lib/apa102_rbpi/strip.rb
 - lib/apa102_rbpi/utils.rb
 - lib/apa102_rbpi/version.rb
 homepage: 
@@ -98,4 +115,3 @@ signing_key:
 specification_version: 4
 summary: Simple library to drive APA102/Dotstar LEDs using a Raspberry Pi.
 test_files: []
-has_rdoc: