ropian 0.1.1 → 0.1.2.pre

data/.gitignore

@@ -0,0 +1,8 @@
+*.gem
+.bundle
+.yardoc
+Gemfile.lock
+pkg/*
+doc
+b
+vendor/bundle

data/.yardopts

@@ -0,0 +1,4 @@
+lib/**/*.rb
+--no-private
+--readme README.rdoc
+--files LICENSE

data/Gemfile

@@ -0,0 +1,4 @@
+source 'http://rubygems.org'
+
+# Specify your gem's dependencies in ropian.gemspec
+gemspec

data/README.rdoc

@@ -1,6 +1,13 @@
-= ropian
+= Ropian
 
-Description goes here.
+Ropian is a library of Networked Power Distribution Unit management utilities. The library currently provides
+support for collecting power usage stats and setting the power state of power sockets.
+
+== Supported Hardware
+This library currently supports the following vendors
+
+* APC
+* Raritan
 
 == Copyright
 

data/Rakefile

@@ -1,60 +1,12 @@
-require 'rubygems'
-require 'rake'
-require 'yaml'
+require 'bundler/gem_helper'
 
-begin
-  require 'jeweler'
-  Jeweler::Tasks.new do |gem|
-    gem.name = "ropian"
-    gem.summary = %Q{Suite of tools for working with network power units}
-    gem.email = "geoff@geoffgarside.co.uk"
-    gem.homepage = "http://github.com/geoffgarside/ropian"
-    gem.authors = ["Geoff Garside"]
-    gem.add_dependency('snmp', '>= 1.0.2')
-
-    gem.files.exclude 'doc/*.mib'
-
-    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
-  end
-rescue LoadError
-  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
-end
-
-require 'rake/testtask'
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib' << 'test'
-  test.pattern = 'test/**/*_test.rb'
-  test.verbose = true
-end
+Bundler::GemHelper.install_tasks
 
 begin
-  require 'rcov/rcovtask'
-  Rcov::RcovTask.new do |test|
-    test.libs << 'test'
-    test.pattern = 'test/**/*_test.rb'
-    test.verbose = true
-  end
+  require 'yard'
+  YARD::Rake::YardocTask.new
 rescue LoadError
-  task :rcov do
-    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
-  end
-end
-
-
-task :default => :test
-
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  if File.exist?('VERSION.yml')
-    config = YAML.load(File.read('VERSION.yml'))
-    version = "#{config[:major]}.#{config[:minor]}.#{config[:patch]}"
-  else
-    version = ""
+  task :yardoc do
+    abort "YARD is not available. In order to run yardoc you must: sudo gem install yard"
   end
-
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "ropian #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
 end
-

data/lib/ropian/control/apc.rb

@@ -1,12 +1,19 @@
 module Ropian
   module Control
+    # This class provides support for APC brand power devices.
     class APC < Generic
-      def base_oid
-        @base_oid ||= SNMP::ObjectId.new('1.3.6.1.4.1.318.1.1.12.3.3.1.1.4')
-      end
-      def state_order
-        @state_order ||= [nil, :on, :off, :reboot]
-      end
+      protected
+        # @return [SNMP::ObjectId] the SNMP base OID for power control
+        def base_oid
+          @base_oid ||= SNMP::ObjectId.new('1.3.6.1.4.1.318.1.1.12.3.3.1.1.4')
+        end
+
+        # APC power devices map the on, off and reboot states to 1, 2, and 3.
+        #
+        # @return [Array] array to map the states to the SNMP integer values.
+        def state_order
+          @state_order ||= [nil, :on, :off, :reboot]
+        end
     end
   end
 end

data/lib/ropian/control/generic.rb

@@ -1,32 +1,86 @@
 module Ropian
   module Control
+    # Generic base class for vendor specific subclasses.
+    #
+    # Provides the common API which subclasses will adhere to.
     class Generic
+
+      # Symbols for the types of supported power states which can
+      # be set on power device sockets.
       States = [:on, :off, :reboot]
+
+      # Provides inspection details for the current receiver.
+      #
+      # @return [String] inspection string
+      # @private
       def inspect
         "#<#{self.class} #{@manager.host}@#{@manager.community}>"
       end
