beaglebone 1.0.4 → 1.0.5

data/lib/beaglebone/pwm.rb

@@ -1,7 +1,7 @@
 # == pwm.rb
 # This file contains the PWM control methods
 module Beaglebone #:nodoc:
-  # AIN
+  # == PWM
   # procedural methods for PWM control
   # == Summary
   # #start is called to enable a PWM pin

data/lib/beaglebone/shiftregister.rb

@@ -1,6 +1,17 @@
+# == shiftregister.rb
+# This file contains the shiftregister control methods
 module Beaglebone
   class ShiftRegister
 
+    # Create a shiftregister object based on 3 GPIO pins
+    #
+    # @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_13
+    # @param data_pin should be a symbol representing the header pin, i.e. :P9_14
+    # @param lsb optional, send least significant bit first if set
+    #
+    # @example
+    #   shiftregister = ShiftRegister.new(:P9_11, :P9_12, :P9_13)
     def initialize(latch_pin, clock_pin, data_pin, lsb=nil)
 
       @latch_pin = latch_pin
@@ -13,6 +24,14 @@ module Beaglebone
       GPIO::pin_mode(@data_pin, :OUT)
     end
 
+    # Send data to shift register
+    #
+    # @param data Integer value to write to the shift register
+    # @param lsb optional, send least significant bit first if set
+    #
+    # @example
+    #   shiftregister = ShiftRegister.new(:P9_11, :P9_12, :P9_13)
+    #   shiftregister.shift_out(255)
     def shiftout(data, lsb=nil)
       GPIO::shift_out(@latch_pin, @clock_pin, @data_pin, data, lsb || @lsb)
     end

data/lib/beaglebone/spi.rb

@@ -1,5 +1,10 @@
-module Beaglebone
-
+# == spi.rb
+# This file contains SPI methods
+module Beaglebone #:nodoc:
+  # == SPI
+  # Procedural methods for SPI control
+  # == Summary
+  # #setup is called to initialize an SPI device
   module SPI
     #some ioctl defines
     IOC_NONE  = 0
@@ -56,6 +61,69 @@ module Beaglebone
     class << self
 
       attr_accessor :spistatus, :spimutex
+
+      # Initialize an SPI device
+      #
+      # @param spi should be a symbol representing the SPI device
+      # @param mode optional, default 0, specifies the SPI mode :SPI_MODE_0 through 3
+      # @param speed optional, specifies the SPI communication speed
+      # @param bpw optional, specifies the bits per word
+      #
+      # @example
+      #   SPI.setup(:SPI0, SPI_MODE_0)
+      def setup(spi, mode=nil, speed=1000000, bpw=8)
+        check_spi_valid(spi)
+
+        #make sure spi not already enabled
+        return if get_spi_status(spi)
+
+        mode = mode || SPI_MODE_0
+
+        spiinfo = SPIS[spi]
+
+        #ensure dtb is loaded
+        Beaglebone::device_tree_load("#{spiinfo[:devicetree]}") if spiinfo[:devicetree]
+
+        #open the spi device.
+        spi_fd = File.open("#{spiinfo[:dev]}#{SPIS[:counter]}.0", 'r+')
+
+        set_spi_status(spi, :fd_spi, spi_fd)
+        set_spi_status(spi, :mutex, Mutex.new)
+
+        set_mode(spi, mode)
+        set_bpw(spi, bpw)
+        set_speed(spi, speed)
+
+        SPIS[:counter] += 1
+
+        spiinfo[:pins].each do |pin|
+          Beaglebone::set_pin_status(pin, :spi, spiinfo[:id])
+          Beaglebone::set_pin_status(pin, :type, :spi)
+          Beaglebone::set_pin_status(pin, :fd_spi, spi_fd)
+        end
+
+      end
+
+      # Transfer data to and from the SPI device
+      #
+      # @return String data read from SPI device
+      #
+      # @param spi should be a symbol representing the SPI device
+      # @param tx_data data to transmit
+      # @param readbytes bytes to read, otherwise it sizeof tx_data is used
+      # @param speed optional, speed to xfer at
+      # @param delay optional delay
+      # @param bpw optional bits per word
+      #
+      # @example
+      #   # communicate with MCP3008
+      #   # byte 1: start bit
+      #   # byte 2: single(1)/diff(0),3 bites for channel, null pad
+      #   # byte 3: don't care
+      #   SPI.setup(:SPI0, SPI_MODE_0)
+      #   raw = SPI.xfer(:SPI0, [ 0b00000001, 0b10000000, 0].pack("C*"))
+      #   data = raw.unpack("C*")
+      #   val = ((data[1] & 0b00000011) << 8 ) | data[2]
       def xfer(spi, tx_data, readbytes=0, speed=nil, delay=nil, bpw=nil)
         check_spi_enabled(spi)
 
