rb_scope 2.0.2

data/lib/rb_scope/api/niScope_template.rb

@@ -0,0 +1,272 @@
+module RbScope
+
+  module API
+
+    # Provide a type translator between Ruby::FFI and C for automatic code generation
+    Types = {
+      c: {
+        p_char:   "char*",   
+        p_int16:  "short*", 
+        p_uint16: "unsigned short*",  
+        p_int32:  "ViInt32*",   #ViInt32 might be changed into long by visatype.h
+        p_uint32: "ViUInt32*",  #ViUInt32 might be changed into unsigned long by visatype.h
+        p_double: "double*",
+        pointer:  "void*",
+        int16:    "short",
+        int32:    "int",
+        uint16:   "unsigned short",
+        uint32:   "unsigned int"
+      },
+      ruby: {
+        p_char:   :pointer, 
+        p_int16:  :pointer,   
+        p_int32:  :pointer,
+        p_uint16: :pointer,
+        p_uint32: :pointer,
+        p_double: :pointer
+      }
+    }
+
+    # Contains a partial list of the signature of the niScope.h functions
+    # This array is used by rb_scope/api/niScope_api.rb to dynamically attach the niScope function to Ruby
+    # It is also used by ext/rb_scope/generators/wrapper_generator to construct a statically linked dll that Ruby::FFI can link to
+    Template =  [      
+      ## open/close ##
+    
+      [:niScope_init,   
+        [ :p_char,                      # device address(char*) 
+          :uint16,                      # perform an Id query ?
+          :uint16,                      # reset device ?
+          :p_uint32                     # pointer to session id (uint32*)
+        ],  
+        :int32 ],
+        
+      [:niScope_close,  
+        [ :uint32],                     # session id 
+        :int32],
+ 
+ 
+      ## configurationg ##  
+        
+      [:niScope_CalSelfCalibrate, 
+        [ :uint32,                      # session id 
+          :p_char,                      # channel list (const char*) 
+          :int32                        # option (VI_NULL for normal self-cal)
+        ], 
+         :int32],
+         
+      [:niScope_ConfigureAcquisition,
+        [ :uint32,                      # session id  
+          :int32                        # acq type (NISCOPE_VAL_NORMAL)
+        ],
+        :int32],
+        
+      [:niScope_ConfigureTriggerDigital,
+        [ :uint32,                      # session id 
+          :p_char,                      # trig src (const char*) NISCOPE_VAL_EXTERNAL
+          :int32,                       # slope (rising or falling edge) NISCOPE_VAL_POSITIVE
+          :double,                      # holdoff (dead time)
+          :double                       # delay before acquisition
+        ],
+        :int32],
+        
+      [:niScope_ConfigureTriggerEdge,
+        [ :uint32,                      # session id  
+          :p_char,                      # trig src (const char*) NISCOPE_VAL_EXTERNAL
+          :double,                      # voltage value
+          :int32,                       # slope (rising or falling) NISCOPE_VAL_POSITIVE
+          :int32,                       # trig coupling (NISCOPE_VAL_DC)
+          :double,                      # holdoff
+          :double                       # delay
+        ],
+        :int32],
+        
+      [:niScope_ConfigureTriggerImmediate,
+        [ :uint32],                     # session id 
+        :int32],
+        
+      [:niScope_ConfigureChanCharacteristics,
+        [ :uint32,                      # session id  
+          :p_char,                      # channel list (const char*)
+          :double,                      # input impedance (50 / 1000000)
+          :double                       # bandwidth
+        ],
+        :int32],
+        
+      [:niScope_ConfigureVertical,
+        [ :uint32,                      # session id  
+          :p_char,                      # channel list (const char*)
+          :double,                      # voltage range
+          :double,                      # voltage offset (0.0)
+          :int32,                       # coupling
+          :double,                      # probe attenuation (1.0)
+          :uint16                       # enable (VI_TRUE)
+        ],
+        :int32],
+        
+      [:niScope_ConfigureHorizontalTiming,
+        [ :uint32,                      # session id  
+          :double,                      # sample rate
+          :int32,                       # num pts per frame
+          :double,                      # reference event position as a % 
+          :int32,                       # num record (# of frames)
+          :uint16                       # real_time (VI_TRUE)
+        ],
+        :int32],
+        
+      [:niScope_ActualRecordLength,
+        [ :uint32,                      # session id  
+          :p_int32,                     # output val (int*)
+        ],
+        :int32],
+        
+      [:niScope_ActualNumWfms,
+        [ :uint32,                      # session id  
+          :p_char,                      # channel list (const char*)
+          :p_int32                      # output val (int32*)
+        ],
+        :int32],
+         
+
+      ## getters ##
+         
+      [:niScope_GetAttributeViBoolean,
+        [ :uint32,                      # session id
+          :p_char,                      # channel list (const char*)
+          :uint32,                      # attribute id
+          :p_uint16                     # output val (uint16*)
+        ],
+        :int32],
+        
+      [:niScope_GetAttributeViInt32,
+        [ :uint32,                      # session id
+          :p_char,                      # channel list (const char*)
+          :uint32,                      # attribute id
+          :p_int32                      # output val (int32*)
+        ],
+        :int32],
+        
+      [:niScope_GetAttributeViReal64,
+        [ :uint32,                      # session id
+          :p_char,                      # channel list (const char*)
+          :uint32,                      # attribute id
+          :p_double                     # output val (double*)
+        ],
+        :int32],
+        
+      [:niScope_GetAttributeViString,
+        [ :uint32,                      # session id
+          :p_char,                      # channel list (const char*)
+          :uint32,                      # attribute id
+          :int32,                       # buffer size
+          :p_char,                      # buffer (char*)
+        ],
+        :int32],
+        
+        
+      ## setters ##  
+      
+      [:niScope_SetAttributeViBoolean,
+        [ :uint32,                      # session id
+          :p_char,                      # channel list (const char*)
+          :uint32,                      # attribute id
+          :uint16                       # value
+        ],
+        :int32],
+
+      [:niScope_SetAttributeViInt32,
+        [ :uint32,                      # session id
+          :p_char,                      # channel list (const char*)
+          :uint32,                      # attribute id
+          :int32                        # value
+        ],
+        :int32],
+
+      [:niScope_SetAttributeViReal64,
+        [ :uint32,                      # session id
+          :p_char,                      # channel list (const char*)
+          :uint32,                      # attribute id
+          :double                       # value
+        ],
+        :int32],
+
+      [:niScope_SetAttributeViString,
+        [ :uint32,                      # session id
+          :p_char,                      # channel list (const char*)
+          :uint32,                      # attribute id
+          :p_char                       # value (const char*)
+        ],
+        :int32],
+        
+        
+      ## error handling functions ##
+        
+      [:niScope_errorHandler,
+        [ :uint32,                      # session id 
+          :int32,                       # error code
+          :p_char,                      # error source buffer (char*)
+          :p_char                       # error desc buffer (char*)
+        ],
+        :int32],
+        
+      [:niScope_GetError,
+        [ :uint32,                      # session id
+          :p_int32,                     # error code output (int32*)
+          :int32,                       # buffer size
+          :p_char                       # buffer for error (char*)
+        ],
+        :int32],
+        
+      [:niScope_GetErrorMessage,
+        [ :uint32,                      # session id
+          :int32,                       # error code
+          :int32,                       # buffer size
+          :p_char                       # buffer for error msg (char*)
+        ],
+        :int32],
+        
+   
+      ## acquisition functions ##
+   
+      [:niScope_InitiateAcquisition,
+        [ :uint32],                     # session id          
+        :int32],
+
+      [:niScope_AcquisitionStatus,
+        [ :uint32,                      # session id
+          :p_int32                      # output acquisition status (int32*)
+        ],
+        :int32],
+        
+      # <TO_DO> check timeout error, if so, abort and go back to idle state      
+      [:niScope_FetchBinary8,
+        [ :uint32,                      # session id
+          :p_char,                      # channel list (const char*)
+          :double,                      # timeout (0: available, -1: inf)
+          :int32,                       # numSamples to fetch (-1 fetch all)
+          :p_char,                      # pointer to buffer (signed int8*)
+          :pointer,                     # timing info (struct niScope_wfmInfo*)
+        ],  
+        :int32],
+        
+      [:niScope_FetchBinary16,
+        [ :uint32,                      # session id
+          :p_char,                      # channel list (const char*)
+          :double,                      # timeout (0: available, -1: inf)
+          :int32,                       # numSamples to fetch (-1 fetch all)
+          :p_int16,                     # pointer to buffer (signed int16*)
+          :pointer,                     # timing info (struct niScope_wfmInfo*)
+        ],  
+        :int32],
+        
+      #Aborts an acquisition and returns the digitizer to the Idle state. 
+      #Call this function if the digitizer times out waiting for a trigger.         
+      [:niScope_Abort,
+        [ :uint32],                     # session id       
+        :int32],   
+      
+    ]
+  
+  end
+  
+end

