beaglebone 1.0.4 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2e81b55e60fccf3fe77f817e676d3cb0eefe32e0
-  data.tar.gz: 0de69ddacb24ca2703ddf2c5192a8d97c12a3fa5
+  metadata.gz: 7ebe3395979d7ccd5ddbd563705281820b5ed54d
+  data.tar.gz: ef2f2c1bb2f50761e5837472c3777781ff767297
 SHA512:
-  metadata.gz: dc992fe711c42c03d70cd62d974659345abe8eadf0ec54e33907447acef4cee6c3523f35d0da1278afd6e1bdb06068f092c74c845592f6427517a262e28a3def
-  data.tar.gz: e93429663cd19116da5eaa610000843953d58b0b6820384c79ba186e902f00a72b64247df01dafcdc5d05e381098bc8a577e970ba62be7b3017c780969c9c65a
+  metadata.gz: 911649b330a3dfbd7ba1f21bfb0b4763b4ba9842513138bc460c71297d34ca63cac7005ce133f9aff2b43b321473ffc711ab02a1b0a63c1ecbe2902ab961e5d3
+  data.tar.gz: e9b5b5dd6fd8ebf76c40758fe7a6d44fa9187df710d948cb8007f8aa020b4705a48417b7d8db630188fb0fc5f468b147fc79ff1927e15cef0c28f5bfbfe397c7

data/beaglebone.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'beaglebone'
-  s.version     = '1.0.4'
+  s.version     = '1.0.5'
   s.date        = '2014-04-13'
   s.summary     = 'Beaglebone IO Gem'
   s.description = 'A Full Featured Beaglebone IO Gem'

data/examples/i2c.rb

@@ -12,7 +12,7 @@ i2c = I2CDevice.new(:I2C2)
 i2c.write(0x1e, [0x02, 0x00].pack("C*"))
 
 #enable temperatuer sensor, 15hz register update
-i2c.write(0x1e, [0x00, "10010000".to_i(2)].pack("C*") )
+i2c.write(0x1e, [0x00, 0b10010000].pack("C*") )
 
 #delay for the settings to take effect
 sleep(0.1)
@@ -66,7 +66,7 @@ I2C.setup(:I2C2)
 #put mag into continuous conversation mode
 I2C.write(:I2C2, 0x1e, [0x02, 0x00].pack("C*"))
 #enable temperatuer sensor, 15hz register update
-I2C.write(:I2C2, 0x1e, [0x00, "10010000".to_i(2)].pack("C*") )
+I2C.write(:I2C2, 0x1e, [0x00, 0b10010000].pack("C*") )
 #delay for the settings to take effect
 sleep(0.1)
 

data/lib/beaglebone/ain.rb

@@ -1,11 +1,11 @@
 # == ain.rb
 # This file contains the Analog Input methods
 module Beaglebone #:nodoc:
-  # AIN
+  # == AIN
   # procedural methods for Analog Input
   # == Summary
-  # #read is called to get the analog value of a pin
-  # more advanced polling methods are also available
+  # #read is called to get the analog value of a pin.
+  # More advanced polling methods are also available
   module AIN
     class << self
 
@@ -45,8 +45,8 @@ module Beaglebone #:nodoc:
         ain_fd.read.strip.to_i
       end
 
-      # Runs a callback after voltage changes by specified amount
-      # This creates a new thread that runs in the background and polls at specified interval
+      # Runs a callback after voltage changes by specified amount.
+      # This creates a new thread that runs in the background and polls at specified interval.
       #
       # @param callback A method to call when the change is detected.  This method should take 4 arguments: the pin, the previous voltage, the current voltage, and the counter
       # @param pin should be a symbol representing the header pin, i.e. :P9_11
@@ -99,9 +99,9 @@ module Beaglebone #:nodoc:
         run_on_change(callback, pin, mv_change, interval, 1)
       end
 
-      # Runs a callback after voltage changes beyond a certain threshold
-      # This creates a new thread that runs in the background and polls at specified interval
-      # When the voltage crosses the specified thresholds the callback is run
+      # Runs a callback after voltage changes beyond a certain threshold.
+      # This creates a new thread that runs in the background and polls at specified interval.
+      # When the voltage crosses the specified thresholds the callback is run.
       #
       # @param callback A method to call when the change is detected.  This method should take 6 arguments: the pin, the previous voltage, the current voltage, the previous state, the current state, and the counter
       # @param pin should be a symbol representing the header pin, i.e. :P9_11