@@ -103,11 +171,18 @@ module Beaglebone
         rx_data
       end
 
+      # Return the file descriptor to the open SPI device
+      #
+      # @param spi should be a symbol representing the SPI device
       def file(spi)
         check_spi_enabled(spi)
         get_spi_status(spi, :fd_spi)
       end
 
+      # Set the communication speed of the specified SPI device
+      #
+      # @param spi should be a symbol representing the SPI device
+      # @param speed communication speed
       def set_speed(spi, speed)
         speed = speed.to_i
         raise ArgumentError, "Speed (#{speed.to_s}) must be a positive integer" unless speed > 0
@@ -120,6 +195,10 @@ module Beaglebone
         set_spi_status(spi, :speed, speed)
       end
 
+      # Set the communication speed of the specified SPI device
+      #
+      # @param spi should be a symbol representing the SPI device
+      # @param mode should be a valid SPI mode, e.g. :SPI_MODE_0 through 3
       def set_mode(spi, mode)
         check_spi_enabled(spi)
         raise ArgumentError, "Mode (#{mode.to_s}) is unknown" unless [SPI_MODE_0, SPI_MODE_1, SPI_MODE_2, SPI_MODE_3].include?(mode)
@@ -129,6 +208,10 @@ module Beaglebone
         spi_fd.ioctl(SPI_IOC_RD_MODE, [mode].pack('C'))
       end
 
+      # Set the bits per word of the specified SPI device
+      #
+      # @param spi should be a symbol representing the SPI device
+      # @param bpw should specify the bits per word
       def set_bpw(spi, bpw)
         bpw = bpw.to_i
         raise ArgumentError, "BPW (#{bpw.to_s}) must be a positive integer" unless bpw > 0
@@ -141,39 +224,11 @@ module Beaglebone
         set_spi_status(spi, :bpw, bpw)
       end
 
-      def setup(spi, mode=nil, speed=1000000, bpw=8)
-        check_spi_valid(spi)
-
-        #make sure spi not already enabled
-        return if get_spi_status(spi)
-
-        mode = mode || SPI_MODE_0
-
-        spiinfo = SPIS[spi]
-
-        #ensure dtb is loaded
-        Beaglebone::device_tree_load("#{spiinfo[:devicetree]}") if spiinfo[:devicetree]
-
-        #open the spi device.
-        spi_fd = File.open("#{spiinfo[:dev]}#{SPIS[:counter]}.0", 'r+')
-
-        set_spi_status(spi, :fd_spi, spi_fd)
-        set_spi_status(spi, :mutex, Mutex.new)
-
-        set_mode(spi, mode)
-        set_bpw(spi, bpw)
-        set_speed(spi, speed)
-
-        SPIS[:counter] += 1
-
-        spiinfo[:pins].each do |pin|
-          Beaglebone::set_pin_status(pin, :spi, spiinfo[:id])
-          Beaglebone::set_pin_status(pin, :type, :spi)
-          Beaglebone::set_pin_status(pin, :fd_spi, spi_fd)
-        end
-
-      end
-
+      # Disable the specified SPI device
+      #
+      # @note device trees cannot be unloaded at this time without kernel panic.
+      #
+      # @param spi should be a symbol representing the SPI device
       def disable(spi)
         check_spi_valid(spi)
         check_spi_enabled(spi)
