Pulses.h

00001 /* 
00002 * @author Jochen Krapf
00003 *
00004 * @section LICENSE
00005 *
00006 * Copyright (c) 2012 Jochen Krapf, MIT License
00007 *
00008 * Permission is hereby granted, free of charge, to any person obtaining a copy of this software
00009 * and associated documentation files (the "Software"), to deal in the Software without restriction,
00010 * including without limitation the rights to use, copy, modify, merge, publish, distribute,
00011 * sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
00012 * furnished to do so, subject to the following conditions:
00013 *
00014 * The above copyright notice and this permission notice shall be included in all copies or
00015 * substantial portions of the Software.
00016 *
00017 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
00018 * BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
00019 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
00020 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00021 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
00022 *
00023 * @section DESCRIPTION
00024 * mbed Pulses Library, for measurement of low frequencys based on timing between pulses
00025 *
00026 * Use cases:
00027 * - Frequency counter for frequ. about or below sample rate (Hz)
00028 * - Motor rotations (rpm)
00029 * - Energy meter with SO interface
00030 *
00031 *
00032 */
00033 
00034 #ifndef MBED_PULSES_H
00035 #define MBED_PULSES_H
00036 
00037 #include "mbed.h"
00038 
00039 /** A class to calculate frequencys based on timing between pulses. Pulse-frequency can be about or slower than loop/aquisition time
00040 *
00041 * Example:
00042 *
00043 * @code
00044 #include "mbed.h"
00045 #include "Pulses.h"
00046 
00047 Pulses pulses(p8, Pulses::FALL);
00048 Serial pc(USBTX, USBRX); // tx, rx
00049 
00050 int main() {
00051     // choose on of the following unit scales
00052     pulses.setFactor(1.0f);   // Hz
00053     pulses.setFactor(60.0f);   // rpm
00054     pulses.setFactor(3600.0f/2000.0f);   // kWh; energy meter with SO interface - 2000 pulses per kWh
00055     
00056     while(1) {
00057         pc.printf ( "Pulses: act=%.3f average=%.3f   counter=%d \r\n", 
00058             pulses.getAct(), 
00059             pulses.getAverage(),
00060             pulses.getCounter() );
00061         
00062         wait(3.14);
00063     }
00064 }
00065 * @endcode
00066 */
00067 class Pulses {
00068 public:
00069 
00070     /** Pulses type format */
00071     enum PulseType {
00072         RISE=1,     //< Trigger on rising edge
00073         FALL=2,     //< Trigger on falling edge
00074         CHANGE=3    //< Trigger on both edges. On symmetrical pulses you can improve precision by 2
00075     };
00076 
00077     /** constructor of Pulses object
00078     *
00079     * @param inPin    Pin number of input pin. All port pins are possible except p19 and p20
00080     * @param type     Type of edge detection. RISE, FALL, CHANGE
00081     * @param timeout  Timeout in seconds to handle a stopped pulse-generator (standing motor). Max 15 minutes.
00082     * @param counter  Start value of the internal pulses counter to offset pSum (in get()) e.g. after reboot
00083     */
00084     explicit Pulses(PinName inPin, PulseType type=FALL, unsigned int timeout=600, unsigned int counter=0);
00085 
00086     /** Gets the frequency based on the last 2 pulses. It's only a snapshot and its not representative.
00087     *
00088     * @return        Actual frequency
00089     */
00090     float getAct();
00091 
00092     /** Gets the average of frequency based on all pulses since last call of this function
00093     *
00094     * @return        Average frequency. -1 if no new pulses occurred since last call
00095     */
00096     float getAverage();
00097 
00098     /** Gets the average, min, max and sum of frequency based on all pulses since last call of this function
00099     *
00100     * @param pAverage    Pointer to float value to return average frequency. Use NULL to skip param. -1 if no new pulses occurred since last call.
00101     * @param pMin        Pointer to float value to return min. frequency. Use NULL to skip param. -1 if no new pulses occurred since last call.
00102     * @param pMax        Pointer to float value to return max. frequency. Use NULL to skip param. -1 if no new pulses occurred since last call.
00103     * @param pSum        Pointer to float value to return the accumulated average values. Use NULL to skip param.
00104     */
00105     void get(float *pAverage, float *pMin, float *pMax, float *pSum=NULL);
00106 
00107     /** Gets the number of pulses from the input pin since start
00108     *
00109     * @return        Number of pulses
00110     */
00111     unsigned int getCounter();
00112 
00113     /** Sets the factor for the getter-functions to convert in another unit (1.0=Hz, 60.0=rpm, ...)
00114     *
00115     * @param factor  Factor to scale from Hz to user unit
00116     */
00117     void setFactor(float factor);
00118 
00119 
00120 protected:
00121     // ISR
00122     void callback_in();
00123     void callback_timeout();
00124 
00125     InterruptIn _in;
00126     Timer _timer;
00127     Ticker _timeout;
00128 
00129     PulseType _type;
00130 
00131     unsigned int _lastTimer;
00132     unsigned int _ActTime;
00133     unsigned int _MinTime;
00134     unsigned int _MaxTime;
00135     unsigned int _AvrTimeSum;
00136     unsigned int _AvrTimeCount;
00137     unsigned int _Counter;
00138     float _Factor;
00139     bool _bFirst;
00140     unsigned int _Timeout;
00141     unsigned int _TimeoutCount;
00142 
00143 };
00144 
00145 #endif