BBB 0.0.10 → 0.1.0

data/lib/BBB/pins/analog_pin.rb

@@ -0,0 +1,39 @@
+module BBB
+  module Pins
+    ##
+    # A pin that reads from the ADC converteds on the board. On the Beaglebone
+    # this is AIN1 to 7. The class itself doesn't do much, since most of the
+    # basic functionality is provided by the pinnable module which is included,
+    # as well as the IO::AIN object used for IO to the filesystem
+    #
+    class AnalogPin
+      include Pinnable
+
+      ##
+      # Read from the Pin
+      #
+      # @return Integer
+      #
+      def read
+        io.read
+      end
+
+      ##
+      # Return the scale of the Pin. On the BeagleBoneBlack 12 bit pins this is
+      # 4096.
+      #
+      # @return Integer
+      #
+      def scale
+        @scale ||= io.scale
+      end
+
+      private
+
+      def default_io
+        IO::AIN.new(position)
+      end
+
+    end
+  end
+end

data/lib/BBB/pins/digital_pin.rb

@@ -0,0 +1,106 @@
+module BBB
+  module Pins
+    ##
+    # A Digital Pin on the board. The digital pins uses GPIO on the filesystem
+    # to communicate. This class assumes its the only actor on the pin. Therfore
+    # it can cache the status in memory instead of reading it from the
+    # filesystem every time.
+    #
+    # It is advised to use the DigitalInputPin and DigitalOutputPin classes for
+    # clarity, buy, nothings stops you from using a DigitalPin with the :input
+    # or :output direction.
+    #
+    class DigitalPin
+      include Pinnable
+
+      attr_reader :status, :opts
+
+      ##
+      # Gets the direction of the pin from the options and memoizes it in the
+      # @direction attribute.
+      #
+      # @return [Symbol] either :input or :output
+      def direction
+        @direction ||= @opts.fetch(:direction)
+      end
+
+      ##
+      # Write value to the specified pin Digitally. This might fail hard if you
+      # try to write to an input pin. However, for performance reasons we do not
+      # want to check the direction of the pin every write.
+      #
+      def write(value)
+        @status = value
+        io.write(value)
+      end
+
+      ##
+      # Read value from the pin for input pins, or from memory for output pins.
+      #
+      # @return [Symbol] :high or :low
+      #
+      def status
+        if direction == :input
+          @status = io.read
+        end
+
+        return @status
+      end
+
+      ##
+      # Set the pin into :high state
+      # @return [void]
+      def on!
+        write(:high)
+      end
+
+      ##
+      # Set the pin into :low state
+      # @return [void]
+      def off!
+        write(:low)
+      end
+
+      ##
+      # Check if the pin state is high
+      # @return [Boolean]
+      def on?
+        status == :high
+      end
+
+      ##
+      # Check if the pin state is low
+      # @return [Boolean]
+      def off?
+        !on?
+      end
+
+      private
+
+      def default_io
+        IO::GPIO.new(direction, position)
+      end
+    end
+
+    ##
+    # @see DigitalPin
+    #
+    class DigitalInputPin < DigitalPin
+      def initialize(position, opts={})
+        opts.merge!(:direction=>:input)
+        super(position, opts)
+      end
+    end
+
+    ##
+    # @see DigitalPin
+    #
+    class DigitalOutputPin < DigitalPin
+      def initialize(position, opts={})
+        opts.merge!(:direction=>:output)
+        super(position, opts)
+      end
+    end
+
+  end
+end

data/lib/BBB/pins/io/ain.rb