data/lib/rb_scope/api/niScope_values.rb

@@ -0,0 +1,34 @@
+module RbScope
+
+  # This module reads the file rb_scope/niScope_pairs 
+  # and use the information inside to automatically generate constants
+  # with values equivalent to the niScope.h #define macro constants.
+  # The file rb_scope/niScope_pairs is automatically generated by the 
+  # shell script extract_all.sh in ext/rb_scope/generators
+  module API
+
+    module Values
+
+      Hash.new.tap{ |pairs|   
+        File.open(File.dirname(__FILE__) + '/niScope_pairs.const', 'r').readlines.tap do |lines|
+          pairs[lines.shift] = lines.shift until lines.empty? #good 2 shift order
+        end     
+      }.each do |k,v|
+        begin
+          self.const_set k.chomp, eval(v)     #don't forget to chomp the line
+        rescue Exception => e
+          #puts "eval error for value %s" % k
+        end    
+      end
+      
+      #for safety, redefine these
+      VI_SUCCESS  = 0
+      VI_NULL     = 0
+      VI_TRUE     = 1
+      VI_FALSE    = 0
+      
+    end
+  
+  end
+
+end

data/lib/rb_scope/api.rb

@@ -0,0 +1,10 @@
+module RbScope
+
+  module API
+
+    require 'rb_scope/api/niScope_api'    
+    require 'rb_scope/api/niScope_values'
+
+  end
+  
+end