+
+      # Creates and returns a new instance of a Ropian::Control::Generic class.
+      #
+      # @param [String] ip_addr The IP address of the power device.
+      # @param [String] community The SNMP write community string to
+      #                 be used when communicating with the device.
+      # @param [Symbol] version The SNMP version symbol specifying the
+      #                 version of SNMP to use when communicating with the device.
       def initialize(ip_addr, community, version = :SNMPv2c)
         @manager = SNMP::Manager.new(:Host => ip_addr,
           :Community => community, :Version => version)
       end
+
+      # Sets the power state of the specified port(s) to ON
+      #
+      # @param [#to_i, Array] port_index Port index or array of indexes to turn ON.
+      # @return [Boolean] success or failure of setting the ports to on.
       def turn_on(port_index)
         set_state(:on, port_index)
       end
+
+      # Sets the power state of the specified port(s) to OFF
+      #
+      # @param [#to_i, Array] port_index Port index or array of indexes to turn OFF
+      # @return [Boolean] success or failure of setting the ports to off.
       def turn_off(port_index)
         set_state(:off, port_index)
       end
+
+      # Power cycles the specified port(s) turning them OFF then ON.
+      #
+      # The delay between the OFF and the ON is usually configured on the
+      # device itself, it is usually in the region of 10 seconds.
+      #
+      # @param [#to_i, Array] port_index Port index or array of indexes to power cycle.
+      # @return [Boolean] success or failure of setting the ports to reboot.
       def reboot(port_index)
         set_state(:reboot, port_index)
       end
+
+      # Sets the given +state+ on the specified port(s).
+      #
+      # @param [Symbol] state The state to set the ports to.
+      # @param [#to_i, Array] port_index Port index or array of indexes to set the state on.
+      # @return [Boolean] success or failure of setting the specified +state+.
+      # @raise [ArgumentError] if the provided +state+ is not a member of States.
+      # @see States
       def set_state(state, port_index)
         raise ArgumentError, "invalid state" unless States.include?(state)
-        @manager.set(SNMP::VarBind.new(base_oid + port_index,
-                                        SNMP::Integer.new(state_order.index(state))))
+
+        varbindings = Array(port_index).map do |index|
+          SNMP::VarBind.new(base_oid + index,
+            SNMP::Integer.new(state_order.index(state)))
+        end
+
+        response = @manager.set(varbindings)
+        response.error_index == 0 # no error
       end
+
       protected
+        # @return [SNMP::ObjectId] SNMP Base OID for power control
         def base_oid
           raise NotImplementedError, "method must be overridden"
         end
+        # @return [Array] Array mapping the States to the corresponding SNMP integer value to set.
         def state_order
           States
         end

data/lib/ropian/control/raritan.rb

@@ -1,12 +1,19 @@
 module Ropian
   module Control
+    # This class provides support for Raritan brand power devices.
     class Raritan < Generic
-      def base_oid
-        @base_oid ||= SNMP::ObjectId.new('1.3.6.1.4.1.13742.4.1.2.2.1.3')
-      end
-      def state_order
-        @state_order ||= [:off, :on, :reboot]
-      end
+      protected
+        # @return [SNMP::ObjectId] the SNMP base OID for power control
+        def base_oid
+          @base_oid ||= SNMP::ObjectId.new('1.3.6.1.4.1.13742.4.1.2.2.1.3')
+        end
+
+        # Raritan power devices map the on, off and reboot states to 1, 0, and 2.
+        #
+        # @return [Array] array to map the states to the SNMP integer values.
+        def state_order
+          @state_order ||= [:off, :on, :reboot]
+        end
     end
   end
 end

data/lib/ropian/meter/apc.rb

@@ -1,21 +1,19 @@
 module Ropian
   module Meter
+    # This class provides support for APC brand power devices.
     class APC < Generic
-      UnitCurrent = SNMP::ObjectId.new('1.3.6.1.4.1.318.1.1.12.2.3.1.1.2.1')
-
-      def collect # :yields: total_amps, hash_of_outlet_amps
-        yield total_amps, {}
-      end
-      # Amps in total on whole bar
-      def total_amps
-        amps_for_oid(UnitCurrent)
-      end
-      def outlet_amps(outlet_index)
-        raise NotImplementedError, "APC Power Bars do not support per outlet power stats"
-      end
       protected