@@ -0,0 +1,58 @@
+module BBB
+  module Pins
+    module IO
+      class AIN
+        include Mapped
+
+        attr_reader :io, :position
+
+        def initialize(position)
+          @position = position
+          self.export
+          @io = get_file_handle
+        end
+
+        def read
+          io.rewind
+          io.read.to_i
+        end
+
+        def scale
+          pin_map.scale
+        end
+
+        def export
+          cape_dir = "/sys/devices/bone_capemgr.*/slots"
+          dir = Dir.glob(cape_dir)
+          if dir.length == 0
+            raise BoardError, "unable to access the capemgr directory: #{cape_dir}"
+          end
+          `echo cape-bone-iio > #{dir.first}`
+        end
+
+        def get_file_handle
+          dir  = Dir.glob("/sys/devices/ocp.*/helper.*/")
+          file = File.expand_path("AIN#{pin_map.ain}", dir.first)
+          return File.open(file, "r")
+        end
+
+        def self.setup
+          check_if_kernel_module_is_loaded!
+        end
+
+        def self.check_if_kernel_module_is_loaded!
+          ains = `find /sys/ -name '*AIN*'`.split("\n")
+
+          if ains.size > 0
+            return true
+          else
+            raise ModuleNotLoadedException, "Is seems that the ADC module is not
+              loaded into the kernel. You might want to try: \n
+              sudo modprobe t1_tscadc or add it to the kernel on boot: \n
+              echo 't1_tscadc' >> /etc/modules.conf"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/BBB/pins/io/gpio.rb

@@ -0,0 +1,77 @@
+module BBB
+  module Pins
+    module IO
+      class GPIO
+        include Mapped
+
+        attr_reader :file_mode, :converted_position, :position, :direction
+
+        def initialize(direction, position)
+          self.direction = direction
+          @position = position
+          @converted_position = pin_map.gpio
+          self.export
+        end
+
+        def direction=(direction)
+          @file_mode = direction == :input ? "r" : "w+"
+          @direction = direction
+        end
+
+        def set_mode
+          direction_file = gpio_pin_dir + "/direction"
+          file_class.open(direction_file, "w") {|f| f.write(direction)}
+        end
+
+        def io
+          return @io unless @io.nil?
+          value_file = gpio_pin_dir + "/value"
+          @io = file_class.open(value_file, file_mode)
+        end
+
+        def write(value)
+          io.write(value_map[value])
+          io.flush
+        end
+
+        def read
+          io.rewind
+          value_map[io.read]
+        end
+
+        def value_map
+          @value_map ||= {:high=>1, :low=>0, 1=>:high, 0=>:low}
+        end
+
+        def gpio_path
+          "/sys/class/gpio"
+        end
+
+        def export_path
+          gpio_path + "/export"
+        end
+
+        def unexport_path
+          gpio_path + "/unexport"
+        end
+
+        def gpio_pin_dir
+          "#{gpio_path}/gpio#{converted_position}"
+        end
+
+        def export
+          file_class.open(export_path, "w") { |f| f.write("#{ converted_position }") }
+          set_mode
+        end
+
+        def unexport
+          file_class.open(unexport_path, "w") { |f| f.write("#{converted_position}") }
+        end
+
+        def file_class
+          File
+        end
+      end
+    end
+  end
+end

data/lib/BBB/pins/io/mapped.rb

@@ -0,0 +1,39 @@
+module BBB
+  module Pins
+    module IO
+      module Mapped
+        ##
+        # Get the pin map as taken from the Bonescript. The Pinmap contains
+        # information on things like the pin mode, and the name of the pin on
+        # the filesystem. Checkout the documentation on {BBB::Pins::IO::PinMapper PinMapper} for more
+        # information and examples of the maps.
+        #
+        # @return [Hash] pin_map
+        #
+        def pin_map
+          return @pin_map unless @pin_map.nil?
+
+          map = PinMapper.map(self.position)
+          map_key = self.pin_map_key
+
+          unless map.respond_to?(map_key) && !map.send(map_key).nil?
+            raise ArgumentError, "#{self.position} is not a valid #{map_key.upcase} pin position"
+          end
+
+          @pin_map = map
+        end
+
+        ##
+        # Returns the map key of the current pin. e.g. GPIO or AIN. This key is
+        # used to check if the provided position actually can be used using the
+        # given IO.
+        #
+        # @return [Symbol] Map key
+        #
+        def pin_map_key
+          self.class.to_s.split("::").last.downcase.to_sym
+        end
+      end
+    end
+  end
+end

