lmsensors 0.1.0

data/lib/lmsensors/lm_constants.rb

@@ -0,0 +1,193 @@
+# lib/lmsensors/lm_constants.rb
+
+# Require the base implementation
+require_relative "../lmsensors_base/lmsensors_base"
+
+# :nodoc: Constants for the LmSensors module
+module LmSensors
+  ##
+  # The default feature map method maps the feature 
+  # type to the subclass that will be used to handle
+  # formatting and analytic post-processing.
+  DEF_FMAP = lambda do |name, f_obj|
+    case f_obj[:type]
+    when SF_IN
+      Feature::Voltage.new name, f_obj
+    when SF_CURR
+      Feature::Current.new name, f_obj
+    when SF_POWER
+      Feature::Power.new name, f_obj
+    when SF_TEMP
+      Feature::Temp.new name, f_obj
+    when SF_FAN
+      Feature::Fan.new name, f_obj
+    when SF_HUMIDITY
+      Feature::Humidity.new name, f_obj
+    when SF_INTRUSION
+      Feature::Alarm.new name, f_obj
+    when SF_BEEP_ENABLE
+      Feature::Beep.new name, f_obj
+    else
+      Feature::GenFeature.new name, f_obj
+    end
+  end # End default feature mapper
+  
+  ##
+  # CHK_BEEP uses the same formatting as the print_chip_beep_enable
+  # from the sensors program chips.c.
+  CHK_BEEP = lambda { |v| v < 0.5 ? "disabled" : "enabled" }
+  
+  ##
+  # CHK_ALARM uses the same formatting as the print_chip_intrusion
+  # from the sensors program chips.c.
+  CHK_ALARM = lambda { |v| v.zero? ? "OK" : "ALARM" }
+  
+  ##
+  # Index of units -- this will map the expected
+  # default units to any features. These are taken from
+  # the 'lm-sensors' headers, and I have exported the
+  # constants from the C-code to here. The names DIRECTLY
+  # correspond to the 'sensors_feature_type' enum, but
+  # they have been shortened from 'SENSORS_FEATURE_'
+  # to 'SF_'.
+  # 
+  # This is, to the best of my ability, taken from the
+  # chips.c file, which has a header you can't seem to
+  # access from sensors.h.
+  UNITS = {
+    SF_IN => "V", # Volts
+    SF_FAN => "RPM", # RPM (fan)
+    SF_TEMP => "°C", # Degrees Celsius
+    SF_POWER => "W", # Watts
+    SF_ENERGY => "J", # Energy, Joules
+    SF_CURR => "A", # Current, Amps
+    SF_HUMIDITY => "% RH", # Humidity, percent
+    SF_MAX_MAIN => "",
+    # Skips here
+    SF_VID => "V", # Vid -- this is in Volts
+    SF_INTRUSION => CHK_ALARM, # Intrusion
+    SF_MAX_OTHER => "",
+    # Skips here, again
+    SF_BEEP_ENABLE => CHK_BEEP, # Beep enabled, true if gte 0.5
+    SF_MAX => "",
+    SF_UNKNOWN => "",
+  } # End default units enum
+  
+  ##
+  # This hash maps commonly-used limit types from
+  # the SENSORS_SUBFEATURE_* constants.
+  # 
+  # I have not included ALL the subfeatures types,
+  # because there are around 100 of them, and most of
+  # them provide no post-processing value. I have, however,
+  # included the following subfeature groups for
+  # the _POWER_, _IN_, _CURR_, and _FAN_ categories:
+  # 
+  # MIN, MAX, a couple HYST (hysteresis) types, INPUT,
+  # and a couple AVERAGE types.
+  # 
+  # NOTE: For the MOST part, the below list is provided
+  # for convenience, only. You can use it to create your
+  # own mappers, if you are not sure what subtypes are
+  # included in the normal feature objects.
+  # 
+  # I had actually considered removing everything below,
+  # but I realized that simply swapping the keys with the
+  # values actually provides a simpler way for others to
+  # access the types and provide some default key types
+  # they might want to use in their subclasses, even if it's 
+  # somewhat redundant.
+  SSF_SUBTYPES = {
+    # Voltages
+    SF_IN => {
+      # Inputs
+      SSF_IN_INPUT => :input,
+      
+      # Edge readings
+      SSF_IN_LOW => :lowest,
+      SSF_IN_HIGH => :highest,
+      
+      # Minima and maxima
+      SSF_IN_MIN => :min,
+      SSF_IN_MAX => :max,
+      
+      # Critical levels
+      SSF_IN_LCRIT => :lcrit,
+      SSF_IN_CRIT => :crit,
+      
+      # Averages
+      SSF_IN_AVG => :average,
+    },
+    # Currents
+    SF_CURR => {
+      # Inputs
+      SSF_CURR_INPUT => :input,
+      
+      # Edge readings
+      SSF_CURR_LOW => :lowest,
+      SSF_CURR_HIGH => :highest,
+      
+      # Minima and maxima
+      SSF_CURR_MIN => :min,
+      SSF_CURR_MAX => :max,
+      
+      # Critical levels
+      SSF_CURR_LCRIT => :lcrit,
+      SSF_CURR_CRIT => :crit,
+      
+      # Averages
+      SSF_CURR_AVG => :average,
+    },
+    # Power
+    SF_POWER => {
+      # Inputs
+      SSF_POWER_INPUT => :input,
+      SSF_POWER_INPUT_LOW => :input_low,
+      SSF_POWER_INPUT_HIGH => :input_high,
+      
+      # Minima and maxima
+      SSF_POWER_MIN => :min,
+      SSF_POWER_MAX => :max,
+      
+      # Critical levels
+      SSF_POWER_LCRIT => :lcrit,
+      SSF_POWER_CRIT => :crit,
+      
+      # Averages
+      SSF_POWER_AVG => :average,
+      SSF_POWER_AVG_LOW => :average_low,
+      SSF_POWER_AVG_HIGH => :average_high,
+      
+      # Caps
+      SSF_POWER_CAP => :cap,
+      SSF_POWER_CAP_HYST => :cap_hyst,
+    },
+    
+    # Temperatures
+    SF_TEMP => {
+      # Inputs
+      SSF_TEMP_INPUT => :input,
+      
+      # Edge readings
+      SSF_TEMP_LOW => :lowest,
+      SSF_TEMP_HIGH => :highest,
+      
+      # Minima and maxima + hysteresis
+      SSF_TEMP_MIN => :min,
+      SSF_TEMP_MIN_HYST => :min_hyst,
+      SSF_TEMP_MAX => :max,
+      SSF_TEMP_MAX_HYST => :max_hyst,
+      
+      # Critical and emergency levels + hysteresis
+      SSF_TEMP_LCRIT => :lcrit,
+      SSF_TEMP_LCRIT_HYST => :lcrit_hyst,
+      SSF_TEMP_CRIT => :crit,
+      SSF_TEMP_CRIT_HYST => :crit_hyst,
+      SSF_TEMP_EMERG => :emergency,
+      SSF_TEMP_EMERG_HYST => :emergency_hyst,
+    },
+    # Fans
+    # Fan sensors have a simple structure that is self-explanatory.
+    SF_FAN => { SSF_FAN_INPUT => :input, SSF_FAN_MIN => :min, SSF_FAN_MAX => :max, },
+  } # End SSF subtypes
+end # End LmSensors constants maps

