pi_piper 1.1.2 → 1.2

data/Manifest

@@ -2,5 +2,7 @@ Manifest
 README.md
 Rakefile
 lib/pi_piper.rb
+lib/pi_piper/bcm2835.rb
+lib/pi_piper/libbcm2835.img
 lib/pi_piper/pin.rb
-pi_piper.gemspec
+lib/pi_piper/spi.rb

data/README.md

@@ -4,7 +4,7 @@ Pi Piper brings event driven programming to the Raspberry Pi's GPIO pins. To get
 
     sudo gem install pi_piper
 
-Sample usage:
+### GPIO
 ```ruby
 require 'pi_piper'
 
@@ -26,6 +26,31 @@ sleep 1
 pin.off
 ```
 
+### SPI
+Starting with version 1.2, PiPiper offers SPI support. Before utilizing SPI, ensure that you have Mike McCauley's [bcm2835 library](http://www.open.com.au/mikem/bcm2835/index.html) installed:
+
+    ls /usr/local/lib/libbcm2835.so
+
+If that file is not present, and you try to utilize the PiPiper::Spi class, you will receive an error similar to:
+
+    LoadError: Could not open library '/usr/local/lib/libbcm2835.so': /usr/local/lib/libbcm2835.so: cannot open shared object file: No such file or directory
+      from /var/lib/gems/1.9.1/gems/ffi-1.3.1/lib/ffi/library.rb:123:in `block in ffi_lib'
+      from /var/lib/gems/1.9.1/gems/ffi-1.3.1/lib/ffi/library.rb:90:in `map'
+      from /var/lib/gems/1.9.1/gems/ffi-1.3.1/lib/ffi/library.rb:90:in `ffi_lib'
+      from /var/lib/gems/1.9.1/gems/pi_piper-1.2/lib/pi_piper/bcm2835.rb:6:in `<module:Bcm2835>'
+      from /var/lib/gems/1.9.1/gems/pi_piper-1.2/lib/pi_piper/bcm2835.rb:4:in `<module:PiPiper>'
+      from /var/lib/gems/1.9.1/gems/pi_piper-1.2/lib/pi_piper/bcm2835.rb:3:in `<top (required)>'
+      from /usr/lib/ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
+      from /usr/lib/ruby/1.9.1/rubygems/custom_require.rb:36:in `require'
+      from /var/lib/gems/1.9.1/gems/pi_piper-1.2/lib/pi_piper/spi.rb:261:in `initialize'
+      from (irb):2:in `new'
+      from (irb):2
+      from /usr/bin/irb:12:in `<main>'
+
+For those uninterested in SPI support, the bcm2835 is a "soft" requirement and is lazy loaded. If you never intended to use PiPiper::Spi, you shouldn't have to worry about this requirement.
+
+
+
 ## Example projects
 
 Looking for more examples/sample code for Pi Piper? Then check out the following example projects, complete with circuit diagrams:
