device_control 0.0.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cf0616f0c1a9a604310b793eea313261cc6f70ecefe3a401ae3df83b973a4f45
+  data.tar.gz: 7ad33892bf3ad7420d4c72f3c94efe0aa9861889427d1028cba27a2fd1bc9fb1
+SHA512:
+  metadata.gz: 1c71afb1964f420e16fa7941e7470cf33c19183218d3bb97f040f34047d653b3e52d1f86e2874ff96997caf5de38a9902f9d4e112f25a516bd1e316da40f79c3
+  data.tar.gz: a24a1a3e8d7dd72b3f30a4470f5cff0a5590c1c7ec00c76b711e5c91d9e799386182477a1400f57d3a2d701375ecfa417c11fcf36d8e3bbde9f09d75d50db802

data/README.md

@@ -0,0 +1,251 @@
+[![Test Status](https://github.com/rickhull/device_control/actions/workflows/test.yaml/badge.svg)](https://github.com/rickhull/device_control/actions/workflows/test.yaml)
+
+# Rationale
+
+At present, this library scratches the itch of implementing a simple PID
+controller.  It builds up to this with some simple abstractions that can
+also be used to build other, more sophisticated controllers.
+
+# Concepts
+
+## Controller
+
+A controller is a piece of equipment (or, more abstractly, perhaps even a
+human operator) that is intended to achieve a certain measurement from the
+environment.  For example, a thermostat wants to maintain a temperature, or
+the cruise control in your car wants to maintain a certain wheelspeed.
+
+A thermostat on its own cannot (meaningfully) affect the environment; it is
+just a controller, presumably for some other device, like a heater.  The
+thermostat, if hooked up to a heating device, can control when the heat
+comes on, and this changes the measurement from the environment, ideally
+towards the desired temperature.
+
+## Device
+
+I'm not sure about the actual nomenclature from a very rich field of study,
+*control theory*, but I'm using the term "device" to describe that which the
+controller is controlling.  So a heater or a refrigerator may be the device,
+or the throttle on an engine, or a broomstick balanced on a pencil eraser.
+
+A controller requires a device, and a device must have some variable input,
+like a control knob, which the controller can thus manipulate.  The device
+presumably reacts to the input with a new output, and this output presumably
+affects the environment in some way that the controller can measure.
+
+## Environment
+
+The environment, in some way, connects the output of the device back to
+the measurement on the controller.  Often, in order to test a device or a
+controller (or both), the environment must be modeled or simulated, often
+crudely.  Or perhaps the environment is already inherent to the problem, or
+it has been modeled extensively as part of the problem.
+
+This project will make little or no effort to model your environment.  But
+it's important to recognize that you have to "close the loop" for any of this
+to make sense.
+
+# Approach
+
+## Control Loop
+
+Our control loop is composed of the 3 concepts above:
+
+```
+CONTROLLER  ==>  DEVICE
+        ^         |
+        |         |
+        |         V
+        ENVIRONMENT
+```
+
+### A Pattern
+
+Each component accepts an input and yields an output.  Controllers accept
+a measure and yield a control value.  Devices accept a control value and yield
+an environmental output.  The environment accepts the new output and produces
+a new measure for the controller.
+
+```ruby
+module Updateable
+  def update(val)
+    self.input = val
+    self.output
+  end
+end
+```
+
+Notice, this is a module, not a class.  This module is intended to be mixed in
+to a class in order provide (and guarantee) the pattern of behavior.  Any
+class which wants to mix in `Updateable` should thus, at minimum, define:
+
+* `initialize`
+* `input=`
+* `output`
+
+Note that the class can use any ivars; there is no need to create or ever
+touch `@input` if a different ivar name is preferred.
+
+### Device
+
+```ruby
+class Device
+  include Updateable
+
+  attr_reader :knob
+
+  def initialize
+    @knob = 0.0
+  end
+
+  def input=(val)
+    @knob = val.to_f
+  end
+  alias_method :knob=, :input=
+
+  def output
+    @knob # do nothing by default
+  end
+
+  def to_s
+    format("Knob: %.3f\tOutput: %.3f", @knob, self.output)
+  end
+end
+```
+
+We've named our class `Device`, mixed in `Updateable`, and we've named our input
+`knob`.  In general, we will operate only on Floats for inputs and outputs,
+though perhaps interesting things can be done outside this limitation.
+
+`@knob` is initialized to zero, and `input=(val)` will update `@knob`.  As
+this is a generic device, we will just pass along the input as our output.
+Let's also make a friendly string output.
+
+#### Heater
+
+```ruby
+class Heater < Device
+  # convert electricity into thermal output
+  EFFICIENCY = 0.999
+
+  attr_reader :watts
+
+  def initialize(watts, threshold: 0)
+    super()
+    @watts = watts
+    @threshold = threshold
+  end
+
+  # output is all or none
+  def output
+    @knob > @threshold ? (@watts * self.class::EFFICIENCY) : 0
+  end
+
+  def to_s
+    format("Power: %d W\tKnob: %.1f\tThermal: %.1f W",
+           @watts, @knob, self.output)
+  end
+end
+```
+
+Starting with a generic device, we'll add `@watts` for output, and we'll also
+allow a configurable threshold for the knob -- *at what point does the knob
+turn to on?*  By default, anything above 0.
+
+BTW, this is a crude model, as `@watts` sort of represents the input energy,
+and we are representing its output as "the amout of heat that 1000 watts
+(or whatever) puts out".  Since electric devices waste power by shedding heat,
+electric heaters are very efficient by definition.  It's not difficult to dump
+all your power into heat; just use a big resistor.
+
+#### Cooler
+
+```ruby
+class Cooler < Heater
+  # not nearly as efficient as a heater at turning electrons into therms
+  EFFICIENCY = 0.35
+end
+```
+
+A cooler is just a heater that puts out watts of cooling.  You'd have to
+model the inverse effect in your environment.  You can of course create more
+sophisticated Heater and Cooler models as well ;)
+
+### Controller
+
+```ruby
+class Controller
+  include Updateable
+
+  attr_reader :measure
+  attr_accessor :setpoint
+
+  def initialize(setpoint)
+    @setpoint, @measure = setpoint, 0.0
+  end
+
+  def input=(val)
+    @measure = val.to_f
+  end
+  alias_method :measure=, :input=
+
+  # just output the error
+  def output
+    @setpoint - @measure
+  end
+
+  def to_s
+    format("Setpoint: %.3f\tMeasure: %.3f", @setpoint, @measure)
+  end
+end
+```
+
+A Controller names its input `measure`, and it introduces a `setpoint`, and
+the difference between setpoint and measure is the error.
+
+#### Thermostat
+
+```ruby
+class Thermostat < Controller
+  # true or false; can drive a Heater or a Cooler
+  # true means input below setpoint; false otherwise
+  def output
+    @setpoint - @measure > 0
+  end
+end
+```
+
+Now consider:
+
+```ruby
+
+h = Heater.new(1000)
+ht = Thermostat.new(20)
+c = Cooler.new(1000)
+ct = Thermostat.new(25)
+
+temp = 26.4
+
+heat_knob = ht.update(temp) ? 1 : 0
+heating_watts = h.update(heat_knob)
+cool_knob = ct.update(temp) ? 0 : 1
+cooling_watts = c.update(cool_knob)
+
+temp = 24.9
+
+# ...
+
+```
+
+Notice, the thermostat essentially answers the question: *is it hot enough?*
+(or: *is it too cold?*).  You can run it either or both ways, but notice that
+you can simply pick one orientation and remain logically consistent.  So the
+**heat knob** goes to 1 when its thermostat goes *below* setpoint.
+The **cool knob** goes to 1 when its thermostat goes *above* setpoint.
+
+# Finale
+
+If you've made it this far, congratulations!  For further reading:
+
+* [lib/pid_controller.rb](lib/pid_controller.rb#L155)
+* [test/pid_controller.rb](test/pid_controller.rb)

data/Rakefile

@@ -0,0 +1,22 @@
+require 'rake/testtask'
+
+Rake::TestTask.new :test do |t|
+  t.pattern = "test/*.rb"
+  t.warning = true
+end
+
+#
+# GEM BUILD / PUBLISH
+#
+
+begin
+  require 'buildar'
+
+  Buildar.new do |b|
+    b.gemspec_file = 'device_control.gemspec'
+    b.version_file = 'VERSION'
+    b.use_git = true
+  end
+rescue LoadError
+  warn "buildar tasks unavailable"
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.0.3

data/device_control.gemspec

@@ -0,0 +1,17 @@
+Gem::Specification.new do |s|
+  s.name = 'device_control'
+  s.summary = "WIP"
+  s.description = "WIP"
+  s.authors = ["Rick Hull"]
+  s.homepage = "https://github.com/rickhull/device_control"
+  s.license = "LGPL-3.0"
+
+  s.required_ruby_version = "> 2"
+
+  s.version = File.read(File.join(__dir__, 'VERSION')).chomp
+
+  s.files = %w[device_control.gemspec VERSION README.md Rakefile]
+  s.files += Dir['lib/**/*.rb']
+  s.files += Dir['test/**/*.rb']
+  s.files += Dir['demo/**/*.rb']
+end

data/lib/pid_controller.rb

@@ -0,0 +1,267 @@
+# There is a pattern for how both Controllers (e.g. thermostat) and Devices
+#   (e.g. heater) operate.
+# They each have an _input_ varying over time which determines the _output_.
+# A thermostat (Controller) listens for  temperature and tells the heater how
+# high to turn it up (or just on / off).  A heater (Device) listens to its
+# control knob and yields heat as an output.
+#
+# We capture this pattern with a single method: _update_.  It accepts the
+# latest input and provides an _output_ based on the input. When the input
+# is read in, perhaps some internal state is changed on
+# the processor which will affect the _output_.
+#
+# Any class which mixes in Updateable can define its own _input=_ method,
+# which may update any ivars.  Any such class must define an _output_ method.
+#
+module Updateable
+  def update(val)
+    self.input = val
+    self.output
+  end
+end
+
+# A Device is like a heater.  It has a control knob, maybe on/off or perhaps
+# a variable control.  Its output (maybe on/off) depends on the control knob.
+class Device
+  include Updateable
+
+  attr_reader :knob
+
+  def initialize
+    @knob = 0.0
+  end
+
+  def input=(val)
+    @knob = val.to_f
+  end
+  alias_method :knob=, :input=
+
+  def output
+    @knob # do nothing by default
+  end
+
+  def to_s
+    format("Knob: %.3f\tOutput: %.3f", @knob, self.output)
+  end
+end
+
+# Alright, fine, let's make a Heater
+# Input is the control knob (turned far enough to on, else off)
+# Output is watts
+class Heater < Device
+  # convert electricity into thermal output
+  EFFICIENCY = 0.999
+
+  attr_reader :watts
+
+  def initialize(watts, threshold: 0)
+    super()
+    @watts = watts
+    @threshold = threshold
+  end
+
+  # output is all or none
+  def output
+    @knob > @threshold ? (@watts * self.class::EFFICIENCY) : 0
+  end
+
+  def to_s
+    format("Power: %d W\tKnob: %.1f\tThermal: %.1f W",
+           @watts, @knob, self.output)
+  end
+end
+
+class Cooler < Heater
+  # not nearly as efficient as a heater at turning electrons into therms
+  EFFICIENCY = 0.35
+end
+
+# A Controller is like a thermostat.  It has a setpoint, and it reads a
+# measurement from the environment, and it adjusts its output to try to make
+# the measurement match the setpoint.
+class Controller
+  include Updateable
+
+  attr_reader :measure
+  attr_accessor :setpoint
+
+  def initialize(setpoint)
+    @setpoint, @measure = setpoint, 0.0
+  end
+
+  def input=(val)
+    @measure = val.to_f
+  end
+  alias_method :measure=, :input=
+
+  # just output the error
+  def output
+    @setpoint - @measure
+  end
+
+  def to_s
+    format("Setpoint: %.3f\tMeasure: %.3f", @setpoint, @measure)
+  end
+end
+
+class Thermostat < Controller
+  # true or false; can drive a Heater or a Cooler
+  # true means input below setpoint; false otherwise
+  def output
+    @setpoint - @measure > 0
+  end
+end
+
+class Flexstat < Thermostat
+  def self.cold_val(hot_val)
+    case hot_val
+    when true, false
+      !hot_val
+    when 0,1
+      hot_val == 0 ? 1 : 0
+    when Numeric
+      0
+    when :on, :off
+      hot_val == :on ? :off : :on
+    else
+      raise "#{hot_val.inspect} not recognized"
+    end
+  end
+
+  def initalize(hot_val: false, cold_val: nil)
+    @hot_val = hot_val
+    @cold_val = cold_val.nil? ? self.class.cold_val(hot_val) : cold_val
+  end
+
+  def output
+    super ? @cold_val : @hot_val
+  end
+end
+
+# now consider e.g.
+# h = Heater.new(1000)
+# ht = Thermostat.new(20)
+# c = Cooler.new(1000)
+# ct = Thermostat.new(25)
+# temp = 26.4
+# heat_knob = ht.update(temp) ? 1 : 0
+# heating_watts = h.update(heat_knob)
+# cool_knob = ct.update(temp) ? 0 : 1
+# cooling_watts = c.update(cool_knob)
+# etc
+
+# A StatefulController tracks its error over time: current, last, accumulated
+#
+class StatefulController < Controller
+  HZ = 1000
+  TICK = Rational(1) / HZ
+
+  attr_accessor :dt
+  attr_reader :error, :last_error, :sum_error
+
+  def initialize(setpoint, dt: TICK)
+    super(setpoint)
+    @dt = dt
+    @error, @last_error, @sum_error = 0.0, 0.0, 0.0
+  end
+
+  # update @error, @last_error, and @sum_error
+  def input=(val)
+    @measure = val
+    @last_error = @error
+    @error = @setpoint - @measure
+    if @error * @last_error <= 0  # zero crossing; reset the accumulated error
+      @sum_error = @error * @dt
+    else
+      @sum_error += @error * @dt
+    end
+  end
+
+  def to_s
+    [super,
+     format("Error: %+.3f\tLast: %+.3f\tSum: %+.3f",
+            @error, @last_error, @sum_error),
+    ].join("\n")
+  end
+end
+
+# A PIDController is a StatefulController that calculates
+# * Proportion (current error)
+# * Integral   (accumulated error)
+# * Derivative (error slope, last_error)
+# The sum of these terms is the output
+#
+class PIDController < StatefulController
+  # Ziegler-Nichols method for tuning PID gain knobs
+  # https://en.wikipedia.org/wiki/Ziegler%E2%80%93Nichols_method
+  ZN = {
+    #           Kp     Ti    Td     Ki     Kd
+    #     Var:  Ku     Tu    Tu    Ku/Tu  Ku*Tu
+    'P'    => [1/2r],
+    'PI'   => [9/20r, 4/5r,   nil, 27/50r],
+    'PD'   => [ 4/5r,  nil,  1/8r,  nil, 1/10r],
+    'PID'  => [ 3/5r, 1/2r,  1/8r, 6/5r, 3/40r],
+    'PIR'  => [7/10r, 2/5r, 3/20r, 7/4r, 21/200r],
+    # less overshoot than standard PID
+    'some' => [ 1/3r, 1/2r,  1/3r, 2/3r, 1/11r],
+    'none' => [ 1/5r, 1/2r,  1/3r, 2/5r, 2/30r],
+  }
+
+  # _ku_ = ultimate gain, _tu_ = oscillation period
+  # output includes ti and td, which are not necessary
+  # typically kp, ki, and kd are used
+  def self.tune(type, ku, tu)
+    record = ZN[type.downcase] || ZN[type.upcase] || ZN.fetch(type)
+    kp, ti, td, ki, kd = *record
+    kp *= ku if kp
+    ti *= tu if ti
+    td *= tu if td
+    ki *= (ku / tu) if ki
+    kd *= (ku * tu) if kd
+    { kp: kp, ti: ti, td: td, ki: ki, kd: kd }
+  end
+
+  attr_accessor :kp, :ki, :kd, :p_range, :i_range, :d_range, :o_range
+
+  def initialize(setpoint, dt: TICK)
+    super
+
+    # gain / multipliers for PID; tunables
+    @kp, @ki, @kd = 1.0, 1.0, 1.0
+
+    # optional clamps for PID terms and output
+    @p_range = (-Float::INFINITY..Float::INFINITY)
+    @i_range = (-Float::INFINITY..Float::INFINITY)
+    @d_range = (-Float::INFINITY..Float::INFINITY)
+    @o_range = (-Float::INFINITY..Float::INFINITY)
+
+    yield self if block_given?
+  end
+
+  def output
+    (self.proportion +
+     self.integral +
+     self.derivative).clamp(@o_range.begin, @o_range.end)
+  end
+
+  def proportion
+    (@kp * @error).clamp(@p_range.begin, @p_range.end)
+  end
+
+  def integral
+    (@ki * @sum_error).clamp(@i_range.begin, @i_range.end)
+  end
+
+  def derivative
+    (@kd * (@error - @last_error) / @dt).clamp(@d_range.begin, @d_range.end)
+  end
+
+  def to_s
+    super +
+      [format(" Gain:\t%.3f\t%.3f\t%.3f",
+              @kp, @ki, @kd),
+       format("  PID:\t%+.3f\t%+.3f\t%+.3f\t= %.5f",
+              self.proportion, self.integral, self.derivative, self.output),
+      ].join("\n")
+  end
+end

data/test/pid_controller.rb

@@ -0,0 +1,283 @@
+require 'pid_controller'
+require 'minitest/autorun'
+
+# create a basic class that includes Updateable as a Mixin
+# the class should define #initialize, #input= and #output at minimum
+class Doubler
+  include Updateable
+
+  attr_accessor :input
+
+  def initialize
+    @input = 0.0
+  end
+
+  def output
+    @input * 2
+  end
+end
+
+describe Updateable do
+  describe "a mixin that provides the _update_ pattern" do
+    before do
+      @o = Doubler.new
+    end
+
+    it "has an _update_ method that accepts an _input_ and returns _output_" do
+      expect(@o.input).must_equal 0.0
+      expect(@o.output).must_equal 0.0
+
+      output = @o.update(45)
+      expect(@o.input).must_equal 45
+      expect(@o.output).must_equal output
+    end
+
+    it "requires an _output_ method" do
+      k = Class.new(Object) do
+        include Updateable
+      end
+      o = k.new
+      expect { o.update(45) }.must_raise NoMethodError
+    end
+  end
+end
+
+describe Device do
+  before do
+    @device = Device.new
+  end
+
+  it "has an _output_" do
+    expect(@device.output).must_be_kind_of Float
+  end
+
+  it "has a string representation" do
+    expect(@device.to_s).must_be_kind_of String
+  end
+
+  it "has an _update_ method from Updateable" do
+    expect(@device.update(2.34)).must_be_kind_of Float
+  end
+end
+
+describe Heater do
+  before do
+    @h = Heater.new(1000)
+  end
+
+  it "has an _output_ when _knob_ is greater than zero" do
+    expect(@h.knob).must_equal 0
+    expect(@h.output).must_equal 0
+    @h.knob = 1
+    expect(@h.output).must_be :>, 0
+  end
+
+  it "has a string representation" do
+    expect(@h.to_s).must_be_kind_of String
+  end
+
+  it "has _update_ from Updateable" do
+    expect(@h.knob).must_equal 0
+    expect(@h.output).must_equal 0
+    output = @h.update(1)
+    expect(output).must_be :>, 0
+    expect(@h.knob).must_equal 1
+    expect(@h.output).must_equal output
+  end
+end
+
+describe Controller do
+  before do
+    @sp = 500
+    @c = Controller.new(@sp)
+  end
+
+  it "has an _output_, the difference between setpoint and measure" do
+    expect(@c.output).must_be_kind_of Float
+    expect(@c.output).must_equal @sp
+  end
+
+  it "has a string representation" do
+    expect(@c.to_s).must_be_kind_of String
+  end
+
+  it "has an _update_ method from Updateable" do
+    expect(@c.update(499)).must_equal 1.0
+  end
+end
+
+describe Thermostat do
+  before do
+    @t = Thermostat.new 25
+  end
+
+  it "outputs true when it's too cold; when measure < setpoint" do
+    expect(@t.update 20).must_equal true
+    expect(@t.update 30).must_equal false
+  end
+
+  it "outputs false when it's too hot; when measure > setpoint" do
+    expect(@t.update 30).must_equal false
+    expect(@t.update 20).must_equal true
+  end
+end
+
+describe StatefulController do
+  it "tracks error, last_error, sum_error" do
+    sc = StatefulController.new(100)
+    expect(sc.error).must_equal 0.0
+    expect(sc.last_error).must_equal 0.0
+    expect(sc.sum_error).must_equal 0.0
+
+    output = sc.update 50
+    expect(sc.output).must_equal output
+    expect(sc.measure).must_equal 50
+    expect(sc.error).must_be_within_epsilon 50.0
+    expect(sc.last_error).must_equal 0.0
+    expect(sc.sum_error).must_be_within_epsilon(50.0 * sc.dt)
+
+    output = sc.update 75
+    expect(sc.output).must_equal output
+    expect(sc.measure).must_equal 75
+    expect(sc.error).must_be_within_epsilon 25.0
+    expect(sc.last_error).must_be_within_epsilon 50.0
+    expect(sc.sum_error).must_be_within_epsilon(75.0 * sc.dt)
+  end
+
+  it "resets sum_error after crossing setpoint" do
+    sc = StatefulController.new(100)
+    sc.update 50
+    sc.update 75
+    expect(sc.sum_error).must_be_within_epsilon(75.0 * sc.dt)
+    sc.update 125
+    expect(sc.error).must_equal(-25.0)
+    expect(sc.sum_error).must_equal(sc.error * sc.dt)
+  end
+end
+
+describe PIDController do
+  it "informs Ziegler-Nichols tuning" do
+    # P only, not PID
+    hsh = PIDController.tune('P', 5, 0.01)
+    expect(hsh[:kp]).must_be :>, 0
+    expect(hsh[:ki]).must_be_nil
+    expect(hsh[:kd]).must_be_nil
+    expect(hsh[:ti]).must_be_nil
+    expect(hsh[:td]).must_be_nil
+
+    hsh = PIDController.tune('PI', 5, 0.01)
+    expect(hsh[:kp]).must_be :>, 0
+    expect(hsh[:ki]).must_be :>, 0
+    expect(hsh[:kd]).must_be_nil
+    expect(hsh[:ti]).must_be :>, 0
+    expect(hsh[:td]).must_be_nil
+
+    hsh = PIDController.tune('PID', 5, 0.01)
+    expect(hsh[:kp]).must_be :>, 0
+    expect(hsh[:ki]).must_be :>, 0
+    expect(hsh[:kd]).must_be :>, 0
+    expect(hsh[:ti]).must_be :>, 0
+    expect(hsh[:td]).must_be :>, 0
+  end
+
+  it "has an optional _dt_ argument to initialize" do
+    pid = PIDController.new(1000, dt: 0.1)
+    expect(pid).must_be_kind_of PIDController
+    expect(pid.setpoint).must_equal 1000
+    expect(pid.dt).must_equal 0.1
+  end
+
+  it "has PID gain settings" do
+    pid = PIDController.new(1000)
+    expect(pid.kp).must_be :>, 0
+    pid.kp = 1000
+    expect(pid.kp).must_equal 1000
+    pid.ki = 1000
+    expect(pid.ki).must_equal 1000
+    pid.kd = 1000
+    expect(pid.kd).must_equal 1000
+  end
+
+  it "clamps the _proportion_ term" do
+    pid = PIDController.new(1000)
+    pid.p_range = (0..1)
+    pid.update(500)
+    expect(pid.proportion).must_equal 1.0
+    pid.update(1500)
+    expect(pid.proportion).must_equal 0.0
+  end
+
+  it "clamps the _integral_ term" do
+    pid = PIDController.new(1000)
+    pid.i_range = (-1.0 .. 1.0)
+    pid.setpoint = 10_000
+    pid.update(500)
+    expect(pid.integral).must_equal 1.0
+    pid.update(10_001)
+    pid.update(20_000)
+    expect(pid.integral).must_equal(-1.0)
+  end
+
+  it "clamps the _derivative_ term" do
+    pid = PIDController.new(1000)
+    pid.d_range = (-1.0 .. 0.0)
+    pid.update(0)
+    pid.update(10)
+    expect(pid.derivative).must_equal(-1.0)
+    pid.update(990)
+    expect(pid.derivative).must_equal(-1.0)
+    pid.update(1000)
+    pid.update(990)
+    expect(pid.derivative).must_equal(0.0)
+  end
+
+  it "clamps the _output_" do
+    pid = PIDController.new(1000)
+    pid.o_range = (0.0 .. 1.0)
+    pid.update(0)
+    expect(pid.output).must_equal(1.0)
+    pid.update(2000)
+    expect(pid.output).must_equal(0.0)
+  end
+
+  it "calculates _proportion_ based on current error" do
+    pid = PIDController.new(1000)
+    pid.kp = 1.0
+    pid.update(0)
+    expect(pid.proportion).must_equal 1000.0
+    pid.update(1)
+    expect(pid.proportion).must_equal 999.0
+    pid.update(1001)
+    expect(pid.proportion).must_equal(-1.0)
+  end
+
+  it "calculates _integral_ based on accumulated error" do
+    pid = PIDController.new(1000)
+    pid.ki = 1.0
+    pid.update(0)
+    # sum error should be 1000; dt is 0.001
+    expect(pid.integral).must_equal(1.0)
+    pid.update(999)
+    expect(pid.integral).must_be_within_epsilon(1.001)
+    pid.update(1100) # zero crossing
+    expect(pid.integral).must_be_within_epsilon(-0.1)
+  end
+
+  it "calculates _derivative_ based on error slope" do
+    pid = PIDController.new(1000)
+    pid.kp = 1.0
+    pid.update(0)
+    # error should be 1000; last_error 0
+    expect(pid.derivative).must_equal(1_000_000)
+    pid.update(500)
+    expect(pid.derivative).must_equal(-500_000)
+    pid.update(999)
+    expect(pid.derivative).must_equal(-499_000)
+    pid.update(1001)
+    expect(pid.derivative).must_equal(-2000)
+    pid.update(1100)
+    expect(pid.derivative).must_equal(-99_000)
+    pid.update(900)
+    expect(pid.derivative).must_equal(200_000)
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: device_control
+version: !ruby/object:Gem::Version
+  version: 0.0.0.3
+platform: ruby
+authors:
+- Rick Hull
+autorequire:
+bindir: bin
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies: []
+description: WIP
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- Rakefile
+- VERSION
+- device_control.gemspec
+- lib/pid_controller.rb
+- test/pid_controller.rb
+homepage: https://github.com/rickhull/device_control
+licenses:
+- LGPL-3.0
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: '2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.26
+signing_key:
+specification_version: 4
+summary: WIP
+test_files: []