data/lib/BBB/pins/io/pin_mapper.rb

@@ -0,0 +1,224 @@
+module BBB
+  module Pins
+    module IO
+      ##
+      # This class provides a convenient way of mapping a JSON representation of the
+      # pins, taken from the bonescript sourcecode, into Ruby objects. After
+      # converting the json to ruby objects the "normal" PinMapper will take the
+      # object structure and provide the actual mapping from the pin header
+      # positions, like p8_3 to the correct GPIO, I2C or WPM endpoints.
+      #
+      # This class should not be used directly to provide these mappings it's simply
+      # a helper class to get from JSON to Ruby.
+      #
+      class PinMapper
+        PIN_MAP_FILE = File.expand_path("../../../../../resources/pin_mappings.json", __FILE__)
+
+        class PinMap < Struct.new(:pins, :uart, :i2c); end
+
+        class Pin    < Struct.new(:name, :gpio, :led, :mux, :key, :mux_reg_offset,
+                                  :options, :eeprom, :pwm, :ain, :scale); end
+        class UART   < Struct.new(:devicetree, :rx, :tx); end
+        class I2C    < Struct.new(:devicetree, :path, :sda, :scl); end
+
+        attr_reader :data
+
+        ##
+        # Initialize a JSONPinMapper
+        #
+        # @param [Hash] hash Hash that was converted from json with the keys
+        #   pinIndex, uart and i2c.
+        #
+        def initialize(hash)
+          @data = hash
+        end
+
+        ##
+        # Factor a new JSONPinMapper based on a json_file that get's parsed to a
+        # hash.
+        #
+        # @param [String] json_filename The file that contains the JSON object with
+        #   pin information
+        #
+        # @return JSONPinMapper instance
+        #
+        def self.convert(json_filename)
+          file = File.open(json_filename, "r")
+          hash = JSON.parse(file.read)
+          new(hash).convert
+        end
+
+        ##
+        # Map a pin symbol and a type to a pin_map or raise an error when a pin
+        # can't be found.
+        #
+        # @param [Symbol] pin_symbol
+        # @params [Symbol] type Type of the pin.
+        #
+        def self.map(pin_symbol)
+          @map ||= convert(PIN_MAP_FILE)
+          begin
+            @map.pins.fetch(pin_symbol.upcase.to_sym)
+          rescue Exception => e
+            raise UnknownPinException, "Pin #{pin_symbol} could not be mapped"
+          end
+        end
+
+        ##
+        # Convert from a the data hash to ruby objects
+        #
+        # @return [Struct] with pins, uart and i2c as keys.
+        #   pins has a
+        #
+        def convert
+          pins = convert_pins(data["pinIndex"])
+          uart = convert_uart(data["uarts"])
+          i2c  = convert_i2c(data["i2c"])
+
+          PinMap.new(pins, uart, i2c)
+        end
+
+        ##
+        # Converts an array of pins into a hash with the pin key as a key and a Pin
+        #   Struct as a value.
+        #
+        # Here is an example of a piece of the JSON code containing pin info:
+        #
+        # {
+        #     "name": "USR0",
+        #     "gpio": 53,
+        #     "led": "usr0",
+        #     "mux": "gpmc_a5",
+        #     "key": "USR0",
+        #     "muxRegOffset": "0x054",
+        #     "options": [
+        #         "gpmc_a5",
+        #         "gmii2_txd0",
+        #         "rgmii2_td0",
+        #         "rmii2_txd0",
+        #         "gpmc_a21",
+        #         "pr1_mii1_rxd3",
+        #         "eqep1b_in",
+        #         "gpio1_21"
+        #     ]
+        # }
+        #
+        # @param [Array<Hash>] array An array of Pin hashes
+        #
+        # @return [Hash] a hash with pin keys as keys and pin objects as values.
+        #
+        def convert_pins(array)
+          hash = {}
+
+          array.each do |pin_hash|
+            pin = Pin.new
+            pin_hash.each_pair do |key, value|
+              pin[underscore(key).to_sym] = value
+            end
+            hash[pin.key.upcase.to_sym] = pin
+          end
+
+          return hash
+        end
+
+        ##
+        # Convert a hash of uarts to a hash with the uart folder (e.g. /dev/tty00)
+        #   as the key and an uart object as the value.
+        #
+        # Here is an example of an individual UART hash:
+        #
+        #  "/dev/ttyO1": {
+        #      "devicetree": "BB-UART1",
+        #      "rx": "P9_26",
+        #      "tx": "P9_24"
+        #  }
+        #
+        # @param [Hash] data_hash with strings as keys and hashes as values
+        #
+        # @return [Hash] with strings of uart positions (e.g. /dev/tty00) as keys
+        #   and uart objects as values
+        #
+        def convert_uart(data_hash)
+          convert_hash_with_hashes(data_hash, UART)
+        end
+
+        ##
+        # Convert a hash of I2Cs to a hash with the I2C folder as the key and a i2c
+        #   object as the value
+        #
+        # Here is an example of an individual I2C hash:
+        #
+        #  "/dev/i2c-1": {
+        #      "devicetree": "BB-I2C1",
+        #      "path": "/dev/i2c-2",
+        #      "sda": "P9_18",
+        #      "scl": "P9_17"
+        #  }
+        #
+        # @param [Hash] data_hash with strings as keys and hashes as values
+        #
+        # @return [Hash] with strings of I2C folders as keys and I2C objects as
+        #   values
+        #
+        def convert_i2c(data_hash)
+          convert_hash_with_hashes(data_hash, I2C)
+        end
+
+        private
+
+        ##
+        # @see #convert_uart
+        #
+        def convert_hash_with_hashes(data_hash, object)
+          hash = {}
+
+          data_hash.each_pair do |filesystem, info_hash|
+            instance = object.new
+            info_hash.each_pair do |key, value|
+              instance[key] = value
+            end
+
+            hash[filesystem] = instance
+          end
+
+          return hash
+        end
+
+        ##
+        # Makes an underscored, lowercase form from the expression in the string.
+        #
+        # Gracefully copied from ActiveSupport::Inflections
+        # http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-underscore
+        #
+        # Changes '::' to '/' to convert namespaces to paths.
+        #
+        #   'ActiveModel'.underscore         # => "active_model"
+        #   'ActiveModel::Errors'.underscore # => "active_model/errors"
+        #
+        # As a rule of thumb you can think of +underscore+ as the inverse of
+        # +camelize+, though there are cases where that does not hold:
+        #
+        #   'SSLError'.underscore.camelize # => "SslError"
+        def underscore(camel_cased_word)
+          word = camel_cased_word.to_s.dup
+          word.gsub!('::', '/')
+          word.gsub!(/(?:([A-Za-z\d])|^)(#{acronym_regex})(?=\b|[^a-z])/) { "#{$1}#{$1 && '_'}#{$2.downcase}" }
+          word.gsub!(/([A-Z\d]+)([A-Z][a-z])/,'\1_\2')
+          word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+          word.tr!("-", "_")
+          word.downcase!
+          word
+        end
+
+        ##
+        # Specifies acronyms. This is a shortcut approach to the full acronym
+        # functionality of Rails. Which can be found here:
+        # https://github.com/rails/rails/blob/4e327225947b933d5434509e02e98226c581adc1/activesupport/lib/active_support/inflector/inflections.rb#L47
+        #
+        def acronym_regex
+          /#{%w(I2C UART GPIO).join("|")}/
+        end
+      end
+    end
+  end
+end