@@ -153,7 +153,7 @@ module Beaglebone #:nodoc:
         Beaglebone::set_pin_status(pin, :thread, thread)
       end
 
-      # Runs a callback once after voltage crosses a specified threshold
+      # Runs a callback once after voltage crosses a specified threshold.
       # Convenience method for run_on_threshold
       # @see #run_on_threshold
       def run_once_on_threshold(callback, pin, mv_lower, mv_upper, mv_reset=10, interval=0.01)
@@ -162,9 +162,9 @@ module Beaglebone #:nodoc:
 
       # noinspection RubyScope
 
-      # Runs a callback after voltage changes beyond a certain threshold
-      # This creates a new thread that runs in the background and polls at specified interval
-      # When the voltage crosses the specified thresholds the callback is run
+      # Runs a callback after voltage changes beyond a certain threshold.
+      # This creates a new thread that runs in the background and polls at specified interval.
+      # When the voltage crosses the specified thresholds the callback is run.
       #
       # This method should take 6 arguments:
       # the pin, the previous voltage, the current voltage, the previous state, the current state, and the counter
@@ -374,8 +374,8 @@ module Beaglebone #:nodoc:
       AIN::read(@pin)
     end
 
-    # Runs a callback after voltage changes by specified amount
-    # This creates a new thread that runs in the background and polls at specified interval
+    # Runs a callback after voltage changes by specified amount.
+    # This creates a new thread that runs in the background and polls at specified interval.
     #
     # @param callback A method to call when the change is detected
     # This method should take 4 arguments: the pin, the previous voltage, the current voltage, and the counter
@@ -399,13 +399,11 @@ module Beaglebone #:nodoc:
     end
 
 
-    # Runs a callback after voltage changes beyond a certain threshold
-    # This creates a new thread that runs in the background and polls at specified interval
-    # When the voltage crosses the specified thresholds the callback is run
+    # Runs a callback after voltage changes beyond a certain threshold.
+    # This creates a new thread that runs in the background and polls at specified interval.
+    # When the voltage crosses the specified thresholds the callback is run.
     #
-    # @param callback A method to call when the change is detected
-    # This method should take 6 arguments:
-    # the pin, the previous voltage, the current voltage, the previous state, the current state, and the counter
+    # @param callback A method to call when the change is detected. This method should take 6 arguments: the pin, the previous voltage, the current voltage, the previous state, the current state, and the counter
     # @param mv_lower an integer specifying the lower threshold voltage
     # @param mv_upper an integer specifying the upper threshold voltage
     # @param mv_reset an integer specifying the range in mv required to reset the threshold trigger
@@ -425,7 +423,7 @@ module Beaglebone #:nodoc:
     end
 
 
-    # Runs a callback once after voltage crosses a specified threshold
+    # Runs a callback once after voltage crosses a specified threshold.
     # Convenience method for run_on_threshold
     def run_once_on_threshold(callback, mv_lower, mv_upper, mv_reset=10, interval=0.01)
       AIN::run_once_on_threshold(callback, @pin, mv_lower, mv_upper, mv_reset, interval)

data/lib/beaglebone/beaglebone.rb

@@ -89,10 +89,8 @@ module Beaglebone
       :P9_15 => { :gpio => 48 },
       :P9_16 => { :gpio => 51, :pwm => 'pwm_1b', :pwm_id => 1, :pwm_mux => 6 },
       #17 and 18 are not currently working for gpio in 3.8
-      #:P9_17 => { :gpio => 4, :i2c => 'i2c1_scl', :i2c_id => 1, :spi => 'spi0_cs0', :spi_id => 0 },
-      #:P9_18 => { :gpio => 5, :i2c => 'i2c1_sda', :i2c_id => 1, :spi => 'spi0_d1', :spi_id => 0 },
-      :P9_17 => { :i2c => 'i2c1_scl', :i2c_id => 1, :spi => 'spi0_cs0', :spi_id => 0 },
-      :P9_18 => { :i2c => 'i2c1_sda', :i2c_id => 1, :spi => 'spi0_d1', :spi_id => 0 },
+      :P9_17 => { :gpio => 4, :i2c => 'i2c1_scl', :i2c_id => 1, :spi => 'spi0_cs0', :spi_id => 0 },
+      :P9_18 => { :gpio => 5, :i2c => 'i2c1_sda', :i2c_id => 1, :spi => 'spi0_d1', :spi_id => 0 },
       :P9_19 => { :i2c => 'i2c2_scl', :i2c_id => 2, :uart => 'uart1_rtsn', :uart_id => 1, :spi => 'spi1_cs1', :spi_id => 1 },
       :P9_20 => { :i2c => 'i2c2_sda', :i2c_id => 2, :uart => 'uart1_ctsn', :uart_id => 1, :spi => 'spi1_cs0', :spi_id => 1 },
       :P9_21 => { :gpio => 3, :pwm => 'pwm_0b', :pwm_id => 0, :pwm_mux => 3, :i2c => 'i2c2_scl', :i2c_id => 2, :uart => 'uart2_txd', :uart_id => 2, :spi => 'spi0_d0', :spi_id => 0 },
