Initial Commit

.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

Gemfile

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

LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Andrew Nordman
+
+MIT License
+
+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.

README.md

@@ -0,0 +1,55 @@
+# Temper
+
+Temperature controlling is easy with Temper.  It uses an improved PID algorithm to
+decrease overshoots and regulate based on continued inputs.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'temper'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install temper
+
+## Usage
+
+To start, create an instance of Temper::PID.  The PID algorithm can be configured with
+custom minimum and maximum values for ease of integration with external control systems
+(PWM-controlled heating elements, for example).  Once created, run `Temper::PID#control`
+in your control loop, feeding it sensor data.
+
+The algorithm being used is fixed interval and will not recalibrate until the time interval
+has passed before recalibrating.  This helps mitigate excess compensation and inconsistent
+adjustment. The update interval is also configurable in temper.
+
+Finally, when handling cooling-based temperature control, negative values are a pain for
+translation.  To assist with this, Temper uses a directional control parameter.  The two
+possible states are `:direct` and `:reverse`.  When using `:reverse`, negative values
+are inverted.
+
+## Example
+
+``` ruby
+temper = Temper::PID.new(interval: 1000, minimum: 0, maximum: 1000, direction: :direct)
+temper.setpoint = 100.0 # Target temperature
+
+while input = read_sensor() # Replace read_sensor with your external system
+  output = temper.control(input)
+  # output is a value betwen minimum and maximum. This can be used for thresholds or
+  # PWM-based control
+end
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

lib/temper.rb

@@ -0,0 +1,109 @@
+require "temper/version"
+
+module Temper
+  class PID
+    attr_accessor :kp, :ki, :kd, :setpoint, :direction, :output
+
+    def initialize options = {}
+      @interval = options[:interval] || 1000
+      @last_time = 0.0
+      @last_input = 0.0
+      @integral_term = 0.0
+      @output_maximum = options[:maximum] || 1000
+      @output_minimum = options[:minimum] || 0
+
+      set_mode options[:mode] || :auto
+      set_direction options[:direction] || :direct
+    end
+
+    def control input
+      return if !@auto # manual mode
+
+      now = Time.now.to_f
+      time_change = (now - @last_time) * 1000
+
+      if time_change >= @interval
+        error = @setpoint - input
+
+        calculate_proportional error
+        calculate_integral error
+        calculate_derivative input
+
+        calculate_output
+
+        @last_time = now
+        @last_input = input
+
+        @output
+      end
+    end
+
+    def calculate_proportional error
+      @proportional_term = @kp * error
+    end
+
+    def calculate_integral error
+      @integral_term += @ki * error
+
+      if @integral_term > @output_maximum
+        @integral_term = @output_maximum
+      elsif @integral_term < @output_minimum
+        @integral_term = @output_minimum
+      end
+    end
+
+    def calculate_derivative input
+      @derivative_term = @kd * (input - @last_input)
+    end
+
+    def calculate_output
+      @output = @proportional_term + @integral_term - @derivative_term
+
+      if @output > @output_maximum
+        @output = @output_maximum
+      elsif @output < @output_minimum
+        @output = @output_minimum
+      end
+
+      @output
+    end
+
+    def tune kp, ki, kd
+      return if kp < 0 || ki < 0 || kd < 0
+
+      interval_seconds = (@interval / 1000.0)
+
+      @kp = kp
+      @ki = ki * interval_seconds
+      @kd = kd / interval_seconds
+
+      if @direction != :direct
+        @kp = 0 - @kp
+        @ki = 0 - @ki
+        @kd = 0 - @kd
+      end
+    end
+
+    def update_interval new_interval
+      if new_interval > 0
+        ratio = new_interval / @interval
+
+        @ki *= ratio
+        @kd /= ratio
+        @interval = new_interval
+      end
+    end
+
+    def set_mode mode
+      @auto = mode == :auto
+    end
+
+    def set_direction direction
+      @direction = direction
+    end
+
+    def mode
+      @auto ? :auto : :manual
+    end
+  end
+end

lib/temper/version.rb

@@ -0,0 +1,3 @@
+module Temper
+  VERSION = "0.0.1"
+end

spec/spec_helper.rb

@@ -0,0 +1,3 @@
+$:.push File.join(File.dirname(__FILE__), '..', 'lib')
+
+require 'temper'

spec/temper_spec.rb

@@ -0,0 +1,25 @@
+require 'spec_helper'
+
+describe Temper::PID do
+  before do
+    controller.setpoint = 100.0
+    controller.tune 1.0, 1.0, 1.0
+  end
+
+  let(:controller) { Temper::PID.new }
+  subject { controller }
+
+  its(:kp) { should == 1.0 }
+  its(:ki) { should == 1.0 }
+  its(:kd) { should == 1.0 }
+  its(:mode) { should == :auto }
+  its(:direction) { should == :direct }
+
+  context 'computing data' do
+    before do
+      controller.control 50.0
+    end
+
+    its(:output) { should == 50.0 }
+  end
+end

temper.gemspec

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'temper/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "temper"
+  gem.version       = Temper::VERSION
+  gem.authors       = ["Andrew Nordman"]
+  gem.email         = ["[email protected]"]
+  gem.description   = %q{Temperature Controller Library}
+  gem.summary       = %q{Temperature controller based on the PID algorithm}
+  gem.homepage      = ""
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+
+  gem.add_development_dependency 'rspec'
+end