temper-control 0.0.1

data/.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

data/Gemfile

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

data/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.

data/README.md

@@ -0,0 +1,67 @@
+# 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-control', require: 'temper'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install temper-control
+
+## 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.
+
+### Minimum Interval Calculation
+
+The algorithm being used is minimum 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 with the `interval` option.
+
+### Directional Control
+
+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.
+
+### Tuning
+
+Temper's PID is manually tuned with the `tune` method, which takes a Kp, Ki, and Kd value. By
+default, Temper will set them to 1.0
+
+## Example
+
+``` ruby
+require 'temper'
+
+temper = Temper::PID.new(interval: 1000, minimum: 0, maximum: 1000, direction: :direct)
+temper.tune(9.0, 25.0, 6.0) # Set Kp, Ki, and Kd
+temper.setpoint = 100.0       # Set 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

data/Rakefile

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

data/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

data/lib/temper/version.rb

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

data/spec/spec_helper.rb

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

data/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

data/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-control"
+  gem.version       = Temper::VERSION
+  gem.authors       = ["Andrew Nordman"]
+  gem.email         = ["cadwallion@gmail.com"]
+  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

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification
+name: temper-control
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Andrew Nordman
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: Temperature Controller Library
+email:
+- cadwallion@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/temper.rb
+- lib/temper/version.rb
+- spec/spec_helper.rb
+- spec/temper_spec.rb
+- temper.gemspec
+homepage: ''
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Temperature controller based on the PID algorithm
+test_files:
+- spec/spec_helper.rb
+- spec/temper_spec.rb