data/lib/rb_scope/fetch.rb

@@ -0,0 +1,70 @@
+module RbScope
+
+  module Fetch
+
+    require 'ffi'
+    extend FFI::Library
+    
+    #begin
+      ffi_lib $LOAD_PATH.map{ |path| path+"/rb_scope/fetch.dll"}
+      attach_function :fetch, [:pointer], :int32, :blocking => true
+    #rescue
+    #  RbScope::prompt "could not load fetch.dll library"
+    #end
+    
+    # simple Struct wrapper to pass information to fetch.c/fetch()
+    class Helper < FFI::ManagedStruct      
+      layout  :address,   :pointer,
+              :error,     :pointer,
+              :buff0,     :pointer,
+              :buff1,     :pointer,
+              :context0,  :pointer,
+              :context1,  :pointer,
+              :timeout,   :double,
+              :points,    :int32,     #also frn_siz
+              :records,   :int32,     #also frm_tot
+              :chunk,     :int32,     #also chunk
+              :session,   :uint32
+
+      Default = {
+        error:    nil,
+        buff0:    nil,
+        buff1:    nil,
+        context0: nil,
+        context1: nil,
+        timeout:  10.0,
+        records:  1,
+        chunk:    1,
+      }
+      
+    end
+    
+  end
+      
+  class Session
+
+    def run param, &block 
+    
+      h = Helper.new
+      Helper::Default.each_pair{ |k,v| h[k] = param[k] || v }  #configure from parameters or ortherwise use default 
+      
+      h[:address] = FFI::MemoryPointer.from_string @address
+      h[:session] = FFI::MemoryPointer.from_string @visa_id      
+      h[:points]  = @points
+      begin
+      h[:buff0], h[:context0] = param[:chan0].call, param[:chan0].context if param[:chan0]
+      h[:buff1], h[:context1] = param[:chan1].call, param[:chan1].context if param[:chan1]
+      rescue
+        RbScope::prompt "could not configure channels output buffers"
+      end
+    
+      self.acquire
+      block.call if block   # call pre-fetching block if necessary
+      Fetch::fetch  h
+      self
+      
+    end
+  
+  end
+  
+end

data/lib/rb_scope/session.rb