@@ -189,6 +244,7 @@ module Beaglebone
 
       end
 
+      # Disable all active SPI devices
       def cleanup
         #reset all spis we've used and unload the device tree
         spistatus.clone.keys.each { |spi| disable(spi)}
@@ -196,6 +252,7 @@ module Beaglebone
 
       private
 
+      #ensure spi is valid
       def check_spi_valid(spi)
         raise ArgumentError, "Invalid spi Specified #{spi.to_s}" unless SPIS[spi] && SPIS[spi][:sclk]
         spiinfo = SPIS[spi.to_sym.upcase]
@@ -217,6 +274,7 @@ module Beaglebone
         end
       end
 
+      # lock spi
       def lock_spi(spi)
         check_spi_enabled(spi)
         mutex = get_spi_status(spi, :mutex)
@@ -226,10 +284,12 @@ module Beaglebone
         end
       end
 
+      # ensure spi is enabled
       def check_spi_enabled(spi)
         raise ArgumentError, "spi not enabled #{spi.to_s}" unless get_spi_status(spi)
       end
 
+      # disable spi pin
       def disable_spi_pin(pin)
         Beaglebone::check_valid_pin(pin, :spi)
 
@@ -290,33 +350,80 @@ module Beaglebone
     end
   end
 
-  #oo interface
+  # Object Oriented SPI Implementation.
+  # This treats the SPI device as an object.
   class SPIDevice
+    # Initialize an SPI device.  Returns an SPIDevice object
+    #
+    # @param spi should be a symbol representing the SPI device
+    # @param mode optional, default 0, specifies the SPI mode :SPI_MODE_0 through 3
+    # @param speed optional, specifies the SPI communication speed
+    # @param bpw optional, specifies the bits per word
+    #
+    # @example
+    #   spi = SPIDevice.new(:SPI0, SPI_MODE_0)
     def initialize(spi,  mode=nil, speed=1000000, bpw=8)
       @spi = spi
       SPI::setup(@spi, mode, speed, bpw)
     end
 
+    # Transfer data to and from the SPI device
+    #
+    # @return String data read from SPI device
+    #
+    # @param tx_data data to transmit
+    # @param readbytes bytes to read, otherwise it sizeof tx_data is used
+    # @param speed optional, speed to xfer at
+    # @param delay optional delay
+    # @param bpw optional bits per word
+    #
+    # @example
+    #   # communicate with MCP3008
+    #   # byte 1: start bit
+    #   # byte 2: single(1)/diff(0),3 bites for channel, null pad
+    #   # byte 3: don't care
+    #   spi = SPIDevice.new(:SPI0)
+    #   raw = spi.xfer([ 0b00000001, 0b10000000, 0].pack("C*"))
+    #   data = raw.unpack("C*")
+    #   val = ((data[1] & 0b00000011) << 8 ) | data[2]
     def xfer(tx_data, readbytes=0, speed=nil, delay=nil, bpw=nil)
       SPI::xfer(@spi, tx_data, readbytes, speed, delay, bpw)
     end
 
-    def disable
-      SPI::disable(@spi)
+    # Return the file descriptor to the open SPI device
+    def file
+      SPI::file(@spi)
     end
 
+    # Set the communication speed of the SPI device
+    #
+    # @param speed communication speed
     def set_speed(speed)
       SPI::set_speed(@spi, speed)
     end
 
+    # Set the communication speed of the SPI device
+    #
+    # @param mode should be a valid SPI mode, e.g. :SPI_MODE_0 through 3
     def set_mode(mode)
       SPI::set_mode(@spi, mode)
     end
 
+    # Set the bits per word of the SPI device
+    #
+    # @param bpw should specify the bits per word
     def set_bpw(bpw)
       SPI::set_bpw(@spi, bpw)
     end
 