@@ -175,6 +173,7 @@ module Beaglebone
   class << self
     attr_accessor :pinstatus, :pinmutex, :loaded_dtbs
 
+    # @private
     # get hash entry for pin
     def get_pin_status(pin, key = nil)
       pinmutex.synchronize do
@@ -186,6 +185,7 @@ module Beaglebone
       end
     end
 
+    # @private
     # set hash entry for pin
     def set_pin_status(pin, key, value)
       pinmutex.synchronize do
@@ -194,6 +194,7 @@ module Beaglebone
       end
     end
 
+    # @private
     # delete pin's hash entry
     def delete_pin_status(pin, key = nil)
       pinmutex.synchronize do

data/lib/beaglebone/gpio.rb

@@ -2,7 +2,7 @@
 # This file contains the GPIO methods
 
 module Beaglebone #:nodoc:
-  # GPIO
+  # == GPIO
   # procedural methods for GPIO control
   # == Summary
   # #pin_mode is called to initialize a pin.
@@ -101,7 +101,7 @@ module Beaglebone #:nodoc:
         Beaglebone::set_pin_status(pin, :state, state)
       end
 
-      # Runs a callback on an edge trigger event
+      # Runs a callback on an edge trigger event.
       # This creates a new thread that runs in the background
       #
       # @param callback A method to call when the edge trigger is detected.  This method should take 3 arguments, the pin, the edge, and the counter
@@ -139,8 +139,8 @@ module Beaglebone #:nodoc:
         Beaglebone::set_pin_status(pin, :thread, thread)
       end
 
-      # Runs a callback one time on an edge trigger event
-      # this is a convenience method for run_on_edge
+      # Runs a callback one time on an edge trigger event.
+      # This is a convenience method for run_on_edge
       # @see #run_on_edge
       def run_once_on_edge(callback, pin, edge, timeout = nil)
         run_on_edge(callback, pin, edge, timeout, 1)
@@ -156,7 +156,7 @@ module Beaglebone #:nodoc:
         thread.join if thread
       end
 
-      # Wait for an edge trigger
+      # Wait for an edge trigger.
       # Returns the type that triggered the event, e.g. :RISING, :FALLING, :BOTH
       #
       # @returns [Symbol] :RISING, :FALLING, or :BOTH
@@ -221,8 +221,8 @@ module Beaglebone #:nodoc:
       # Sends data to a shift register
       #
       # @param latch_pin should be a symbol representing the header pin, i.e. :P9_12
-      # @param clock_pin should be a symbol representing the header pin, i.e. :P9_12
-      # @param data_pin should be a symbol representing the header pin, i.e. :P9_12
+      # @param clock_pin should be a symbol representing the header pin, i.e. :P9_13
+      # @param data_pin should be a symbol representing the header pin, i.e. :P9_14
       # @param data Integer value to write to the shift register
       # @param lsb optional, send least significant bit first if set
       #
@@ -505,7 +505,7 @@ module Beaglebone #:nodoc:
       GPIO::digital_read(@pin)
     end
 
-    # Runs a callback on an edge trigger event
+    # Runs a callback on an edge trigger event.
     # This creates a new thread that runs in the background
     #
     # @param callback A method to call when the edge trigger is detected.  This method should take 3 arguments, the pin, the edge, and the counter
@@ -520,7 +520,7 @@ module Beaglebone #:nodoc:
       GPIO::run_on_edge(callback, @pin, edge, timeout, repeats)
     end
 
-    # Runs a callback one time on an edge trigger event
+    # Runs a callback one time on an edge trigger event.
     # this is a convenience method for run_on_edge
     # @see #run_on_edge
     def run_once_on_edge(callback, edge, timeout=nil)
@@ -533,7 +533,7 @@ module Beaglebone #:nodoc:
       GPIO::stop_edge_wait(@pin)
     end
 
