pi_piper 1.2.1 → 1.3

data/Manifest

@@ -6,4 +6,3 @@ lib/pi_piper/bcm2835.rb
 lib/pi_piper/libbcm2835.img
 lib/pi_piper/pin.rb
 lib/pi_piper/spi.rb
-pi_piper.gemspec

data/README.md

@@ -7,9 +7,10 @@ Pi Piper brings event driven programming to the Raspberry Pi's GPIO pins. To get
 ### GPIO
 ```ruby
 require 'pi_piper'
+include PiPiper
 
-PiPiper.watch :pin => 23 do |pin|
-  puts "Pin changed from #{pin.last_value} to #{pin.value}"
+watch :pin => 23 do
+  puts "Pin changed from #{last_value} to #{value}"
 end
 
 PiPiper.wait
@@ -36,6 +37,9 @@ PiPiper::Spi.begin do |spi|
 end
 ```
 
+## Documentation
+
+API documentation for Pi Piper can be found at [rdoc.info](http://rdoc.info/github/jwhitehorn/pi_piper/frames/).
 
 ## Example projects
 

data/Rakefile

@@ -2,7 +2,7 @@ require 'rubygems'
 require 'rake'  
 require 'echoe'  
   
-Echoe.new('pi_piper', '1.2.1') do |p|  
+Echoe.new('pi_piper', '1.3') do |p|  
   p.description     = "Event driven Raspberry Pi GPIO library"  
   p.url             = "http://github.com/jwhitehorn/pi_piper"  
   p.author          = "Jason Whitehorn"  

data/lib/pi_piper.rb

@@ -5,18 +5,40 @@ end
 PiPiper::Bcm2835.init
 
 module PiPiper
-
-  def PiPiper.watch(options)
+  extend self
+  
+  #Defines an event block to be executed when an pin event occurs.
+  #
+  # == Parameters:
+  # options:
+  #   Options hash. Options include `:pin`, `:invert` and `:trigger`.
+  # 
+  def watch(options, &block)
     Thread.new do
       pin = PiPiper::Pin.new(options)
       loop do
         pin.wait_for_change 
-        yield pin
+        if block.arity > 0
+          block.call pin
+        else
+          pin.instance_exec &block
+        end
       end 
     end.abort_on_exception = true  
   end
+  
+  #Defines an event block to be executed after a pin either goes high or low.
+  #
+  # @param [Hash] options A hash of options
+  # @option options [Fixnum] :pin The pin number to initialize. Required.
+  # @option options [Symbol] :goes The event to watch for. Either :high or :low. Required.
+  def after(options, &block)
+    options[:trigger] = options.delete(:goes) == :high ? :rising : :falling
+    watch options, &block
+  end
 
-  def PiPiper.wait
+  #Prevents the main thread from exiting. Required when using PiPiper.watch
+  def wait
     loop do sleep 1 end
   end
 

data/lib/pi_piper/bcm2835.rb

@@ -1,6 +1,8 @@
 require 'ffi'
 
 module PiPiper
+  # The Bcm2835 module is not intended to be directly called.
+  # It serves as an FFI library for PiPiper::SPI.
   module Bcm2835
     extend FFI::Library
     ffi_lib File.dirname(__FILE__) + '/libbcm2835.img'

data/lib/pi_piper/pin.rb

@@ -1,7 +1,15 @@
 module PiPiper
+  # Represents a GPIO pin on the Raspberry Pi
   class Pin
     attr_reader :pin, :last_value, :value, :direction, :invert
     
+    #Initializes a new GPIO pin.
+    #
+    # @param [Hash] options A hash of options
+    # @option options [Fixnum] :pin The pin number to initialize. Required.
+    # @option options [Symbol] :direction The direction of communication, either :in or :out. Defaults to :in.
+    # @option options [Boolean] :invert Indicates if the value read from the physical pin should be inverted. Defaults to false.
+    # @option options [Symbol] :trigger Indicates when the wait_for_change method will detect a change, either :rising, :falling, or :both edge triggers. Defaults to :both.
     def initialize(options)
       options = {:direction => :in, :invert => false, :trigger => :both}.merge options
       @pin = options[:pin]
@@ -18,30 +26,38 @@ module PiPiper
       read 
     end
     
+    # If the pin has been initialized for output this method will set the logic level high.
     def on
       File.open(value_file, 'w') {|f| f.write("1") } if direction == :out
     end
     
+    # Tests if the logic level is high.
     def on?
       not off?
     end
     
+    # If the pin has been initialized for output this method will set the logic level low.
     def off
       File.open(value_file, 'w') {|f| f.write("0") } if direction == :out
     end
     
+    # Tests if the logic level is low.
     def off?
       value == 0
     end
 
+    # If the pin has been initialized for output this method will either raise or lower the logic level depending on `new_value`.
+    # @param [Object] new_value If false or 0 the pin will be set to off, otherwise on.
     def update_value(new_value)
       !new_value || new_value == 0 ? off : on
     end
     
+    # Tests if the logic level has changed since the pin was last read.
     def changed?
       last_value != value
     end
 
+    # blocks until a logic level change occurs. The initializer option `:trigger` modifies what edge this method will release on.
     def wait_for_change
       fd = File.open(value_file, "r")
       File.open(edge_file, "w") { |f| f.write("both") }
@@ -56,7 +72,9 @@ module PiPiper
         end
       end
     end
-    
+
+    # Reads the current value from the pin. Without calling this method first, `value`, `last_value` and `changed?` will not be updated. 
+    # In short, you must call this method if you are curious about the current state of the pin.
     def read 
       @last_value = @value
       val = File.read(value_file).to_i

data/lib/pi_piper/spi.rb

@@ -1,32 +1,38 @@
-=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
+#--
+#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.
+#++
+
+
+
+
 
 module PiPiper
+  # class for SPI interfaces on the Raspberry Pi
   class Spi
     # 65536 = 256us = 4kHz
     CLOCK_DIVIDER_65536 = 0
@@ -69,6 +75,7 @@ module PiPiper
     # No CS, control it yourself
     CHIP_SELECT_NONE = 3
 
+    #Sets the SPI mode. Defaults to mode (0,0).
     def self.set_mode(cpol, cpha)
       mode = SPI_MODE0 #default
       mode = SPI_MODE1 if cpol == 0 and cpha == 1
@@ -77,6 +84,7 @@ module PiPiper
       Bcma2835.spi_set_data_mode mode
     end
 
+    #Begin an SPI block. All SPI communications should be wrapped in a block.
     def self.begin(chip=nil)
       Bcm2835.spi_begin
       chip = CHIP_SELECT_0 if !chip && block_given?
@@ -190,7 +198,7 @@ module PiPiper
     # @example Write multiple bytes
     #   spi.write(0x22, 0x33, 0x44)
     #
-    # @return [Number|Array|String] data that came out of MISO during write
+    # @return [Number|Array] data that came out of MISO during write
     def write(*args)
       case args.count
         when 0

data/pi_piper.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = "pi_piper"
-  s.version = "1.2.1"
+  s.version = "1.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jason Whitehorn"]
-  s.date = "2013-01-22"
+  s.date = "2013-01-28"
   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/bcm2835.rb", "lib/pi_piper/libbcm2835.img", "lib/pi_piper/pin.rb", "lib/pi_piper/spi.rb"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pi_piper
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: '1.3'
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-22 00:00:00.000000000 Z
+date: 2013-01-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi