Merge pull request #1 from DrGFreeman/in_work

Added Minimum example and improved documentation

.travis.yml

@@ -19,6 +19,6 @@ env:
 
 script:
 - set -eo pipefail;
-  for e in examples/*; do
+  for e in examples/Demo*; do
     platformio ci --board=$BOARD --lib=. $e/*;
   done

README.md

@@ -1,22 +1,25 @@
 # TimedPID
 A simple PID controller for the Arduino IDE featuring different time step calculation options.
 
-Version 0.1.0  
+Version 1.0.0  
 [![Build Status](https://travis-ci.org/DrGFreeman/TimedPID.svg?branch=master)](https://travis-ci.org/DrGFreeman/TimedPID)  
 By Julien de la Bruère-Terreault (drgfreeman@tuta.io)
 
 ## Summary
 
 This library for the Arduino IDE provides a simple [Proportional - Integral - Derivative (PID) controller](https://en.wikipedia.org/wiki/PID_controller). The controller features three options for time step calculation (the time step is used for integral and derivative error terms calculation):
 
-1. No time step (unit time step; `getCmd` method)
-1. Auto time step calculation (uses time between calls to `getCmdAutoStep` method)
-1. Pre-defined time step (passed as argument to `getCmdStep` method)
+1. Non-specified (unit) time step (`getCmd()` method)
+1. Auto time step calculation (uses time between calls to `getCmdAutoStep()` method)
+1. Defined time step (passed as argument to `getCmdStep()` method)
+
+## Examples
+Two example sketches are provided with the library:
+* _Minimum.ino_  
+This example shows the minimum code lines to declare, setup and get the command from the PID controller.
 
-## Example
-An example sketch is provided with the library:
 * _DemoTimedPID.ino_  
-This example shows how to use the library with a pre-defined time step.
+This example shows how to use the library with a defined time step. It includes a fake mechanical system simulation to demonstrate how the PID controls the force to apply on a mass object subject to inertial and drag forces to have the mass object achieve a desired speed function.
 
 ## Library Reference
 * `TimedPID(float Kp = 1.0, float Ki = 0.0, float Kd = 0.0)`  
@@ -29,7 +32,7 @@ Returns the system command. `setPoint` is the desired "target" value for the pro
 Similar to `getCmd` method except this method automatically calculates the time step based on the time between two calls to this method. The calculated time step is in seconds units.
 
 * `float getCmdStep(float setPoint, float procVar, float timeStep)`  
-Similar to `getCmdAutoStep` method except the time step is passed to the method via the `timeStep` argument.
+Similar to `getCmdAutoStep` method except the time step is passed to the method via the `timeStep` argument. The time step can be in any units.
 
 * `void reset()`  
 Resets the PID error terms. The method also resets to the current time the time variable used by the `getCmdAutoStep` to calculate the time step.
@@ -42,4 +45,4 @@ Sets the PID controller gains. `Kp`, `Ki` and `Kd` are the proportional, integra
 
 ## Version history
 
-* 0.1.0 (2017-04-22): Initial release for testing.
+* 1.0.0 (2017-04-25) Initial release

examples/DemoTimedPID/DemoTimedPID.ino

@@ -30,8 +30,8 @@ This example demonstrates how to use the TimedPID class to control the speed of
 a mass subject to inertial and drag forces by controlling the force applied to
 the mass. The controller reacts to changes in the desired speed.
 
-The getCmdStep() is used as the time step is calculated in the main loop and
-used to calculate the speed of the mass.
+The getCmdStep() is used in this case since the time step is calculated in the
+main loop and used to update the speed of the mass under acceleration.
 */
 
 #include <TimedPID.h>

examples/Minimum/Minimum.ino

@@ -0,0 +1,64 @@
+/*
+Minimum.ino
+Source: https://github.com/DrGFreeman/TimedPID
+
+MIT License
+
+Copyright (c) 2017 Julien de la Bruere-Terreault <drgfreeman@tuta.io>
+
+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.
+*/
+
+/*
+This example shows the minimum code lines to declare, setup and get the command
+from the PID controller.
+*/
+
+#include <TimedPID.h>
+
+/* Create a TimedPID object instance.
+Kp, Ki, Kd are floats representing the proportional, integral and derivative
+gains respectively. */
+TimedPID pid(Kp, Ki, Kd);
+
+void setup() {
+  /* Optional: Set min and max PID command values.
+  minValue and maxValue arguments are floats representing the min and max
+  command values that the PID controller can produce.
+  Uncomment the following line to use this option. */
+  // pid.setCmdRange(minValue, maxValue);
+}
+
+void loop() {
+  /* Get the PID command
+  cmd is a variable to store the PID command.
+  setPoint is the desired "target" value for the controlled process variable.
+  procVar is the current value of the process variable being controlled.
+
+  getCmd() method uses unit time step. */
+  float cmd = pid.getCmd(setPoint, procVar);
+
+  /* Alternatively, use getCmdAutoStep() method to have the PID controller
+  automatically calculate the time step between calls to the method. */
+  // float cmd = pid.getCmdAutoStep(setPoint, procVar);
+
+  /* Alternatively, use getCmdStep() method to have the PID controller use the
+  time step defined by timeStep. */
+  // float cmd = pid.getCmdStep(setPoint, procVar, timeStep);
+}

library.properties

@@ -1,9 +1,9 @@
 name=TimedPID
-version=0.0.1
+version=1.0.0
 author=Julien de la Bruere-Terreault, drgfreeman@tuta.io
 maintainer=Julien de la Bruere-Terreault, drgfreeman@tuta.io
 sentence=PID controller
 paragraph=A simple PID controller for the Arduino IDE featuring different time step calculation options.
 category=Data Processing
-url=https://github.com/DrGFreeman/PID
+url=https://github.com/DrGFreeman/TimedPID
 architectures=avr