data/lib/lmsensors/lmsensors.rb

@@ -0,0 +1,33 @@
+# lib/lmsensors/lmsensors.rb
+
+# Base requires
+require_relative "../lmsensors_base/lmsensors_base"
+require_relative "./lm_constants"
+
+require_relative "./sensors/sensorspawner"
+require_relative "./sensors/sensor"
+
+require_relative "./feature"
+
+##
+# LmSensors is the wrapping module for the entire
+# lm-sensors library. This module provides the ability
+# to initialize for and clean up resources from it, to
+# generate Sensor objects that can be used to monitor
+# specific pieces of hardware, as desired, and to generate
+# a SensorSpawner to enumerate what sensors are available.
+module LmSensors
+  ##
+  # Wraps the 'pro_init' function to initialize the sensors
+  def self.init(filename=nil) self.pro_init(filename) end
+  
+  ##
+  # Wraps the 'pro_cleanup' function to release the resources
+  def self.cleanup() self.pro_cleanup end
+  
+  ##
+  # For compatibility purposes, as this was
+  # being tested by some people, Sensors is now
+  # purely an alias of SensorSpawner.
+  Sensors = LmSensors::SensorSpawner
+end # End LmSensors module

data/lib/lmsensors/sensors/abssensor.rb

@@ -0,0 +1,151 @@
+# lib/lmsensors/sensors/abssensors.rb
+
+# Requires
+require_relative "../../lmsensors_base/lmsensors_base"
+require_relative "../lm_constants"
+require_relative "../feature"
+
+# :nodoc: This module will house the abstract implementation
+# :nodoc: of a general sensor-type object.
+module LmSensors
+  ##
+  # AbsSensor is an abstract representation of
+  # a sensor-type object and provides a base interface
+  # for required functions (operates like a trait).
+  class AbsSensor < LmSensors::SensorsBase
+    ##
+    # AbsSensor :chip_name is the name sensors returns for the chip
+    attr_reader :chip_name
+    ##
+    # AbsSensor :filters are the selected feature types to return for your use case
+    attr_reader :filters
+    ##
+    # AbsSensor :fmap is a custom formatter map or the default DEF_FMAP
+    attr_reader :fmap
+    ##
+    # AbsSensor :fmt is a boolean of whether or not to return the data formatted
+    attr_reader :fmt
+    ##
+    # AbsSensor :subs is whether to return the subfeatures or just the feature
+    # and its type
+    attr_reader :subs
+    
+    ##
+    # Constructor
+    def initialize
+      pro_initialize
+      unset_filters
+      @fmt = @subs = false
+      @fmap = LmSensors::DEF_FMAP
+    end # End constructor
+    
+    ##
+    # Get the chip_name
+    def name() @chip_name end
+    
+    ##
+    # Set the sensor's filters, the types that
+    # will be returned on '.features'.
+    def set_filters(arr)
+      if Array === arr then
+        @filters = arr.select { |item| LmSensors::UNITS.include? item } .sort
+      else STDERR.puts "::Sensors ERROR:: Filters must be an array" end
+    end # End set filters
+    
+    ##
+    # Unset the filters for this sensor
+    def unset_filters() @filters = [] end
+    
+    ##
+    # Toggle whether this sensor also returns
+    # subfeatures on a feature list request.
+    def toggle_subs() @subs = !@subs end
+    
+    ##
+    # Toggle if the sensor will report with
+    # formatted output or unformatted. Default
+    # is to report unformatted.
+    def toggle_fmt() @fmt = !@fmt end
+    
+    ##
+    # Set the format mapper for the different types.
+    # This method should receive a proc that maps to different
+    # feature formatters.
+    def set_fmap(map)
+      # Only accept a proc/lambda for format mapping
+      if Proc === map then
+        if map.arity != 2 then
+          if !$LmSensorsIgnArity then
+            STDERR.puts <<~EMSG
+            ::SensorSpawner WARNING:: @fmap arity should be 2 and will
+            NOT WORK without being overridden in a custom subclass.
+            
+            If you are receiving this message, and you have already
+            overridden the subclasses and format handling, you should
+            set the global variable $LmSensorsIgnArity to 'true'.
+            
+            This is only a warning and will not stop the map from
+            being set, even if it is invalid.
+            
+            This warning will NOT be displayed again in this run.
+            EMSG
+            $LmSensorsIgnArity = true
+          end
+          @fmap = map
+        end
+      else # If it's not a proc, spit out an error
+        STDERR.puts "::Sensors ERROR:: Format map must be a proc/lambda"
+      end
+    end # End format mapper
+    
+    ##
+    # Reset the formatting map
+    def reset_fmap() @fmap = LmSensors::DEF_FMAP end
+    
+    ##
+    # Abstract enum must be implemented
+    # by subclasses
+    def enum(*args)
+      STDERR.puts "::AbsSensor ERROR:: Abstract 'enum' not implemented for #{self.class}"
+      []
+    end # End abstract enum
+    
+    ##
+    # Get the number of sensors available
+    # for the current name (or the total number
+    # of sensors available).
+    def count
+      data = enum
+      if ([Hash, Array].include?(data.class)) then
+        # If the data is good
+        data.count
+      else return nil end
+      
+    end # End count of sensors
+    alias :count_s :count # Add alias for backwards compatibility
+    
+    # Protected methods
+    protected
+    
+    ##
+    # Validate a path -- protected
+    def path_valid?(path)
+      # Check that the path argument is a string
+      if (!path.is_a?(String)) then
+        STDERR.puts "::Sensor ERROR:: Path must be string!"
+        return nil
+      end # End check for correct path
+      # Clean the path input
+      dir = path.strip.gsub(/\/*$/, "")
+      
+      # Check if path is a directory, else exit early.
+      # Do not need to check File.exist? first, b/c this
+      # already returns nil, if it doesn't.
+      if !File.directory?(dir) then
+        STDERR.puts "::Sensors ERROR:: Path is either invalid or not a directory!"
+        return nil
+      end # End directory check
+      dir # Return the correct path
+    end # End path validation 
+  end # End Sensors class
+end # End LmSensors append

data/lib/lmsensors/sensors/sensor.rb

@@ -0,0 +1,148 @@
+# lib/lmsensors/sensors/sensors.rb
+
+# Require the abstract sensor
+require_relative "./abssensor"
+
+# :nodoc: This module will house the concrete implementation
+# :nodoc: of the actual Sensor object types.
+module LmSensors
+  ##
+  # Sensor is a concrete implementation
+  # of the AbsSensor. This implementation
+  # is a specific object dedicated to an
+  # individual sensor chip.
+  class Sensor < LmSensors::AbsSensor
+    ##
+    # Sensor :path is the '/sys/class/hwmon/' path for this specific sensor
+    attr_reader :path
+    # Sensor :adapter is the adapter type, like the PCI or ISA adapter
+    attr_reader :adapter
+    
+    ##
+    # Find a device sensors by its path, in such
+    # a case where the app already has a device from
+    # sysfs or similar and needs to attach them together.
+    # 
+    # Sets the name of the sensor, as well, so this should
+    # be used as an instance.
+    def locate(path)
+      # Validate the path
+      dir = path_valid?(path)
+      if !dir then return nil end
+      # Determine if it's a valid sensor, since the
+      # sensors here use the path as the index.
+      # If so, set it as this object's name
+      raw = pro_enum(nil, nil)
+      # Check if the enum value is valid
+      if (![Hash, Array].include?(raw.class)) then
+        STDERR.puts raw
+        return nil
+      end # End enum check
+      raw.then do |sensors|
+        # Return early, if it's not in the keys
+        if !sensors.keys.include?(dir) then
+          STDERR.puts "Path does not have an associated sensor"
+          return nil
+        end # End check for valid sensor path
+        
+        # Set the data and return the chip name
+        data = sensors[dir]
+        @chip_name = data[:name]
+        @adapter = data[:adapter]
+        @path = data[:path]
+        @chip_name
+      end # End enumeration handler
+    end # End locate by path
+    
+    ##
+    # Return the core chip data. This does NOT include
+    # the features and subfeatures, just the information
+    # on the chip itself.
+    def info() { name: name, adapter: @adapter, path: @path, } end
+    
+    ##
+    # Stat will return the values and names
+    # of all the features associated with the
+    # currently-selected chip. This has replaced
+    # :features, which is now just an alias for :stat.
+    # 
+    # 2021-May-31 (pre-release): Now respects @filters
+    def stat
+      # For each chip, split it by key and value
+      raw = read
+      # Check that the data is still valid
+      if raw.nil? then return nil end
+      data = raw.collect do |feature, keys|
+        # Is the filter set?
+        no_filter = @filters.empty?
+        # Is the feature of a type included in the filter?
+        included = @filters.include?(keys[:type])
+        
+        # If the filter is NOT set, OR the keys IS included
+        # in the filter, proceed.
+        if no_filter or included then
+          # If the subfeature option is set, return
+          # the subfeature data and the unit.
+          if @subs then
+            @fmap.call(feature, keys)
+          # If the subfeature option is not set, just return
+          # the feature type.
+          else { feature => keys[:type] } end
+        # If filtered and not included, return empty array
+        else [] end
+      end.flatten # Remove any empty units
+      # If format is set, format the output
+      if (@fmt and @subs) then data.collect { |item| item.fmt } else data end
+    end
+    # Pseudo-alias abstract enum to stat, for this class
+    def enum(*args) stat end
+    
+    ##
+    # :features is now an alias for :stat,
+    # as :stat did not previously respect @filters
+    alias :features :stat
+    
+    ##
+    # Get the number of features available for
+    # the current name (or total features to be
+    # read for all sensors). This overrides the
+    # abstract ``.count`` method.
+    def count
+      data = read
+      if !data then return nil end
+      # If the data is good
+      data.count
+    end # End count method
+    
+    ##
+    # Get the number of subfeatures available for
+    # the current name (or total features to be
+    # read for all sensors).
+    def count_sf
+      total = 0 # Accumulator
+      data = read
+      if !data then return nil end
+      # If the data is good, continue
+      data.each do |_, v|
+        # Ignore the :type symbol
+        total += (v.select { |item| :type != item } .count)
+      end
+      total # Return accumulator
+    end # End count of subfeatures
+    
+    ##
+    # Raw chip data -- this is unfiltered and unformatted.
+    # 
+    # This has replaced the previous version of :stat, as
+    # :stat unintentionally did not respect the @filters.
+    def read
+      c = pro_enum(true, @chip_name)
+      if Hash === c then
+        c[@path][:stat]
+      else
+        STDERR.puts c
+        return nil
+      end
+    end # End read
+  end # End Sensor class
+end # End LmSensors append