+    # Disable the specified SPI device
+    #
+    # @note device trees cannot be unloaded at this time without kernel panic.
+    #
+    def disable
+      SPI::disable(@spi)
+    end
+
   end
 
 end

data/lib/beaglebone/uart.rb

@@ -1,16 +1,135 @@
-module Beaglebone
+# == uart.rb
+# This file contains UART methods
+module Beaglebone #:nodoc:
+  # == UART
+  # Procedural methods for UART control
+  # == Summary
+  # #setup is called to initialize a UART device
   module UART
+    # Valid UART speeds
     SPEEDS = [ 110, 300, 600, 1200, 2400, 4800, 9600, 14400, 19200, 28800, 38400, 56000, 57600, 115200 ]
+
     @uartstatus = {}
     @uartmutex = Mutex.new
 
     class << self
       attr_accessor :uartstatus, :uartmutex
 
+
+      # Initialize a UART device
+      #
+      # @param uart should be a symbol representing the UART device
+      # @param speed should be an integer thats a valid speed. @see SPEEDS
+      #
+      # @example
+      #   UART.setup(:UART1, 9600)
+      def setup(uart, speed=9600)
+        check_uart_valid(uart)
+        check_speed_valid(speed)
+
+        #make sure uart not already enabled
+        return if get_uart_status(uart)
+
+        uartinfo = UARTS[uart]
+
+        #ensure dtb is loaded
+        Beaglebone::device_tree_load("#{TREES[:UART][:pin]}#{uartinfo[:id]}")
+
+        #open the uart device
+        uart_fd = File.open(uartinfo[:dev], 'r+')
+
+        if uartinfo[:tx]
+          Beaglebone::set_pin_status(uartinfo[:tx], :uart, uartinfo[:id])
+          Beaglebone::set_pin_status(uartinfo[:tx], :type, :uart)
+          Beaglebone::set_pin_status(uartinfo[:tx], :fd_uart, uart_fd)
+        end
+
+        if uartinfo[:rx]
+          Beaglebone::set_pin_status(uartinfo[:rx], :uart, uartinfo[:id])
+          Beaglebone::set_pin_status(uartinfo[:tx], :type, :uart)
+          Beaglebone::set_pin_status(uartinfo[:rx], :fd_uart, uart_fd)
+        end
+
+        system("stty -F #{uartinfo[:dev]} raw")
+        system("stty -F #{uartinfo[:dev]} #{speed}")
+
+        set_uart_status(uart, :fd_uart, uart_fd)
+      end
+
+      # Set the speed of the UART
+      #
+      # @param speed should be an integer thats a valid speed. @see SPEEDS
+      #
+      # @example
+      #   UART.set_speed(:UART1, 9600)
+      def set_speed(uart, speed)
+        check_uart_valid(uart)
+        check_speed_valid(speed)
+
+        uartinfo = UARTS[uart]
+        system("stty -F #{uartinfo[:dev]} #{speed}")
+      end
+
+      # Write data to a UART device
+      #
+      # @param uart should be a symbol representing the UART device
+      # @param data the data to write
+      #
+      # @return Integer the number of bytes written
+      #
+      # @example
+      #   UART.write(:UART1, "1234") => 4
+      def write(uart, data)
+        check_uart_enabled(uart)
+
+        pin_tx = UARTS[uart][:tx]
+
+        Beaglebone::check_valid_pin(pin_tx, :uart)
+
+        fd = Beaglebone::get_pin_status(pin_tx, :fd_uart)
+
+        ret = fd.write(data)
+        fd.flush
+
+        ret
+      end
+
+      # Write a line data to a UART device.
+      # This is a convenience method using #write
+      # @see #write
+      #
+      # @param uart should be a symbol representing the UART device
+      # @param data the data to write
+      #
+      # @return Integer the number of bytes written
+      #
+      # @example
+      #   UART.writeln(:UART1, "1234") => 5
+      def writeln(uart, data)
+        write(uart, data + "\n")
+      end
+
+      # Read one character from a UART device
+      #
+      # @param uart should be a symbol representing the UART device
+      #
+      # @return String the character read from the UART device
+      #
+      # @example
+      #   UART.readchars(:UART1) => "x"
       def readchar(uart)
         readchars(uart, 1)
       end
 