-    # Wait for an edge trigger
+    # Wait for an edge trigger.
     # Returns the type that triggered the event, e.g. :RISING, :FALLING, :BOTH
     #
     # @return [Symbol] :RISING, :FALLING, or :BOTH

data/lib/beaglebone/i2c.rb

@@ -1,5 +1,10 @@
-module Beaglebone
-
+# == i2c.rb
+# This file contains I2C methods
+module Beaglebone #:nodoc:
+  # == I2C
+  # Procedural methods for I2C control
+  # == Summary
+  # #setup is called to initialize an I2C device
   module I2C
 
     I2C_SLAVE = 0x0703
@@ -10,6 +15,48 @@ module Beaglebone
     class << self
       attr_accessor :i2cstatus, :i2cmutex
 
+      # Initialize an I2C device
+      #
+      # @param i2c should be a symbol representing the I2C device
+      #
+      # @example
+      #   I2C.setup(:I2C2)
+      def setup(i2c)
+        check_i2c_valid(i2c)
+
+        #make sure i2c not already enabled
+        return if get_i2c_status(i2c)
+
+        i2cinfo = I2CS[i2c]
+
+        #ensure dtb is loaded
+        Beaglebone::device_tree_load("#{i2cinfo[:devicetree]}") if i2cinfo[:devicetree]
+
+        #open the i2c device
+        i2c_fd = File.open(i2cinfo[:dev], 'r+')
+
+        Beaglebone::set_pin_status(i2cinfo[:scl], :i2c, i2cinfo[:id])
+        Beaglebone::set_pin_status(i2cinfo[:scl], :type, :i2c)
+        Beaglebone::set_pin_status(i2cinfo[:scl], :fd_i2c, i2c_fd)
+
+        Beaglebone::set_pin_status(i2cinfo[:sda], :i2c, i2cinfo[:id])
+        Beaglebone::set_pin_status(i2cinfo[:sda], :type, :i2c)
+        Beaglebone::set_pin_status(i2cinfo[:sda], :fd_i2c, i2c_fd)
+
+        set_i2c_status(i2c, :fd_i2c, i2c_fd)
+        set_i2c_status(i2c, :mutex, Mutex.new)
+      end
+
+      # Write data to an I2C device
+      #
+      # @param i2c should be a symbol representing the I2C device
+      # @param address the address of the slave device
+      # @param data the data to write
+      #
+      # @return Integer the number of bytes written
+      #
+      # @example
+      #  I2C.write(:I2C2, 0x1e, [0x00, 0b10010000].pack("C*") )
       def write(i2c, address, data)
         check_i2c_enabled(i2c)
 
@@ -21,9 +68,19 @@ module Beaglebone
 
           i2c_fd.syswrite(data)
         end
-
       end
 
+      # Read data from an I2C device
+      #
+      # @param i2c should be a symbol representing the I2C device
+      # @param address the address of the slave device
+      # @param bytes bytes to read
+      # @param register optional register to read from
+      #
+      # @example
+      #   # read 3 big endian signed shorts starting at register 0x03
+      #   data = I2C.read(:I2C2, 0x1e, 6, [0x03].pack("C*"))
+      #     x,z,y = raw.unpack("s>*")
       def read(i2c, address, bytes=1, register=nil)
         check_i2c_enabled(i2c)
 
@@ -42,37 +99,19 @@ module Beaglebone
         data
       end
 
+      # Return the file descriptor to the open I2C device
+      #
+      # @param i2c should be a symbol representing the I2C device
       def file(i2c)
         check_i2c_enabled(i2c)
         get_i2c_status(i2c, :fd_i2c)
       end
 
-      def setup(i2c)
-        check_i2c_valid(i2c)
-
-        #make sure i2c not already enabled
-        return if get_i2c_status(i2c)
-
-        i2cinfo = I2CS[i2c]
-
-        #ensure dtb is loaded
-        Beaglebone::device_tree_load("#{i2cinfo[:devicetree]}") if i2cinfo[:devicetree]
-
-        #open the i2c device
-        i2c_fd = File.open(i2cinfo[:dev], 'r+')
-
-        Beaglebone::set_pin_status(i2cinfo[:scl], :i2c, i2cinfo[:id])
-        Beaglebone::set_pin_status(i2cinfo[:scl], :type, :i2c)
-        Beaglebone::set_pin_status(i2cinfo[:scl], :fd_i2c, i2c_fd)
-
-        Beaglebone::set_pin_status(i2cinfo[:sda], :i2c, i2cinfo[:id])
-        Beaglebone::set_pin_status(i2cinfo[:sda], :type, :i2c)
-        Beaglebone::set_pin_status(i2cinfo[:sda], :fd_i2c, i2c_fd)
-
-        set_i2c_status(i2c, :fd_i2c, i2c_fd)
-        set_i2c_status(i2c, :mutex, Mutex.new)
-      end
-
+      # Disable the specified I2C device.
+      #
+      # @note device trees cannot be unloaded at this time without kernel panic.
+      #
+      # @param i2c should be a symbol representing the I2C device
       def disable(i2c)
         check_i2c_valid(i2c)
         check_i2c_enabled(i2c)