-        def amps_for_oid(oid)
-          @manager.get(oid).varbind_list.first.value.to_f / 10
+        # If the vendor returns current in values in milli-amps for example
+        # this method can be overridden to return 1000.
+        #
+        # @return [Numeric] Amps scaling factor.
+        def amps_scale_factor
+          10
+        end
+
+        # @return [SNMP::ObjectId] SNMP OID where the unit current can be retrieved
+        def unit_current_oid
+          @unit_current_oid ||= SNMP::ObjectId.new('1.3.6.1.4.1.318.1.1.12.2.3.1.1.2.1')
         end
     end
   end

data/lib/ropian/meter/generic.rb

@@ -1,16 +1,93 @@
 module Ropian
   module Meter
+    # Generic base class for vendor specific subclasses.
+    #
+    # Provides the common API which subclasses will adhere to.
     class Generic
+      # Provides inspection details for the current receiver.
+      #
+      # @return [String] inspection string
+      # @private
       def inspect
         "#<#{self.class} #{@manager.host}@#{@manager.community}>"
       end
+
+      # Creates and returns a new instance of Ropian::Meter::Generic.
+      #
+      # @param [String] ip_addr The IP address of the power device.
+      # @param [String] community The SNMP write community string to
+      #                 be used when communicating with the device.
+      # @param [Symbol] version The SNMP version symbol specifying the
+      #                 version of SNMP to use when communicating with the device.
       def initialize(ip_addr, community, version = :SNMPv2c)
         @manager = SNMP::Manager.new(:Host => ip_addr,
           :Community => community, :Version => version)
       end
+
+      # Collects and yields the unit current and outlet currents to the given block
+      #
+      # @yield [total_amps, outlet_amps]
+      # @yieldparam [Float] total_amps Total unit current in Amps
+      # @yieldparam [Hash<Integer,Float>] outlet_amps Hash of the power outlet Amps, may be empty if unsupported
+      def collect
+        yield total_amps, all_outlet_amps
+      end
+
+      # Returns the total number of amps for the receiver
+      # @return [Float] total current usage of the receiver in amps
+      def total_amps
+        amps_for_oid(unit_current_oid)
+      end
+
+      # Returns the current of the given +outlet+ in amps.
+      # @param [#to_i] outlet Outlet number
+      # @return [Float] outlet current usage in amps.
+      def outlet_amps(outlet)
+        amps_for_oid(outlet_current_base_oid + outlet.to_i)
+      end
+
       protected
+        # If the vendor returns current in values in milli-amps for example
+        # this method can be overridden to return 1000.
+        #
+        # @return [Numeric] Amps scaling factor.
+        def amps_scale_factor
+          1
+        end
+
+        # @param [SNMP::ObjectId] oid
+        # @return [Float] number of Amps for specified +oid+.
         def amps_for_oid(oid)
-          @manager.get(oid).varbind_list.first.value.to_f / 1000
+          @manager.get(oid).varbind_list.first.value.to_f / amps_scale_factor
+        end
+
+        # @return [SNMP::ObjectId] SNMP OID where the unit current can be retrieved
+        def unit_current_oid
+          raise NotImplementedError, "must be overridden by subclasses"
+        end
+
+        # @return [SNMP::ObjectId] Base SNMP OID where the outlet current can be retrieved
+        def outlet_current_base_oid
+          raise NotImplementedError, "must be overridden by subclasses"
+        end
+
+        # Returns a hash of the current for each outlet in amps.
+        # @return [Hash<Integer,Float>] Hash of the outlet numbers and their current in amps.
+        def all_outlet_amps
+          results = {}
+
+          begin
+            @manager.walk(outlet_current_base_oid) do |r|
+              r.each do |varbind|
+                results[varbind.name.index(outlet_current_base_oid)] = varbind.value.to_f / amps_scale_factor
+              end
+            end
+          rescue NotImplementedError
+            # catch from outlet_current_base_oid if not supported in subclass
+            # we don't interfere with the results and return the empty hash.
+          end
+
+          results
         end
     end
   end

data/lib/ropian/meter/raritan.rb

@@ -1,28 +1,25 @@
 module Ropian
   module Meter
+    # This class provides support for Raritan brand power devices.
     class Raritan < Generic