+      # Read characters from a UART device
+      #
+      # @param uart should be a symbol representing the UART device
+      # @param bytes number of bytes to read
+      #
+      # @return String the characters read from the UART device
+      #
+      # @example
+      #   UART.readchars(:UART1, 2) => "xx"
       def readchars(uart, bytes)
         check_uart_enabled(uart)
         ensure_read_lock(uart)
@@ -34,6 +153,14 @@ module Beaglebone
         buffer
       end
 
+      # Read a line from a UART device
+      #
+      # @param uart should be a symbol representing the UART device
+      #
+      # @return String the line read from the UART device
+      #
+      # @example
+      #   UART.readline(:UART1) => "A line of text"
       def readline(uart)
         check_uart_enabled(uart)
         ensure_read_lock(uart)
@@ -53,6 +180,12 @@ module Beaglebone
         data
       end
 
+      # Read a character from a UART device and pass it to the specified block
+      #
+      # @param uart should be a symbol representing the UART device
+      #
+      # @example
+      #   UART.each_char(:UART1) { |x| puts "read: #{x}" }
       def each_char(uart)
         loop do
           data = readchars(uart, 1)
@@ -61,6 +194,13 @@ module Beaglebone
 
       end
 
+      # Read characters from a UART device and pass them to the specified block
+      #
+      # @param uart should be a symbol representing the UART device
+      # @param chars should be the number of chars to read
+      #
+      # @example
+      #   UART.each_chars(:UART1, 2) { |x| puts "read: #{x}" }
       def each_chars(uart, chars)
         loop do
           data = readchars(uart, chars)
@@ -68,6 +208,13 @@ module Beaglebone
         end
       end
 
+
+      # Read lines from a UART device and pass them to the specified block
+      #
+      # @param uart should be a symbol representing the UART device
+      #
+      # @example
+      #   UART.each_line(:UART1) { |x| puts "read: #{x}" }
       def each_line(uart)
         loop do
           data = readline(uart)
@@ -75,29 +222,16 @@ module Beaglebone
         end
       end
 
-      def writeln(uart, data)
-        write(uart, data + "\n")
-      end
-
-      def write(uart, data)
-        check_uart_enabled(uart)
-
-        pin_tx = UARTS[uart][:tx]
-
-        Beaglebone::check_valid_pin(pin_tx, :uart)
-
-        fd = Beaglebone::get_pin_status(pin_tx, :fd_uart)
-
-        ret = fd.write(data)
-        fd.flush
-
-        ret
-      end
-
-      def run_once_on_each_line(callback, uart)
-        run_on_each_line(callback, uart, 1)
-      end
-
+      # Runs a callback after receiving a line of data from a UART device
+      # This creates a new thread that runs in the background
+      #
+      # @param callback A method to call when the data is received.  This method should take 3 arguments, the UART, the line read, and the counter
+      # @param uart should be a symbol representing the UART device
+      # @param repeats is optional and specifies the number of times the callback will be run
+      #
+      # @example
+      #   callback = lambda { |uart, line, count| puts "[#{uart}:#{count}] #{line} "}
+      #   UART.run_on_each_line(callback, :UART1)
       def run_on_each_line(callback, uart, repeats=nil)
         check_uart_enabled(uart)
 
@@ -125,18 +259,23 @@ module Beaglebone
         set_uart_status(uart, :thread, thread)
       end
 