@@ -0,0 +1,37 @@
+module RbScope
+  
+  # Helper class to encapsulate data and state relative to a device Session
+  # This is the main class that clients instantiate to use the gem.
+  # <TO_DO> 1) implement errors 2) attributes setters/getters
+  #
+  # typical usage: RbScope::Session.new("mydevice").configure parameters
+  # 
+  class Session
+
+    attr_reader :address, :visa_id, :status
+
+    #starts a new connection
+    def initialize address, &block
+      @address = address      
+      session_p = FFI::MemoryPointer.new :pointer, 1      
+      @status = API::rbScope_init address, 1, 1, session_p
+      #handle error if @status < 0
+      @visa_id = session_p.read_pointer.read_uint32
+      prompt "session ##{@visa_id} for device #{@address} initalized with status #{@status}"
+      self.instance_eval &block if block
+      self
+    end
+  
+    # cleanup method called by the garbage collector
+    def self.release session
+      if API::rbScope_close(session.visa_id) < 0
+        #handle error
+      end
+    end
+    
+    require 'rb_scope/session_methods'
+    require 'rb_scope/session_attributes'   
+    
+  end
+
+end

data/lib/rb_scope/session_attributes.rb

@@ -0,0 +1,21 @@
+module RbScope
+
+  class Session 
+
+    Attribute = [
+    
+    
+    ]
+  
+    Getters = [
+    
+    
+    ]   
+    
+    def define_attribute name, id, type    
+      #nantoka    
+    end
+  
+  end
+  
+end

data/lib/rb_scope/session_methods.rb

@@ -0,0 +1,82 @@
+module RbScope
+
+  class Session 
+
+    # This table defines the how the methods from the niScope dll are hooked to instances
+    # of the Session class.
+    # Arguments are passed to each methods with an Hash and through their Hash keys
+    Methods = [
+      [:calibrate,  "CalSelfCalibrate", ["0,1", 0]],
+      [:acquire,    "InitiateAcquisition", []],
+      [:stop,       "Abort", []],
+
+      [:trig_now,   "ConfigureTriggerImmediate", []],
+      [:trig_digi,
+        "ConfigureTriggerDigital",
+        [API::Values::NISCOPE_VAL_EXTERNAL, :slope, :deadtime, 0.0]],
+      [:trig_edge,
+        "Configure_TriggerEdge",
+        [API::Values::NISCOPE_VAL_EXTERNAL, :trig_voltage, :slope, :trig_coupling, :deadtime, 0.0]],
+
+      [:vertical,   "ConfigureVertical",
+        [:channel, :range, 0.0, :coupling, 1.0, 1]],
+      [:channel,    "ConfigureChanCharacteristics",
+        [:channel, :impedance, :bandwidth]],
+      [:horizontal, "ConfigureHorizontalTiming",
+        [:rate, :points, :trig_reference, :records, 1]],      
+    ]
+    
+    #this block of code does the actual patching
+    Methods.each do |sig|   
+      define_method(sig[0]) do |*args|
+        meth = "rbScope_#{sig[1]}".to_sym           # generate the good method name found in RbScope::API
+        args_chain  = [@visa_id]                     # first arg is always the session Id number
+                    + sig[2].map{ |x|
+                      if x.is_a? Symbol             # if x is a symbol, check for user provided value
+                        args[x] || Defaults[x]      # if no value use default
+                      else
+                        x                           # else use the hardcoded value
+                      end
+                    }
+        @status = API::send meth, args_chain        # finally dispatch the method call to RbScope::API
+        #handle_error if rez < 0
+        self
+      end
+    end
+    
+    # 1-in-4 configuration methods with the convention that there is a :channel key 
+    # which points to an array of subhash for both channels which looks like:
+    #   parameters = {:channel [ {range: 0.1, chan_impendance: 50, ... }, {...} ]}
+    def configure parameters
+      @points = parameters[:points] || Defaults[:points]
+      self.horizontal parameters
+      parameters[:channel].each_with_index{ |p,i|
+        self.channel i.to_s, p
+      } if parameters[:channel]
+    end
+    
+    #shortcut for channel configuration
+    def channel chan, parameters
+      param = parameters.clone.tap{ |hash| hash[:channel] = chan }
+      [:channel, :vertical].each{ |meth| self.send meth, parame }
+    end
+      
+    # default values for parameters of configuration functions
+    Defaults = {
+      deadtime:         0.0,
+      slope:            API::Values::NISCOPE_VAL_POSITIVE,
+      trig_coupling:    API::Values::NISCOPE_VAL_DC,
+      trig_voltage:     0.5,
+      trig_reference:   0.5,
+      coupling:         API::Values::NISCOPE_VAL_AC,
+      impedance:        API::Values::NISCOPE_VAL_1_MEG_OHM,
+      bandwidth:        API::Values::NISCOPE_VAL_BANDWIDTH_FULL,
+      rate:             1000000,
+      points:           1000,
+      records:          1000,
+      range:            1.0,
+    }
+  
+  end
+  
+end

data/lib/rb_scope.rb

@@ -0,0 +1,39 @@
+##
+ #              rb_scope
+ #
+ #    ( C2Ruby wrapper to NI-Scope drivers )
+ #    
+ #  author      hugo benichi
+ #  email       hugo.benichi@m4x.org
+ #  copyright   2012 hugo benichi
+ #  
+ #  description 
+ #  
+ #    A Ruby layer wrapping around C calls to the NI-Scope drivers.
+ #    Most C data manipulation and C calls are done through the FFI gems.
+ #	  In addition a few C methods are provided for improved efficiency when handling data
+ #
+ ##
+
+# main namespace module which encapsulates the helper methods and wrappring API calls
+module RbScope
+  
+  # <TO_DO> all addressedd from conf file / NiScope to auto-detect them ?
+
+  class << self
+
+    # prefix a message before writing to stdout
+	  def prompt message
+      puts "RbScope >> #{message}"
+    end
+
+  end
+
+  [
+    'rb_scope/api',
+    'rb_scope/fetch',
+    'rb_scope/session',
+  ].each{ |mod| require mod }
+  
+end
+

data/rakefile.rb

@@ -0,0 +1,77 @@
+require 'rake/clean'
+
+name = 'rb_scope'
+
+# at installation
+
+  task :gem_build do
+    sh "gem build %s.gemspec" % name
+  end
+
+  task :gem_install => :gem_build do
+    gemfile = Dir.new("./").entries.select{ |f| f =~ /rb_scope-[\d]+\.[\d]+\.[\d]+.gem/ }[0]
+    sh "gem install %s" % gemfile
+  end
+
+  task :doc do  
+    sh 'rdoc lib' 
+  end
+
+
+# testing tasks
+
+task :debug => [:gem_install, :test_gem]
+
+task :test_local do
+  sh "ruby -I./lib test/test_rb_scope.rb"
+end
+
+task :test_gem do
+  sh "ruby -I./lib test/test_rb_scope.rb"
+end
+
+task :load do
+  sh "ruby -Ilib -Iext lib/rb_scope/api/niScope_api.rb"
+end
+
+# post-install compilation tasks
+
+  task :dll_install => [:dll_rb_scope, :dll_fetch] do
+    #mark down 
+  end
+  
+  path_include = ""
+  path_library = ""
+  
+  task :set_path do
+    puts "you might need to run the command prompt as Administrator"
+    #ask for VC env var batch script
+      sh '"C:\Program Files (x86)\MVS10.0\VC\vcvarsall.bat"'
+      #ask for path to niScope.h
+      #ask for path to ivi.h and visa.h
+      path_include = '"C:\Program Files (x86)\IVI Foundation\VISA\WinNT\include"'
+      #ask for path to niScope.lib
+      path_library = '"C:\Program Files (x86)\IVI Foundation\VISA\WinNT\Lib\msc\niScope.lib"'
+  end
+
+  task :dll_rb_scope => :set_path do
+    #write down wrapper.c
+      #ruby -Ilib ext\ni_scope\wrapper_generator.rb > ext\ni_scope\wrapper.c
+    #compile
+      sh 'cl -c .\ext\rb_scope\wrapper.c -I%s' % path_include
+      #compile rb_scope.c with good dependency
+    #link
+      sh 'link /DLL /OUT:lib\rb_scope\rb_scope.dll wrapper.obj %s' % path_library   
+  end
+
+  task :dll_fetch => :set_path do
+    sh 'cl -c .\ext\rb_scope\fetching\fetch.c -I%s -I.\ext\rb_scope\fetching' % path_include
+    sh 'link /DLL /OUT:lib\rb_scope\fetch.dll fetch.obj %s' %path_library
+  end
+
+# cleaning  
+  
+  CLEAN.include 'ext/**/*{.o,.obj}'
+  CLEAN.include '*{.gem}'
+  CLOBBER.include 'lib/**/*.{dll,exp,lib}'
+

data/test/test_rb_scope.rb

@@ -0,0 +1,3 @@
+require "rb_scope"
+
+puts "ok"