-      UnitCurrent = SNMP::ObjectId.new("1.3.6.1.4.1.13742.4.1.4.2.1.3.1")
-      OutletCurrent = SNMP::ObjectId.new("1.3.6.1.4.1.13742.4.1.2.2.1.4")
-
-      def collect # :yields: total_amps, hash_of_outlet_amps
-        results = Hash.new
+      protected
+        # If the vendor returns current in values in milli-amps for example
+        # this method can be overridden to return 1000.
+        #
+        # @return [Numeric] Amps scaling factor.
+        def amps_scale_factor
+          1000
+        end
 
-        @manager.walk(OutletCurrent) do |r|
-          r.each do |varbind|
-            results[varbind.name.index(OutletCurrent)] = varbind.value.to_f / 1000
-          end
+        # @return [SNMP::ObjectId] SNMP OID where the unit current can be retrieved
+        def unit_current_oid
+          @unit_current_oid ||= SNMP::ObjectId.new("1.3.6.1.4.1.13742.4.1.4.2.1.3.1")
         end
 
-        yield total_amps, results
-      end
-      # Amps in total on whole bar
-      def total_amps
-        amps_for_oid(UnitCurrent)
-      end
-      # Amps per outlet
-      def outlet_amps(outlet_index)
-        amps_for_oid(OutletCurrent + outlet_index)
-      end
+        # @return [SNMP::ObjectId] Base SNMP OID where the outlet current can be retrieved
+        def outlet_current_base_oid
+          @outlet_current_base_oid ||= SNMP::ObjectId.new("1.3.6.1.4.1.13742.4.1.2.2.1.4")
+        end
     end
   end
 end

data/lib/ropian.rb

@@ -1,33 +1,46 @@
 require 'snmp'
 
-require 'ropian/control/generic'
-require 'ropian/control/raritan'
-require 'ropian/control/apc'
-
-require 'ropian/meter/generic'
-require 'ropian/meter/raritan'
-require 'ropian/meter/apc'
-
-# :stopdoc:
+# Extension to provides read access to :host, :community and :version
+# instance variables.
+#
+# We've done this primarily for #inspect cases.
+#
+# @private
 class SNMP::Manager
   attr_reader :host, :community, :version
 end
+
+# Extension to provides additive properties to SNMP::ObjectId instances.
+#
+# @private
 class SNMP::ObjectId
+  # Adds the provided suboid or array of suboids to the
+  # receiver an returns a new instance.
+  #
+  # @param [#to_i,Array] suboid or array of suboids to append to the receiver.
+  # @return [SNMP::ObjectId] new OID with the +val+ appended to the receivers suboids.
   def +(val)
     current = self.to_a
-    unless val.kind_of?(Array)
-      current << val.to_i
-      return self.class.new(current)
-    else
-      return self.class.new(current + val.to_a)
-    end
+    val = [val.to_i] unless val.kind_of?(Array)
+    return self.class.new(current + val)
   end
 end
-# :startdoc:
 
-module Ropian # :nodoc:
-  module Control # :nodoc:
+# Ropian is a collection of modules and classes for working with SNMP power devices.
+module Ropian
+  # The control module classes provide functionality for managing the power state of
+  # sockets on the power devices. Turning sockets on, off or rebooting for example.
+  module Control
+    autoload :Generic,  File.expand_path('../ropian/control/generic', __FILE__)
+    autoload :APC,      File.expand_path('../ropian/control/apc', __FILE__)
+    autoload :Raritan,  File.expand_path('../ropian/control/raritan', __FILE__)
   end
-  module Meter # :nodoc:
+
+  # The meter module classes provide functionality for collecting power usage information
+  # from power devices. They support per socket power usage stats where hardware support is present.
+  module Meter
+    autoload :Generic,  File.expand_path('../ropian/meter/generic', __FILE__)
+    autoload :APC,      File.expand_path('../ropian/meter/apc', __FILE__)
+    autoload :Raritan,  File.expand_path('../ropian/meter/raritan', __FILE__)
   end
 end

data/ropian.gemspec

@@ -1,55 +1,21 @@
 # -*- encoding: utf-8 -*-
+$:.push File.expand_path("../lib", __FILE__)
 
 Gem::Specification.new do |s|
-  s.name = %q{ropian}
-  s.version = "0.1.1"
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.name = "ropian"
+  s.version = "0.1.2.pre"
   s.authors = ["Geoff Garside"]