@@ -33,6 +58,7 @@ Looking for more examples/sample code for Pi Piper? Then check out the following
 * [Project 1: Morse Code](https://github.com/jwhitehorn/pi_piper/wiki/Project-1:-Morse-Code)
 * [Project 2: Simple Switch](https://github.com/jwhitehorn/pi_piper/wiki/Project-2:-Simple-Switch)
 * [Project 3: 2-bit counter](https://github.com/jwhitehorn/pi_piper/wiki/Project-3:-2-bit-counter)
+* [Project 4: MCP3008](https://github.com/jwhitehorn/pi_piper/wiki/Project-4:-MCP3008)
 
 ## License
 

data/Rakefile

@@ -2,13 +2,13 @@ require 'rubygems'
 require 'rake'  
 require 'echoe'  
   
-Echoe.new('pi_piper', '1.1.2') do |p|  
+Echoe.new('pi_piper', '1.2') do |p|  
   p.description     = "Event driven Raspberry Pi GPIO library"  
   p.url             = "http://github.com/jwhitehorn/pi_piper"  
   p.author          = "Jason Whitehorn"  
   p.email           = "jason.whitehorn@gmail.com"  
   p.ignore_pattern  = ["examples/**/*"]  
-  p.development_dependencies = []  
+  p.development_dependencies = ['ffi']  
 end  
   
 Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each { |ext| load ext }  

data/lib/pi_piper.rb

@@ -1,4 +1,8 @@
 Dir[File.dirname(__FILE__) + '/pi_piper/*.rb'].each {|file| require file }
+at_exit do 
+  PiPiper::Bcm2835.close
+end 
+PiPiper::Bcm2835.init
 
 module PiPiper
 

data/lib/pi_piper/bcm2835.rb

@@ -0,0 +1,38 @@
+require 'ffi'
+
+module PiPiper
+  module Bcm2835
+    extend FFI::Library
+    ffi_lib File.dirname(__FILE__) + '/libbcm2835.img'
+
+    SPI_MODE0 = 0
+    SPI_MODE1 = 1
+    SPI_MODE2 = 2
+    SPI_MODE3 = 3
+
+    attach_function :init, :bcm2835_init, [], :uint8
+    attach_function :close, :bcm2835_close, [], :uint8
+
+    attach_function :spi_begin,       :bcm2835_spi_begin,            [], :uint8
+    attach_function :spi_end,         :bcm2835_spi_end,              [], :uint8
+    attach_function :spi_transfer,    :bcm2835_spi_transfer,         [:uint8], :uint8
+    attach_function :spi_transfernb,  :bcm2835_spi_transfernb,       [:pointer, :pointer, :uint], :void
+    attach_function :spi_clock,       :bcm2835_spi_setClockDivider,  [:uint8], :void
+    attach_function :spi_bit_order,   :bcm2835_spi_setBitOrder,      [:uint8], :void
+    attach_function :spi_chip_select, :bcm2835_spi_chipSelect,       [:uint8], :void
+    attach_function :spi_set_data_mode, :bcm2835_spi_setDataMode,    [:uint8], :void
+    attach_function :spi_chip_select_polarity, 
+                    :bcm2835_spi_setChipSelectPolarity,              [:uint8, :uint8], :void
+
+    def self.spi_transfer_bytes(data)
+      data_out = FFI::MemoryPointer.new(data.count) 
+      data_in = FFI::MemoryPointer.new(data.count)
+      (0..data.count-1).each { |i| data_out.put_uint8(i, data[i]) }
+
+      spi_transfernb(data_out, data_in, data.count)
+
+      (0..data.count-1).map { |i| data_in.get_uint8(i) }
+    end
+
+  end
+end

data/lib/pi_piper/spi.rb

@@ -0,0 +1,229 @@
+=begin
+Modifications Copyright 2013, Jason Whitehorn and released under the terms
+of the license included in README.md
+
+Based on works, Copyright (c) 2012 Joshua Nussbaum
+
+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.
+=end
+
+module PiPiper
+  class Spi
+    # 65536 = 256us = 4kHz
+    CLOCK_DIVIDER_65536 = 0
+    # 32768 = 126us = 8kHz
+    CLOCK_DIVIDER_32768 = 32768
+    # 16384 = 64us = 15.625kHz
+    CLOCK_DIVIDER_16384 = 16384
+    # 8192 = 32us = 31.25kHz
+    CLOCK_DIVIDER_8192  = 8192
+    # 4096 = 16us = 62.5kHz
+    CLOCK_DIVIDER_4096  = 4096
+    # 2048 = 8us = 125kHz
+    CLOCK_DIVIDER_2048  = 2048
+    # 1024 = 4us = 250kHz
+    CLOCK_DIVIDER_1024  = 1024
+    # 512 = 2us = 500kHz
+    CLOCK_DIVIDER_512   = 512
+    # 256 = 1us = 1MHz
+    CLOCK_DIVIDER_256   = 256
+    # 128 = 500ns = = 2MHz
+    CLOCK_DIVIDER_128   = 128
+    # 64 = 250ns = 4MHz
+    CLOCK_DIVIDER_64    = 64
+    # 32 = 125ns = 8MHz
+    CLOCK_DIVIDER_32    = 32
+    # 16 = 50ns = 20MHz
+    CLOCK_DIVIDER_16    = 16
+
+    # Least signifigant bit first, e.g. 4 = 0b001
+    LSBFIRST = 0
+    # Most signifigant bit first, e.g. 4 = 0b100
+    MSBFIRST = 1
+
+    # Select Chip 0
+    CHIP_SELECT_0 = 0
+    # Select Chip 1
+    CHIP_SELECT_1 = 1
+    # Select both chips (ie pins CS1 and CS2 are asserted)
+    CHIP_SELECT_BOTH = 2
+    # No CS, control it yourself
+    CHIP_SELECT_NONE = 3
+
+    def self.set_mode(cpol, cpha)
+      mode = SPI_MODE0 #default
+      mode = SPI_MODE1 if cpol == 0 and cpha == 1
+      mode = SPI_MODE2 if cpol == 1 and cpha == 0
+      mode = SPI_MODE3 if cpol == 1 and cpha == 1
+      Bcma2835.spi_set_data_mode mode
+    end
+
+    def self.begin(chip=nil)
+      Bcm2835.spi_begin
+      chip = CHIP_SELECT_0 if !chip && block_given?
+      spi = new(chip)
+
+      if block_given?
+        begin
+          yield(spi)
+        ensure
+          self.end
+        end
+      else
+        spi
+      end
+    end
+
+    # Not needed when #begin is called with a block
+    def self.end
+      Bcm2835.spi_end
+    end
+
+    def clock(divider)
+      Bcm2835.spi_clock(divider)
+    end
+
+    def bit_order(order=MSBFIRST)
+      if order.is_a?(Range)  
+        if order.begin < order.end
+          order = LSBFIRST
+        else
+          order = MSBFIRST
+        end
+      end
+
+      Bcm2835.spi_bit_order(order)
+    end
+
+    # Activate a specific chip so that communication can begin
+    #
+    # When a block is provided, the chip is automatically deactivated after the block completes.
+    # When a block is not provided, the user is responsible for calling chip_select(CHIP_SELECT_NONE) 
+    #
+    # @example With block (preferred)
+    #   spi.chip_select do
+    #     spi.write(0xFF)
+    #   end
+    #
+    # @example Without block
+    #   spi.chip_select(CHIP_SELECT_0)
+    #   spi.write(0xFF)
+    #   spi.write(0x22)
+    #   spi.chip_select(CHIP_SELECT_NONE)
+    #
+    # @yield 
+    # @param [optional, CHIP_SELECT_*] chip the chip select line options
+    def chip_select(chip=CHIP_SELECT_0)
+      chip = @chip if @chip 
+      Bcm2835.spi_chip_select(chip) 
+      if block_given?
+        begin
+          yield
+        ensure
+          Bcm2835.spi_chip_select(CHIP_SELECT_NONE)
+        end
+      end
+    end
+
+    # Configure the active state of the chip select line
+    #
+    # The default state for most chips is active low.
+    #
+    # "active low" means the clock line is kept high during idle, and goes low when communicating.
+    #
+    # "active high" means the clock line is kept low during idle, and goes high when communicating.
+    #
+    # @param [Boolean] active_low true for active low, false for active high 
+    # @param [optional, CHIP_SELECT_*] chip one of CHIP_SELECT_*
+    def chip_select_active_low(active_low, chip=nil)
+      chip = @chip if @chip
+      chip = CHIP_SELECT_0 unless chip
+
+      Bcm2835.spi_chip_select_polarity(chip, active_low ? 0 : 1)
+    end
+
+    # Read from the bus
+    #
+    # @example Read a single byte
+    #   byte = spi.read
+    #
+    # @example Read array of bytes
+    #   array = spi.read(3)
+    #
+    #
+    # @param [optional, Number] count the number of bytes to read. 
+    #   When count is provided, an array is returned.
+    #   When count is nil, a single byte is returned.
+    # @return [Number|Array] data that was read from the bus
+    def read(count=nil)
+      if count
+        write([0xFF] * count)
+      else
+        enable { Bcm2835.spi_transfer(0) }
+      end
+    end
+
+    # Write to the bus
+    #
+    # @example Write a single byte
+    #   spi.write(0x22)
+    #
+    # @example Write multiple bytes
+    #   spi.write(0x22, 0x33, 0x44)
+    #
+    # @return [Number|Array|String] data that came out of MISO during write
+    def write(*args)
+      case args.count
+        when 0
+          raise ArgumentError.new("missing arguments")
+        when 1
+          data = args.first
+        else
+          data = args
+      end
+
+      enable do
+        case data
+        when Numeric
+          Bcm2835.spi_transfer(data)
+        when Enumerable
+          Bcm2835.spi_transfer_bytes(data)
+        else
+          raise ArgumentError.new("#{data.class} is not valid data. Use Numeric or an Enumerable of numbers")
+        end
+      end
+    end
+
+  private
+    def initialize(chip)
+      @chip = chip
+    end
+
+    def enable(&block)
+      if @chip
+        chip_select(&block)
+      else
+        yield
+      end
+    end
+  end
+end

data/pi_piper.gemspec

@@ -2,15 +2,15 @@
 
 Gem::Specification.new do |s|
   s.name = "pi_piper"
-  s.version = "1.1.2"
+  s.version = "1.2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jason Whitehorn"]
-  s.date = "2013-01-20"
+  s.date = "2013-01-21"
   s.description = "Event driven Raspberry Pi GPIO library"
   s.email = "jason.whitehorn@gmail.com"
-  s.extra_rdoc_files = ["README.md", "lib/pi_piper.rb", "lib/pi_piper/pin.rb"]
-  s.files = ["Manifest", "README.md", "Rakefile", "lib/pi_piper.rb", "lib/pi_piper/pin.rb", "pi_piper.gemspec"]
+  s.extra_rdoc_files = ["README.md", "lib/pi_piper.rb", "lib/pi_piper/bcm2835.rb", "lib/pi_piper/libbcm2835.img", "lib/pi_piper/pin.rb", "lib/pi_piper/spi.rb"]
+  s.files = ["Manifest", "README.md", "Rakefile", "lib/pi_piper.rb", "lib/pi_piper/bcm2835.rb", "lib/pi_piper/libbcm2835.img", "lib/pi_piper/pin.rb", "lib/pi_piper/spi.rb", "pi_piper.gemspec"]
   s.homepage = "http://github.com/jwhitehorn/pi_piper"
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Pi_piper", "--main", "README.md"]
   s.require_paths = ["lib"]
@@ -22,8 +22,11 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_development_dependency(%q<ffi>, [">= 0"])
     else
+      s.add_dependency(%q<ffi>, [">= 0"])
     end
   else
+    s.add_dependency(%q<ffi>, [">= 0"])
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pi_piper
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: '1.2'
   prerelease: 
 platform: ruby
 authors:
@@ -9,8 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-20 00:00:00.000000000 Z
-dependencies: []
+date: 2013-01-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Event driven Raspberry Pi GPIO library
 email: jason.whitehorn@gmail.com
 executables: []
@@ -18,13 +34,19 @@ extensions: []
 extra_rdoc_files:
 - README.md
 - lib/pi_piper.rb
+- lib/pi_piper/bcm2835.rb
+- lib/pi_piper/libbcm2835.img
 - lib/pi_piper/pin.rb
+- lib/pi_piper/spi.rb
 files:
 - Manifest
 - README.md
 - Rakefile
 - lib/pi_piper.rb
+- lib/pi_piper/bcm2835.rb
+- lib/pi_piper/libbcm2835.img
 - lib/pi_piper/pin.rb
+- lib/pi_piper/spi.rb
 - pi_piper.gemspec
 homepage: http://github.com/jwhitehorn/pi_piper
 licenses: []