minilab 1.0.0-mswin32

data/.document

@@ -0,0 +1,2 @@
+README
+lib/minilab.rb

data/CHANGES

@@ -0,0 +1,2 @@
+== 1.0.0
+First release

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2007 Atomic Object, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,107 @@
+== About
+
+minilab is a Ruby extension for Measurement Computing's miniLAB 1008 device. The minilab extension provides a simple interface to several of the miniLAB 1008's analog and digital IO functions. I've used the miniLAB to control the input and examine the output from our embedded devices; the minilab extension allowed us to use automated system testing tools for Ruby.
+
+minilab is not guaranteed to work with other Measurement Computing devices, but could be extended to do so.
+
+== Installation
+
+1. Install the minilab gem onto your system or unpack it into a local directory in your project. Install Measurement Computing's Universal Library and InstaCal software; both come on CDs with the device.
+
+1. Plug in the device and then fire up the InstaCal software. Go to Install -> Configure in the menus and the Custom Serial Number to 253, No. of Channels to 8 Single Ended, and Trigger Source to DIO0. Use the Flash LED button to ensure that InstaCal can communicate with the device (I've never had a problem with this). Although I don't think the Custom Serial Number and Trigger Source make much difference to my extension, the No. of Channels is important (see Known limitations below).
+
+1. That should be it---you should now be able to require 'lib/minilab,' create a minilab object, and connect to it. If you can't, please contact me! I've only installed this on a limited number of computers, so I'd like to hear about problems with the library installation, gem installation, LOAD_PATH, etc.
+
+=== Building the C extension
+I included a precompiled version of the C extension with the gem so that everyone doesn't need to worry about compiling. If you'd really like to compile it, then the Rakefile has several targets for managing the build (see extension:build, extension:clean). In order to build, there is a good chance you'll need to edit the Rakefile to use the correct paths to your build environment (they are at the bottom). Right now they're set up strictly for my laptop.
+
+== Usage
+=== Build and connect
+
+First you'll need to build the Minilab object; use the Minilab.build class method to do this. The class method is important to use instead of +new+, since it takes care of a lot of behind-the-scenes object construction for you.
+
+After building the object, use the +connect+ method. This will establish the connection to the library. None of the other methods will work until you connect.
+
+Example:
+
+<tt>minilab = Minilab.build</tt>
+
+<tt>minilab.connect</tt>
+
+=== Reading and writing data
+
+I've created methods for reading and writing both digital and analog data from the device. Analog data goes through the read and write pins on the top of the device; no configuration is needed for the analog methods.
+
+Digital data goes through either the DIO pins on the top of the device or the digital ports on the DB37 port. If you're using the DIO pins, then you don't need to do any configuration. If you're using the DB37 pins, then you'll need to configure the appropriate port for input and output. You can find a mapping of DB37 pin numbers to ports either in Measurement Computing's miniLAB 1008 data sheet or at the end of this README.
+
+Check out the read and write analog and read, write, and configure digital methods in the Minilab document for more information.
+
+Example:
+
+<tt> minilab.configure_input_port(:portb) </tt>
+
+<tt> value = minilab.read_digital_byte(:portb) </tt>
+
+<tt> assert_equal 12, value, "wrong value read for system time" </tt>
+
+The adventurous may also want to look at the included system tests for the device, since they are examples of how to use the device and are not contrived.
+
+== Tests
+
+The minilab extension comes with unit, integration, and system tests. The unit tests stress individual units. The integration and system tests represent real use cases for the software; in the case of integration tests, the hardware is mocked out whereas the hardware is not mocked during system tests. This means that unit and integration tests can be run without the hardware plugged in, but system tests require the hardware. Even though there is some overlap between integration and system tests, integration tests made it easier for me to safely develop new features without having bulky hardware plugged in all the time.
+
+See the end of the document of this document for an outline of how a miniLAB and DB37 connector should be set up in order to run the system tests.
+
+== Known limitations
+
+* The minilab extension only supports one device plugged in at a time. I could add support for multiple devices, but since I only have one, I haven't bothered adding support for more than one.
+
+* I never got around to writing out an entire digital byte because I never needed it.
+
+* Reading analog values only supports single-ended mode. As you can probably guess, I didn't need differential mode, so I didn't add support for it.
+
+In any case, contact me if you'd like me to implement any of this functionality. Add functionality yourself is always possible and may be quicker than waiting for me to do it.
+
+== Contact information
+Matt Fletcher
+
+Developer
+
+Atomic Object, LLC
+
+fletcher@atomicobject.com
+
+== Appendix
+=== DB37 pin to port mapping
+Pin:: Port
+30-37:: :porta
+3-10:: :portb
+26-29:: :portcl
+22-25:: :portch
+
+=== System test setup
+
+On top of the miniLAB:
+CH0 IN:: D/A OUT 1
+CH1 IN:: GND
+CH2 IN:: DIO0
+CH4 IN:: PC +5V
+CH6 IN:: D/A OUT 0
+DIO0:: DIO3
+DIO1:: PC +5V
+DIO2:: GND
+
+On the DB37 pins:
+3:: 11
+4:: 11
+5:: 28
+6:: 11
+7:: 36
+8:: 11
+9:: 11
+10:: 20
+22:: 27
+23:: 21
+24:: 34
+25:: 21
+30:: 21

data/Rakefile

@@ -0,0 +1,145 @@
+require File.expand_path(File.dirname(__FILE__) + "/config/environment")
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+
+EXTENSION_DIR = 'lib/extension/'
+extension = namespace :extension do
+  file "#{EXTENSION_DIR}/Makefile" do
+    run_in_build_environment do
+      sh 'ruby extconf.rb'
+    end
+  end
+  
+  file "#{EXTENSION_DIR}/minilab_hardware.c" => "#{EXTENSION_DIR}/Makefile"
+
+  file "#{EXTENSION_DIR}/minilab_hardware.so" => "#{EXTENSION_DIR}/minilab_hardware.c" do
+    run_in_build_environment do
+      sh 'nmake'
+    end
+  end
+
+  desc "Build the minilab_hardware extension"
+  task :build => "#{EXTENSION_DIR}/minilab_hardware.so"
+
+  desc "Clean out extension build artifacts"
+  task :clean do
+    run_in_build_environment do
+      sh 'nmake clean'
+      rm_f 'Makefile'
+      rm_f 'minilab_hardware-i386-mswin32.def'
+      rm_f 'mkmf.log'
+    end
+  end
+end
+
+test = namespace :test do
+  desc "Run the unit tests (doesn't require hardware)"
+  Rake::TestTask.new(:units => extension[:build]) do |t|
+    t.pattern = 'test/unit/**/*_test.rb'
+    t.verbose = true
+  end
+
+  desc "Run the integration tests (doesn't require hardware)"
+  Rake::TestTask.new(:integration => extension[:build]) do |t|
+    t.pattern = "test/integration/**/*_test.rb"
+    t.verbose = true
+  end
+
+  desc "Run the system tests (requires hardware)"
+  task :system => extension[:build] do
+    require 'systir'
+    require "#{SYSTEST_ROOT}/minilab_driver.rb"
+    result = Systir::Launcher.new.find_and_run_all_tests(MinilabDriver, SYSTEST_ROOT)
+    raise "SYSTEM TESTS FAILED" unless result.passed?
+  end
+
+  desc "Run every suite of tests"
+  task :all => [:units, :integration, :system]
+end
+
+desc "Compile the extension, run the unit tests, and run the integration tests"
+task :default => [extension[:build], test[:units], test[:integration]]
+
+def rdoc_options
+  [] << '--line-numbers' << '--inline-source' << '--main' << 'README' << '--title' << 'minilab' #<< "--op" << "rdoc"
+end
+
+gem_spec = Gem::Specification.new do |spec|
+  spec.name = "minilab"
+  spec.version = "1.0.0"
+  spec.author = "Matt Fletcher - Atomic Object, LLC"
+  spec.email = "fletcher@atomicobject.com"
+  spec.homepage = "http://atomicobject.com"
+  spec.platform = Gem::Platform::WIN32
+  spec.summary = "Ruby interface to Measurement Computing's miniLAB 1008"
+  spec.files = FileList["{test,config,vendor}/**/*"].exclude("rdoc").to_a
+  spec.files += FileList["lib/*"].exclude("rdoc").to_a
+  spec.files += ["Rakefile", "README", "LICENSE", "CHANGES", ".document"] 
+  spec.files += ["#{EXTENSION_DIR}/minilab_hardware.c", "#{EXTENSION_DIR}/minilab_hardware.so", "#{EXTENSION_DIR}/extconf.rb"]
+  spec.test_files = FileList["{test/unit,test/integration}/*"]
+  spec.has_rdoc = true
+  spec.extra_rdoc_files = ["README", "CHANGES", "LICENSE"]
+  spec.rdoc_options = rdoc_options
+end 
+  
+package_task = Rake::GemPackageTask.new(gem_spec) do |pkg|
+  pkg.need_tar = true
+  pkg.need_zip = true
+end
+
+task :package => extension[:build]
+
+desc "Clean the project of build artifacts"
+task :clean => [extension[:clean], Rake::Task[:clobber_package]]
+
+namespace :doc do
+  desc "Generate RDoc documentation"
+  Rake::RDocTask.new { |rdoc|
+    rdoc.rdoc_dir = 'rdoc'
+    rdoc.title    = "minilab: Ruby extension for the miniLAB 1008"
+    rdoc.options = rdoc_options
+    rdoc.rdoc_files.include('lib/minilab.rb', 'README','CHANGES','LICENSE')
+  }
+end
+
+private
+# These paths are all defaults for the Visual Studio .NET installation.
+# This stuff is not meant to work on anyone but Matt's laptop. Working anywhere else is purely coincidence.
+NEW_PATH_VARS = [
+  'C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\IDE',
+  'C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\bin',
+]
+
+NEW_INCLUDE_VARS = [
+  'C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\PlatformSDK\Include',
+  'C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\include',
+  'C:\MCC\C',
+]
+
+NEW_LIB_VARS = [
+  'C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\PlatformSDK\Lib',
+  'C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib',
+  'C:\MCC\C',
+]
+
+def run_in_build_environment
+  original_path = ENV['PATH']
+  original_include = ENV['INCLUDE']
+  original_lib = ENV['LIB']
+
+  begin
+    ENV['PATH'] = [NEW_PATH_VARS, ENV['PATH']].flatten.join(';')
+    ENV['INCLUDE'] = [NEW_INCLUDE_VARS, ENV['INCLUDE']].flatten.join(';')
+    ENV['LIB'] = [NEW_LIB_VARS, ENV['LIB']].flatten.join(';')
+
+    cd EXTENSION_DIR
+    yield
+  ensure
+    ENV['PATH'] = original_path
+    ENV['INCLUDE'] = original_include
+    ENV['LIB'] = original_lib
+
+    cd APP_ROOT
+  end
+end

data/config/environment.rb

@@ -0,0 +1,15 @@
+unless $environment_already_defined
+  APP_ROOT = File.expand_path(File.dirname(__FILE__) + "/..")
+  SYSTEST_ROOT = APP_ROOT + "/test/system"
+
+  [ 'lib',
+    'vendor/systir',
+    'vendor/hardmock/lib',
+    'vendor/behaviors/lib',
+    'vendor/constructor/lib',
+    'vendor/diy/lib',
+  ].each do |dir|
+    $LOAD_PATH << File.join(APP_ROOT, dir)
+  end
+  $environment_already_defined = true
+end

data/config/objects.yml

@@ -0,0 +1,22 @@
+minilab:
+  compose: minilab_hardware, result_verifier, analog_io, digital_auxport_io, digital_port_io
+
+minilab_hardware:
+  lib: extension/minilab_hardware
+
+result_verifier:
+  compose: minilab_hardware
+
+analog_io:
+  compose: minilab_hardware, result_verifier
+
+digital_auxport_io:
+  compose: minilab_hardware, result_verifier
+
+digital_port_io:
+  compose: minilab_hardware, result_verifier, digital_configuration, library_translator
+
+library_translator:
+
+digital_configuration:
+  compose: minilab_hardware, result_verifier

data/lib/analog_io.rb

@@ -0,0 +1,30 @@
+require 'constructor'
+
+class AnalogIo #:nodoc:
+  constructor :minilab_hardware, :result_verifier
+
+  def read_analog(channel)
+    check_channel_range(channel, 0, 7)
+
+    result = @minilab_hardware.read_analog(channel)
+    @result_verifier.verify(result, "read_analog")
+
+    result[:value]
+  end
+
+  def write_analog(channel, volts)
+    check_channel_range(channel, 0, 1)
+
+    unless (0.0 .. 5.0) === volts
+      raise "#{volts} volts is out of range for this device; Only voltage between 0.0 and 5.0 is supported."
+    end
+
+    result = @minilab_hardware.write_analog(channel, volts)
+    @result_verifier.verify(result, "write_analog")
+  end
+  
+  private
+  def check_channel_range(channel, low, high)
+    raise "Channel #{channel} is out of range." unless (low..high) === channel
+  end
+end

data/lib/digital_auxport_io.rb

@@ -0,0 +1,49 @@
+require 'constructor'
+require 'extension/minilab_hardware'
+
+class DigitalAuxportIo #:nodoc:
+  constructor :minilab_hardware, :result_verifier
+  include MinilabConstants
+
+  VALID_PINS = ['DIO0', 'DIO1', 'DIO2', 'DIO3']
+
+  def read_digital(pin)
+    check_pin_valid(pin)
+    pin = get_pin_number(pin)
+
+    configuration = {:direction => DIGITALIN, :pin => pin}
+    result = @minilab_hardware.configure_auxport(configuration)
+    @result_verifier.verify(result, "configure_auxport_in")
+
+    result = @minilab_hardware.read_auxport(pin)
+    @result_verifier.verify(result, "read_auxport")
+
+    result[:value]
+  end
+
+  def write_digital(pin, value)
+    check_pin_valid(pin)
+    pin = get_pin_number(pin)
+
+    raise "#{value} is not a valid digital output." if (value < 0)
+    value = 1 if (value > 0)
+
+    configuration = { :direction => DIGITALOUT, :pin => pin }
+    result = @minilab_hardware.configure_auxport(configuration)
+    @result_verifier.verify(result, "configure_auxport_out")
+
+    result = @minilab_hardware.write_auxport(pin, value)
+    @result_verifier.verify(result, "write_auxport")
+  end
+
+  private
+  def check_pin_valid(pin)
+    if !VALID_PINS.include?(pin.to_s.upcase)
+      raise "#{pin} is not a valid digital IO pin"
+    end
+  end
+
+  def get_pin_number(pin)
+    pin.match(/(\d)$/)[0].to_i
+  end
+end

data/lib/digital_configuration.rb

@@ -0,0 +1,66 @@
+require 'constructor'
+require 'extension/minilab_hardware'
+
+class DigitalConfiguration #:nodoc:
+  include MinilabConstants
+  constructor :minilab_hardware, :result_verifier
+
+  PORTS = [:porta, :portb, :portcl, :portch]
+  LIBRARY_PORT_NAMES = {
+    :porta => FIRSTPORTA,
+    :portb => FIRSTPORTB,
+    :portcl => FIRSTPORTCL,
+    :portch => FIRSTPORTCH
+  }
+
+  def setup
+    @port_status = {}
+    PORTS.each { |port| @port_status[port] = :not_configured }
+  end
+
+  def get_valid_ports
+    PORTS
+  end
+
+  def configure_port_for_input(port)
+    configure_port(port, DIGITALIN)
+  end
+
+  def configure_port_for_output(port)
+    configure_port(port, DIGITALOUT)
+  end
+
+  def is_port_configured_for_input?(port)
+    check_port_status(port, DIGITALIN)
+  end
+
+  def is_port_configured_for_output?(port)
+    check_port_status(port, DIGITALOUT)
+  end
+  
+  private
+  def is_port_recognized?(port)
+    if get_valid_ports.include?(port)
+      true
+    else
+      raise "Port #{port} is not valid."
+    end
+  end
+
+  def configure_port(port, direction)
+    is_port_recognized?(port)
+
+    result = @minilab_hardware.configure_port(:direction => direction, :port => LIBRARY_PORT_NAMES[port])
+    @result_verifier.verify(result)
+
+    @port_status[port] = direction
+    true
+  end
+
+  def check_port_status(port, status)
+    is_port_recognized?(port)
+
+    return false unless @port_status[port] == status
+    true
+  end
+end