-  s.date = %q{2009-06-11}
-  s.email = %q{geoff@geoffgarside.co.uk}
-  s.extra_rdoc_files = [
-    "LICENSE",
-     "README.rdoc"
-  ]
-  s.files = [
-    ".document",
-     ".gitignore",
-     "LICENSE",
-     "README.rdoc",
-     "Rakefile",
-     "VERSION.yml",
-     "lib/ropian.rb",
-     "lib/ropian/control/apc.rb",
-     "lib/ropian/control/generic.rb",
-     "lib/ropian/control/raritan.rb",
-     "lib/ropian/meter/apc.rb",
-     "lib/ropian/meter/generic.rb",
-     "lib/ropian/meter/raritan.rb",
-     "ropian.gemspec",
-     "test/ropian_test.rb",
-     "test/test_helper.rb"
-  ]
-  s.homepage = %q{http://github.com/geoffgarside/ropian}
-  s.rdoc_options = ["--charset=UTF-8"]
-  s.require_paths = ["lib"]
-  s.rubygems_version = %q{1.3.4}
-  s.summary = %q{Suite of tools for working with network power units}
-  s.test_files = [
-    "test/ropian_test.rb",
-     "test/test_helper.rb"
-  ]
+  s.email = ["geoff@geoffgarside.co.uk"]
+  s.homepage = "http://github.com/geoffgarside/ropian"
+  s.summary = "Suite of tools for working with network power distribution units"
+  s.description = "Provides metering and control of network power distribution units"
+
+  s.required_rubygems_version = ">= 1.3.6"
 
-  if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
-    s.specification_version = 3
+  s.add_dependency "snmp", ">= 1.0.2"
+
+  s.files = `git ls-files`.split("\n") - %w(doc/apc.mib doc/raritan.mib)
+  s.require_paths = ["lib"]
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<snmp>, [">= 1.0.2"])
-    else
-      s.add_dependency(%q<snmp>, [">= 1.0.2"])
-    end
-  else
-    s.add_dependency(%q<snmp>, [">= 1.0.2"])
-  end
+  s.add_development_dependency "yard"
 end

metadata

@@ -1,53 +1,61 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: ropian
-version: !ruby/object:Gem::Version 
-  hash: 25
-  prerelease: 
-  segments: 
-  - 0
-  - 1
-  - 1
-  version: 0.1.1
+version: !ruby/object:Gem::Version
+  version: 0.1.2.pre
+  prerelease: 6
 platform: ruby
-authors: 
+authors:
 - Geoff Garside
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2011-06-02 00:00:00 Z
-dependencies: 
-- !ruby/object:Gem::Dependency 
+date: 2012-04-30 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: snmp
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  requirement: !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 19
-        segments: 
-        - 1
-        - 0
-        - 2
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
         version: 1.0.2
   type: :runtime
-  version_requirements: *id001
-description: 
-email: geoff@geoffgarside.co.uk
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: 1.0.2
+- !ruby/object:Gem::Dependency
+  name: yard
+  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: Provides metering and control of network power distribution units
+email:
+- geoff@geoffgarside.co.uk
 executables: []
-
 extensions: []
-
-extra_rdoc_files: 
-- LICENSE
-- README.rdoc
-files: 
-- .document
+extra_rdoc_files: []
+files:
+- .gitignore
+- .yardopts
+- Gemfile
 - LICENSE
 - README.rdoc
 - Rakefile
-- VERSION.yml
 - lib/ropian.rb
 - lib/ropian/control/apc.rb
 - lib/ropian/control/generic.rb
@@ -60,36 +68,30 @@ files:
 - test/test_helper.rb
 homepage: http://github.com/geoffgarside/ropian
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: 2435443475953317457
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.3.6
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.8.4
+rubygems_version: 1.8.23
 signing_key: 
 specification_version: 3
-summary: Suite of tools for working with network power units
+summary: Suite of tools for working with network power distribution units
 test_files: []
-
+has_rdoc: 

data/.document

@@ -1,5 +0,0 @@
-README.rdoc
-lib/**/*.rb
-bin/*
-features/**/*.feature
-LICENSE

data/VERSION.yml

@@ -1,4 +0,0 @@
---- 
-:major: 0
-:minor: 1
-:patch: 1