-      def run_once_on_each_char(callback, uart)
-        run_once_on_each_chars(callback, uart, 1)
-      end
-
-      def run_once_on_each_chars(callback, uart, chars=1)
-        run_on_each_chars(callback, uart, chars, 1)
-      end
-
-      def run_on_each_char(callback, uart, repeats=nil)
-        run_on_each_chars(callback, uart, 1, repeats)
+      # Convenience method for run_on_each_line with repeats set to 1
+      # @see #run_on_each_line
+      def run_once_on_each_line(callback, uart)
+        run_on_each_line(callback, uart, 1)
       end
 
+      # Runs a callback after receiving data from a UART device
+      # This creates a new thread that runs in the background
+      #
+      # @param callback A method to call when the data is received.  This method should take 3 arguments, the UART, the line read, and the counter
+      # @param uart should be a symbol representing the UART device
+      # @param chars should be the number of chars to read
+      # @param repeats is optional and specifies the number of times the callback will be run
+      #
+      # @example
+      #   callback = lambda { |uart, data, count| puts "[#{uart}:#{count}] #{data} "}
+      #   UART.run_on_each_chars(callback, :UART1, 2)
       def run_on_each_chars(callback, uart, chars=1, repeats=nil)
         check_uart_enabled(uart)
 
@@ -164,47 +303,32 @@ module Beaglebone
         set_uart_status(uart, :thread, thread)
       end
 
-      def set_speed(uart, speed)
-        check_uart_valid(uart)
-        check_speed_valid(speed)
-
-        uartinfo = UARTS[uart]
-        system("stty -F #{uartinfo[:dev]} #{speed}")
+      # Convenience method for run_on_each_chars with chars and repeats set to 1
+      # @see #run_on_each_chars
+      def run_once_on_each_char(callback, uart)
+        run_once_on_each_chars(callback, uart, 1)
       end
 
-      def setup(uart, speed=9600)
-        check_uart_valid(uart)
-        check_speed_valid(speed)
-
-        #make sure uart not already enabled
-        return if get_uart_status(uart)
-
-        uartinfo = UARTS[uart]
-
-        #ensure dtb is loaded
-        Beaglebone::device_tree_load("#{TREES[:UART][:pin]}#{uartinfo[:id]}")
-
-        #open the uart device
-        uart_fd = File.open(uartinfo[:dev], 'r+')
-
-        if uartinfo[:tx]
-          Beaglebone::set_pin_status(uartinfo[:tx], :uart, uartinfo[:id])
-          Beaglebone::set_pin_status(uartinfo[:tx], :type, :uart)
-          Beaglebone::set_pin_status(uartinfo[:tx], :fd_uart, uart_fd)
-        end
-
-        if uartinfo[:rx]
-          Beaglebone::set_pin_status(uartinfo[:rx], :uart, uartinfo[:id])
-          Beaglebone::set_pin_status(uartinfo[:tx], :type, :uart)
-          Beaglebone::set_pin_status(uartinfo[:rx], :fd_uart, uart_fd)
-        end
-
-        system("stty -F #{uartinfo[:dev]} raw")
-        system("stty -F #{uartinfo[:dev]} #{speed}")
+      # Convenience method for run_on_each_chars with chars and repeats set to 1
+      # @see #run_on_each_chars
+      def run_once_on_each_chars(callback, uart, chars=1)
+        run_on_each_chars(callback, uart, chars, 1)
+      end
 
-        set_uart_status(uart, :fd_uart, uart_fd)
+      # Convenience method for run_on_each_chars with chars set to 1
+      # @see #run_on_each_chars
+      def run_on_each_char(callback, uart, repeats=nil)
+        run_on_each_chars(callback, uart, 1, repeats)
       end
 
+      # Disable a UART device.
+      #
+      # @note device trees cannot be unloaded at this time without kernel panic.
+      #
+      # @param uart should be a symbol representing the UART device
+      #
+      # @example
+      #   UART.disable(:UART1)
       def disable(uart)
         check_uart_valid(uart)
         check_uart_enabled(uart)
@@ -217,7 +341,7 @@ module Beaglebone
         delete_uart_status(uart)
       end
 