@@ -87,6 +126,7 @@ module Beaglebone
 
       end
 
+      # Disable all active I2C interfaces
       def cleanup
         #reset all i2cs we've used and unload the device tree
         i2cstatus.clone.keys.each { |i2c| disable(i2c)}
@@ -94,12 +134,14 @@ module Beaglebone
 
       private
 
+      # disable i2c pin
       def disable_i2c_pin(pin)
         Beaglebone::check_valid_pin(pin, :i2c)
 
         Beaglebone::delete_pin_status(pin)
       end
 
+      # ensure valid i2c device
       def check_i2c_valid(i2c)
         raise ArgumentError, "Invalid i2c Specified #{i2c.to_s}" unless I2CS[i2c] && I2CS[i2c][:sda]
         i2cinfo = I2CS[i2c.to_sym.upcase]
@@ -114,10 +156,12 @@ module Beaglebone
 
       end
 
+      # ensure i2c device is enabled
       def check_i2c_enabled(i2c)
         raise ArgumentError, "i2c not enabled #{i2c.to_s}" unless get_i2c_status(i2c)
       end
 
+      # lock i2c device
       def lock_i2c(i2c)
         check_i2c_enabled(i2c)
         mutex = get_i2c_status(i2c, :mutex)
@@ -127,6 +171,7 @@ module Beaglebone
         end
       end
 
+      # i2c hash getter
       def get_i2c_status(i2c, key = nil)
         i2cmutex.synchronize do
           if key
@@ -137,6 +182,7 @@ module Beaglebone
         end
       end
 
+      # i2c hash setter
       def set_i2c_status(i2c, key, value)
         i2cmutex.synchronize do
           i2cstatus[i2c]    ||= {}
@@ -144,6 +190,7 @@ module Beaglebone
         end
       end
 
+      # i2c hash delete
       def delete_i2c_status(i2c, key = nil)
         i2cmutex.synchronize do
           if key.nil?
@@ -157,30 +204,57 @@ module Beaglebone
     end
   end
 
-  #oo interface
+  # Object Oriented I2C Implementation.
+  # This treats the I2C device as an object.
   class I2CDevice
-
+    # Initialize an I2C device.  Returns an I2CDevice object
+    #
+    # @param i2c should be a symbol representing the I2C device
+    #
+    # @example
+    #   i2c = I2CDevice.new(:I2C2)
     def initialize(i2c)
       @i2c = i2c
       I2C::setup(@i2c)
     end
 
-    def read(address, bytes=1, register=nil)
-      I2C::read(@i2c, address, bytes, register)
-    end
-
+    # Write data to an I2C device
+    #
+    # @param address the address of the slave device
+    # @param data the data to write
+    #
+    # @return Integer the number of bytes written
+    #
+    # @example
+    #  i2c.write(0x1e, [0x00, 0b10010000].pack("C*") )
     def write(address, data)
       I2C::write(@i2c, address, data)
     end
 
+    # Read data from an I2C device
+    #
+    # @param address the address of the slave device
+    # @param bytes bytes to read
+    # @param register optional register to read from
+    #
+    # @example
+    #   # read 3 big endian signed shorts starting at register 0x03
+    #   data = i2c.read(0x1e, 6, [0x03].pack("C*"))
+    #     x,z,y = raw.unpack("s>*")
+    def read(address, bytes=1, register=nil)
+      I2C::read(@i2c, address, bytes, register)
+    end
+
+    # Disable the specified I2C device.
+    #
+    # @note device trees cannot be unloaded at this time without kernel panic.
     def disable
       I2C::disable(@i2c)
     end
 
+    # Return the file descriptor to the open I2C device
     def file
       I2C::file(@i2c)
     end
-
   end
-
 end