PinDetect.h

00001 /*
00002     by Michael Shimniok
00003     
00004     based on PinDetect Copyright (c) 2010 Andy Kirkham
00005 
00006     Permission is hereby granted, free of charge, to any person obtaining a copy
00007     of this software and associated documentation files (the "Software"), to deal
00008     in the Software without restriction, including without limitation the rights
00009     to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00010     copies of the Software, and to permit persons to whom the Software is
00011     furnished to do so, subject to the following conditions:
00012 
00013     The above copyright notice and this permission notice shall be included in
00014     all copies or substantial portions of the Software.
00015 
00016     THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00017     IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00018     FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00019     AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00020     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
00022     THE SOFTWARE.
00023 */
00024 
00025 #if 0
00026 
00027 #ifndef AJK_PIN_DETECT_H
00028 #define AJK_PIN_DETECT_H
00029 
00030 #include "mbed.h"
00031 
00032 #define PINDETECT_PIN_ASSTERED   1
00033 #define PINDETECT_SAMPLE_PERIOD 20000
00034 #define PINDETECT_ASSERT_COUNT  1
00035 #define PINDETECT_HOLD_COUNT    50
00036 
00037 /** PinDetect adds mechanical switch debouncing to DigitialIn and interrupt callbacks.
00038  *
00039  * This is done by sampling the specified pin at regular intervals and detecting any
00040  * change of state ( 0 -> 1 or 1 -> 0 ). When a state change is detected the attached
00041  * callback handler is called. Additionally, if the pin stays in the same state after
00042  * a state change for a defined period of time, an extra callback is made allowing a
00043  * program to detect when a "key is pressed and held down" rather than a momentary
00044  * key/switch press.
00045  *
00046  * All parameters are customisable which include:-
00047  *  <ul>
00048  *  <li> The sampling frequency. </li>
00049  *  <li> The number of continuous samples until a state change is detected. </li>
00050  *  <li> The number of continuous samples until a key is assumed held after a state change. </li>
00051  *  <li> The logic level which is assumed to be asserted (0volts or +volts). </li>
00052  *  </ul>
00053  *
00054  * Only callbacks that have been attached will be called by the library.
00055  *
00056  * Example:
00057  * @code
00058  * #include "mbed.h"
00059  * #include "PinDetect.h"
00060  *
00061  * PinDetect  pin( p30 );
00062  * DigitialOut led1( LED1 );
00063  * DigitialOut led2( LED2 );
00064  * DigitialOut led3( LED3 );
00065  * DigitialOut led4( LED4 );
00066  *
00067  * void keyPressed( void ) {
00068  *     led2 = 1;
00069  *     led3 = 0;
00070  *     led4 = 0;
00071  * }
00072  *
00073  * void keyReleased( void ) {
00074  *     led2 = 0;
00075  *     led3 = 0;
00076  *     led4 = 0;
00077  * }
00078  *
00079  * void keyPressedHeld( void ) {
00080  *     led3 = 1;
00081  * }
00082  *
00083  * void keyReleasedHeld( void ) {
00084  *     led4 = 1;
00085  * }
00086  *
00087  * int main() {
00088  *
00089  *     pin.mode( PullDown );
00090  *     pin.attach_asserted( &keyPressed );
00091  *     pin.attach_deasserted( &keyReleased );
00092  *     pin.attach_asserted_held( &keyPressedHeld );
00093  *     pin.attach_deasserted_held( &keyReleasedHeld );
00094  *
00095  *     // Sampling does not begin until you set a frequency.
00096  *     // The default is 20ms. If you want a different frequency
00097  *     // then pass the period in microseconds for example, for 10ms :-
00098  *     //     pin.setSampleFrequency( 10000 );
00099  *     //
00100  *     pin.setSampleFrequency(); // Defaults to 20ms.
00101  *
00102  *     while( 1 ) {
00103  *         led1 = !led1;
00104  *         wait( 0.2 );
00105  *     }
00106  * }
00107  * @endcode
00108  *
00109  * This example will flash led1 in a similar to a standard starting program.
00110  *
00111  * Applying a "1" (switch on) to pin 30 will switch on led2, removing the "1" to "0"
00112  * (switch off) led2 goes out. Holding the "switch" at one for one second will switch
00113  * on led3. An unasserted P30 (switched off) will, after one second illuminate led4
00114  * when the deasserted calledback is called.
00115  *
00116  * The above is a very basic introduction. For more details:-
00117  * @see example.h
00118  */
00119 class PinDetect {
00120 
00121 protected:
00122     DigitalIn   *_in;
00123     Ticker      *_ticker;
00124     int         _prevState;
00125     int         _currentStateCounter;
00126     int         _sampleTime;
00127     int         _assertValue;
00128     int         _samplesTillAssertReload;
00129     int         _samplesTillAssert;
00130     int         _samplesTillHeldReload;
00131     int         _samplesTillHeld;
00132     //FunctionPointer _callbackAsserted;
00133     //FunctionPointer _callbackDeasserted;
00134     //FunctionPointer _callbackAssertedHeld;
00135     //FunctionPointer _callbackDeassertedHeld;
00136 
00137     /** initialise class
00138      *
00139      * @param PinName p is a valid pin that supports DigitalIn
00140      * @param PinMode m The mode the DigitalIn should use.
00141      */
00142     void init(PinName p, PinMode m); 
00143 
00144     /** The Ticker periodic callback function
00145      */
00146     void isr(void);
00147 
00148 public:
00149 
00150     friend class Ticker;
00151 
00152     /** PinDetect constructor
00153      *
00154      * By default the PinMode is set to PullDown.
00155      *
00156      * @see http://mbed.org/handbook/DigitalIn
00157      * @param p PinName is a valid pin that supports DigitalIn
00158      */
00159     PinDetect(PinName p);
00160 
00161     /** PinDetect constructor
00162      *
00163      * @see http://mbed.org/handbook/DigitalIn
00164      * @param PinName p is a valid pin that supports DigitalIn
00165      * @param PinMode m The mode the DigitalIn should use.
00166      */
00167     PinDetect(PinName p, PinMode m);
00168 
00169     /** PinDetect destructor
00170      */
00171     ~PinDetect();
00172 
00173     /** Set the sampling time in microseconds.
00174      *
00175      * @param int The time between pin samples in microseconds.
00176      */
00177     void setSampleFrequency(int i = PINDETECT_SAMPLE_PERIOD);
00178 
00179     /** Set the value used as assert.
00180      *
00181      * Defaults to 1 (ie if pin == 1 then pin asserted).
00182      *
00183      * @param int New assert value (1 or 0)
00184      */
00185     void setAssertValue(int i = PINDETECT_PIN_ASSTERED);
00186 
00187     /** Set the number of continuous samples until assert assumed.
00188      *
00189      * Defaults to 1 (1 * sample frequency).
00190      *
00191      * @param int The number of continuous samples until assert assumed.
00192      */
00193     void setSamplesTillAssert(int i);
00194 
00195     /** Set the number of continuous samples until held assumed.
00196      *
00197      * Defaults to 50 * sample frequency.
00198      *
00199      * @param int The number of continuous samples until held assumed.
00200      */
00201     void setSamplesTillHeld(int i);
00202 
00203     /** Set the pin mode.
00204      *
00205      * @see http://mbed.org/projects/libraries/api/mbed/trunk/DigitalInOut#DigitalInOut.mode
00206      * @param PinMode m The mode to pass on to the DigitalIn
00207      */
00208     void mode(PinMode m);
00209 
00210     /** Attach a callback function
00211      *
00212      * @code
00213      *
00214      * DigitalOut led1( LED1 );
00215      * PinDetect pin( p30 );
00216      *
00217      * void myCallback( void ) {
00218      *   led1 = 1;
00219      * };
00220      *
00221      * main() {
00222      *     pin.attach_asserted( &myCallback );
00223      * }
00224      *
00225      * @endcode
00226      *
00227      * Call this function when a pin is asserted.
00228      * @param function A C function pointer
00229      */
00230     void attach_asserted(Callback function);
00231 
00232     /** Attach a callback object/method
00233      *
00234      * @code
00235      *
00236      * class Bar {
00237      *   public:
00238      *     void myCallback( void ) { led1 = 1; }
00239      * };
00240      *
00241      * DigitalOut led1( LED1 );
00242      * PinDetect pin( p30 );
00243      * Bar bar;
00244      *
00245      * main() {
00246      *     pin.attach_asserted( &bar, &Bar::myCallback );
00247      * }
00248      *
00249      * @endcode
00250      *
00251      * Call this function when a pin is asserted.
00252      * @param object An object that conatins the callback method.
00253      * @param method The method within the object to call.
00254      */
00255     template<typename T>
00256     void attach_asserted(T *object, void (T::*member)(void));
00257 
00258     /** Attach a callback function
00259      *
00260      * @code
00261      *
00262      * DigitalOut led1( LED1 );
00263      * PinDetect pin( p30 );
00264      *
00265      * void myCallback( void ) {
00266      *   led1 = 0;
00267      * };
00268      *
00269      * main() {
00270      *     pin.attach_deasserted( &myCallback );
00271      * }
00272      *
00273      * @endcode
00274      *
00275      * Call this function when a pin is deasserted.
00276      * @param function A C function pointer
00277      */
00278     void attach_deasserted(void (*function)(void));
00279 
00280     /** Attach a callback object/method
00281      *
00282      * @code
00283      *
00284      * class Bar {
00285      *   public:
00286      *     void myCallback( void ) { led1 = 0; }
00287      * };
00288      *
00289      * DigitalOut led1( LED1 );
00290      * PinDetect pin( p30 );
00291      * Bar bar;
00292      *
00293      * main() {
00294      *     pin.attach_deasserted( &bar, &Bar::myCallback );
00295      * }
00296      *
00297      * @endcode
00298      *
00299      * Call this function when a pin is deasserted.
00300      * @param object An object that conatins the callback method.
00301      * @param method The method within the object to call.
00302      */
00303     template<typename T>
00304     void attach_deasserted(T *object, void (T::*member)(void));
00305 
00306     /** Attach a callback function
00307      *
00308      * @code
00309      *
00310      * DigitalOut led2( LED2 );
00311      * PinDetect pin( p30 );
00312      *
00313      * void myCallback( void ) {
00314      *   led2 = 1;
00315      * };
00316      *
00317      * main() {
00318      *     pin.attach_asserted_held( &myCallback );
00319      * }
00320      *
00321      * @endcode
00322      *
00323      * Call this function when a pin is asserted and held.
00324      * @param function A C function pointer
00325      */
00326     void attach_asserted_held(void (*function)(void));
00327 
00328     /** Attach a callback object/method
00329      *
00330      * @code
00331      *
00332      * class Bar {
00333      *   public:
00334      *     void myCallback( void ) { led2 = 0; }
00335      * };
00336      *
00337      * DigitalOut led2( LED2 );
00338      * PinDetect pin( p30 );
00339      * Bar bar;
00340      *
00341      * main() {
00342      *     pin.attach_asserted_held( &bar, &Bar::myCallback );
00343      * }
00344      *
00345      * @endcode
00346      *
00347      * Call this function when a pin is asserted and held.
00348      * @param object An object that conatins the callback method.
00349      * @param method The method within the object to call.
00350      */
00351     template<typename T>
00352     void attach_asserted_held(T *object, void (T::*member)(void));
00353 
00354     /** Attach a callback function
00355      *
00356      * @code
00357      *
00358      * DigitalOut led3( LED3 );
00359      * PinDetect pin( p30 );
00360      *
00361      * void myCallback( void ) {
00362      *   led3 = 1;
00363      * };
00364      *
00365      * main() {
00366      *     pin.attach_deasserted_held( &myCallback );
00367      * }
00368      *
00369      * @endcode
00370      *
00371      * Call this function when a pin is deasserted and held.
00372      * @param function A C function pointer
00373      */
00374     void attach_deasserted_held(void (*function)(void));
00375 
00376     /** Attach a callback object/method
00377      *
00378      * @code
00379      *
00380      * class Bar {
00381      *   public:
00382      *     void myCallback( void ) { led3 = 0; }
00383      * };
00384      *
00385      * DigitalOut led3( LED3 );
00386      * PinDetect pin( p30 );
00387      * Bar bar;
00388      *
00389      * main() {
00390      *     pin.attach_deasserted_held( &bar, &Bar::myCallback );
00391      * }
00392      *
00393      * @endcode
00394      *
00395      * Call this function when a pin is deasserted and held.
00396      * @param object An object that conatins the callback method.
00397      * @param method The method within the object to call.
00398      */
00399     template<typename T>
00400     void attach_deasserted_held(T *object, void (T::*member)(void));
00401 
00402     /** operator int()
00403      *
00404      * Read the value of the pin being sampled.
00405      */
00406     operator int() { return _in->read(); }
00407 
00408 };
00409 
00410 #endif
00411 
00412 #endif