-      #stop background read
+      # Stops any threads waiting for data on the specified UART
       def stop_read_wait(uart)
         thread = get_uart_status(uart, :thread)
 
@@ -225,6 +349,7 @@ module Beaglebone
         thread.join if thread
       end
 
+      # Disable all UART devices
       def cleanup
         #reset all UARTs we've used and unload the device tree
         uartstatus.clone.keys.each { |uart| disable(uart)}
@@ -232,6 +357,7 @@ module Beaglebone
 
       private
 
+      # return hash data for specified UART
       def get_uart_status(uart, key = nil)
         uartmutex.synchronize do
           if key
@@ -242,6 +368,7 @@ module Beaglebone
         end
       end
 
+      # set hash data for specified UART
       def set_uart_status(uart, key, value)
         uartmutex.synchronize do
           uartstatus[uart]    ||= {}
@@ -249,6 +376,7 @@ module Beaglebone
         end
       end
 
+      # remove hash data for specified UART
       def delete_uart_status(uart, key = nil)
         uartmutex.synchronize do
           if key.nil?
@@ -259,6 +387,7 @@ module Beaglebone
         end
       end
 
+      # ensure UART is valid
       def check_uart_valid(uart)
         raise ArgumentError, "Invalid UART Specified #{uart.to_s}" unless UARTS[uart]
         uartinfo = UARTS[uart.to_sym.upcase]
@@ -273,10 +402,12 @@ module Beaglebone
 
       end
 
+      # ensure UART is enabled
       def check_uart_enabled(uart)
         raise ArgumentError, "UART not enabled #{uart.to_s}" unless get_uart_status(uart)
       end
 
+      # ensure we have a read lock for the UART
       def ensure_read_lock(uart)
         #ensure we're the only ones reading
         if get_uart_status(uart, :thread) && get_uart_status(uart, :thread) != Thread.current
@@ -288,10 +419,12 @@ module Beaglebone
         end
       end
 
+      # check to make sure the specified speed is valid
       def check_speed_valid(speed)
         raise ArgumentError, "Invalid speed specified: #{speed}" unless SPEEDS.include?(speed)
       end
 
+      # disable a uart pin
       def disable_uart_pin(pin)
         Beaglebone::check_valid_pin(pin, :uart)
 
@@ -309,77 +442,174 @@ module Beaglebone
     end
   end
 
-  #oo interface
+  # Object Oriented UART Implementation.
+  # This treats the UART device as an object.
   class UARTDevice
+    # Initialize a UART device.  Returns a UARTDevice object
+    #
+    # @param uart should be a symbol representing the UART device
+    # @param speed should be an integer thats a valid speed. @see SPEEDS
+    #
+    # @example
+    #   uart1 = UARTDevice.new(:UART1, 9600)
     def initialize(uart, speed=9600)
       @uart = uart
       UART::setup(@uart, speed)
     end
 
+    # Set the speed of the UART
+    #
+    # @param speed should be an integer thats a valid speed. @see SPEEDS
+    #
+    # @example
+    #   uart1.set_speed(9600)
     def set_speed(speed)
       UART::set_speed(@uart, speed)
     end
 
+    # Write data to a UART device
+    #
+    # @param data the data to write
+    #
+    # @return Integer the number of bytes written
+    #
+    # @example
+    #   uart1.write("1234") => 4
     def write(data)
       UART::write(@uart, data)
     end
 
+    # Write a line data to a UART device.
+    # This is a convenience method using #write
+    # @see #write
+    #
+    # @param data the data to write
+    #
+    # @return Integer the number of bytes written
+    #
+    # @example
+    #   uart1.writeln("1234") => 5
     def writeln(data)
       UART::writeln(@uart, data)
     end
 
+    # Read one character from a UART device
+    #
+    # @return String the character read from the UART device
+    #
+    # @example
+    #   uart1.readchars => "x"
     def readchar
       UART::readchar(@uart)
     end
 
+    # Read characters from a UART device
+    #
+    # @param bytes number of bytes to read
+    #
+    # @return String the characters read from the UART device
+    #
+    # @example
+    #   uart1.readchars(2) => "xx"
     def readchars(bytes)
       UART::readchars(@uart, bytes)
     end
 
+    # Read a line from a UART device
+    #
+    # @return String the line read from the UART device
+    #
+    # @example
+    #   uart1.readline => "A line of text"
     def readline
       UART::readline(@uart)
     end
 
+    # Read a character from a UART device and pass it to the specified block
+    #
+    # @example
+    #   uart1.each_char { |x| puts "read: #{x}" }
     def each_char(&block)
       UART::each_char(@uart, &block)
     end
 
+    # Read characters from a UART device and pass them to the specified block
+    #
+    # @param chars should be the number of chars to read
+    #
+    # @example
+    #   uart1.each_chars(2) { |x| puts "read: #{x}" }
     def each_chars(chars, &block)
       UART::each_chars(@uart, chars, &block)
     end
 
+    # Read lines from a UART device and pass them to the specified block
+    #
+    # @example
+    #   uart1.each_line { |x| puts "read: #{x}" }
     def each_line(&block)
       UART::each_line(@uart, &block)
     end
 
+    # Runs a callback after receiving a line of data from a UART device
+    # This creates a new thread that runs in the background
+    #
+    # @param callback A method to call when the data is received.  This method should take 3 arguments, the UART, the line read, and the counter
+    # @param repeats is optional and specifies the number of times the callback will be run
+    #
+    # @example
+    #   callback = lambda { |uart, line, count| puts "[#{uart}:#{count}] #{line} "}
+    #   uart1.run_on_each_line(callback)
     def run_on_each_line(callback, repeats=nil)
       UART::run_on_each_line(callback, @uart, repeats)
     end
 
+    # Convenience method for run_on_each_line with repeats set to 1
+    # @see #run_on_each_line
     def run_once_on_each_line(callback)
       UART::run_once_on_each_line(callback, @uart)
     end
 
-    def run_on_each_char(callback, repeats=nil)
-      UART::run_on_each_char(callback, @uart, repeats)
+    # Runs a callback after receiving data from a UART device
+    # This creates a new thread that runs in the background
+    #
+    # @param callback A method to call when the data is received.  This method should take 3 arguments, the UART, the line read, and the counter
+    # @param chars should be the number of chars to read
+    # @param repeats is optional and specifies the number of times the callback will be run
+    #
+    # @example
+    #   callback = lambda { |uart, data, count| puts "[#{uart}:#{count}] #{data} "}
+    #   uart1.run_on_each_chars(callback, 2)
+    def run_on_each_chars(callback, chars=1, repeats=nil)
+      UART::run_on_each_chars(callback, @uart, chars, repeats)
     end
 
+    # Convenience method for run_on_each_chars with chars and repeats set to 1
+    # @see #run_on_each_chars
     def run_once_on_each_char(callback)
       UART::run_once_on_each_char(callback, @uart)
     end
 
-    def run_on_each_chars(callback, chars=1, repeats=nil)
-      UART::run_on_each_chars(callback, @uart, chars, repeats)
-    end
-
+    # Convenience method for run_on_each_chars with chars and repeats set to 1
+    # @see #run_on_each_chars
     def run_once_on_each_chars(callback, chars=1)
       UART::run_once_on_each_chars(callback, @uart, chars)
     end
 
+    # Convenience method for run_on_each_chars with chars set to 1
+    # @see #run_on_each_chars
+    def run_on_each_char(callback, repeats=nil)
+      UART::run_on_each_char(callback, @uart, repeats)
+    end
+
+    # Stops any threads waiting for data on the specified UART
     def stop_read_wait
       UART::stop_read_wait(@uart)
     end
 
+    # Disable a UART device.
+    #
+    # @note device trees cannot be unloaded at this time without kernel panic.
     def disable
       UART::disable(@uart)
     end