BBTrackball.h

00001 /* Copyright 2011 Adam Green (http://mbed.org/users/AdamGreen/)
00002 
00003    Licensed under the Apache License, Version 2.0 (the "License");
00004    you may not use this file except in compliance with the License.
00005    You may obtain a copy of the License at
00006 
00007        http://www.apache.org/licenses/LICENSE-2.0
00008 
00009    Unless required by applicable law or agreed to in writing, software
00010    distributed under the License is distributed on an "AS IS" BASIS,
00011    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00012    See the License for the specific language governing permissions and
00013    limitations under the License.
00014 */
00015 /* Header file for class to control Sparkfun's Blackberry Trackball:
00016      http://www.sparkfun.com/products/9320
00017 */
00018 #ifndef _BBTRACKBALL_H_
00019 #define _BBTRACKBALL_H_
00020 #include <mbed.h>
00021 
00022 namespace AFP 
00023 {
00024 
00025 /** A class to interface with the Sparkfun Blackberry Trackball Breakout Board.
00026  *  http://www.sparkfun.com/products/9320
00027  *
00028  *  This breakout board uses a hall effect for each direction of motion (up, 
00029  *  down, left, right) and generates pulses as the trackball is rotated in each
00030  *  of these directions.  This class counts both the rising and falling edges
00031  *  of these pulses in an interrupt handler.  The main program can query for
00032  *  the number of pulses that have been generated since the previous query was
00033  *  made.
00034  *
00035  *  The breakout board also has a push button placed beneath the trackball so
00036  *  that user presses can be detected as well.  This class will provide the
00037  *  state of this button as well after filtering it for the purpose of 
00038  *  debouncing.
00039  *
00040  *  The last feature of this breakout board that is supported by the class
00041  *  includes the 4 LEDs that have been placed beneath the trackball.  This
00042  *  class allows the caller to specify an individual brightness value for each
00043  *  of the LEDs (red, blue, green, white). 
00044  *
00045  * Example:
00046  * @code
00047 #include <mbed.h>
00048 #include <USBMouse.h>
00049 #include "BBTrackball.h"
00050 
00051 int main() 
00052 {
00053     static const CBBTrackball::SColour GreenColour = { 0, 255, 0, 0 };
00054     static CBBTrackball Trackball(p20,  // BLU
00055                                   p25,  // RED
00056                                   p26,  // GRN
00057                                   p10,  // WHT
00058                                   p5,   // UP
00059                                   p6,   // DWN
00060                                   p7,   // LFT
00061                                   p8,   // RHT
00062                                   p9);  // BTN
00063     static USBMouse     Mouse;
00064     
00065     // Turn the green LED on.
00066     Trackball.SetColour(&GreenColour);
00067     
00068     for(;;)
00069     {
00070         CBBTrackball::SState    TrackballState;
00071         int                     DeltaX;
00072         int                     DeltaY;
00073         
00074         Trackball.GetState(&TrackballState);
00075 
00076         // NOTE: The breakout board is rotated 90 degrees on my breadboard.
00077         DeltaX = TrackballState.Up - TrackballState.Down;
00078         DeltaY = TrackballState.Right - TrackballState.Left;
00079 
00080         Mouse.update(DeltaX, 
00081                      DeltaY, 
00082                      TrackballState.ButtonPressed ? MOUSE_LEFT : 0,
00083                      0);
00084     }
00085 }
00086  * @endcode
00087  */
00088 class CBBTrackball
00089 {
00090 public:
00091      /** A structure in which the current state of the trackball is returned
00092          from the GetState() method.
00093          
00094          @see GetState()
00095      */
00096      struct SState
00097      {
00098         int     ButtonPressed;  /**< 1 if the button is currently pressed and 0 otherwise. */
00099         short   Up;             /**< Number of upward pulses since last call. */
00100         short   Down;           /**< Number of downward pulses since last call. */
00101         short   Left;           /**< Number of leftward pulses since last call. */
00102         short   Right;          /**< Number of rightward pulses since last call. */
00103      };
00104      
00105      /** A structure used to represent the colour of the illumination for the
00106          trackball.
00107          
00108          @see SetColour()
00109      */
00110      struct SColour
00111      {
00112         unsigned char   Red;    /**< Red colour component (0 - 255). */
00113         unsigned char   Green;  /**< Green colour component (0 - 255). */
00114         unsigned char   Blue;   /**< Blue colour component (0 - 255). */
00115         unsigned char   White;  /**< Additional white colour component (0 - 255). */
00116      };
00117      
00118      /**
00119      * Create a CBBTrackball object, binds it to the specified input/output
00120      * pins, and initializes the required interrupt handling.
00121      *
00122      * @param BluePin The mbed pin which is connected to the BLU pin of the breakout board.
00123      *                Must be a pin on which the mbed supports PwmOut.
00124      * @param RedPin The mbed pin which is connected to the RED pin of the breakout board.
00125      *                Must be a pin on which the mbed supports PwmOut.
00126      * @param GreenPin The mbed pin which is connected to the GRN pin of the breakout board.
00127      *                Must be a pin on which the mbed supports PwmOut.
00128      * @param WhitePin The mbed pin which is connected to the WHT pin of the breakout board.
00129      *                Must be a pin on which the mbed supports PwmOut.
00130      * @param UpPin The mbed pin which is connected to the UP pin of the breakout board.
00131      *              Must be a pin on which the mbed supports InterruptIn.
00132      * @param DownPin The mbed pin which is connected to the DWN pin of the breakout board.
00133      *              Must be a pin on which the mbed supports InterruptIn.
00134      * @param LeftPin The mbed pin which is connected to the LFT pin of the breakout board.
00135      *              Must be a pin on which the mbed supports InterruptIn.
00136      * @param RightPin The mbed pin which is connected to the RHT pin of the breakout board.
00137      *              Must be a pin on which the mbed supports InterruptIn.
00138      * @param ButtonPin The mbed pin which is connected to the BTN pin of the breakout board.
00139      */
00140     CBBTrackball(PinName BluePin,
00141                  PinName RedPin,
00142                  PinName GreenPin,
00143                  PinName WhitePin,
00144                  PinName UpPin,
00145                  PinName DownPin,
00146                  PinName LeftPin,
00147                  PinName RightPin,
00148                  PinName ButtonPin) : m_BluePWM(BluePin),
00149                                       m_RedPWM(RedPin),
00150                                       m_GreenPWM(GreenPin),
00151                                       m_WhitePWM(WhitePin),
00152                                       m_UpInterrupt(UpPin),
00153                                       m_DownInterrupt(DownPin),
00154                                       m_LeftInterrupt(LeftPin),
00155                                       m_RightInterrupt(RightPin),
00156                                       m_Button(ButtonPin),
00157                                       m_UpCount(0),
00158                                       m_DownCount(0),
00159                                       m_LeftCount(0),
00160                                       m_RightCount(0),
00161                                       m_ButtonState(1),
00162                                       m_ButtonNewStateCount(0)
00163     {
00164         static const SColour AllLEDsOff = { 0, 0, 0, 0 };
00165         
00166         m_UpInterrupt.rise<CBBTrackball>(this, &CBBTrackball::UpISR);
00167         m_DownInterrupt.rise<CBBTrackball>(this, &CBBTrackball::DownISR);
00168         m_LeftInterrupt.rise<CBBTrackball>(this, &CBBTrackball::LeftISR);
00169         m_RightInterrupt.rise<CBBTrackball>(this, &CBBTrackball::RightISR);
00170         m_ButtonSampleTicker.attach_us<CBBTrackball>(this, &CBBTrackball::ButtonSampleISR, 100);
00171         SetColour(&AllLEDsOff);
00172     }
00173     
00174     
00175     /** Gets current state of the trackball.
00176     *
00177     * Returns state indicating how much the trackball has moved in each 
00178     * direction since the last call to GetState() and the current state of the
00179     * push button.
00180     *
00181     * @param pState points to the state structure to be filled in with the 
00182     *        current state.
00183     */
00184     void GetState(SState* pState);
00185     
00186     /** Sets the colour of the trackball illumination.
00187     *
00188     * @param pColour points to the colour structure used to determine the
00189     *        illumination contribution from each of the 4 LEDs found beneath
00190     *        the trackball.
00191     */
00192     void SetColour(const SColour* pColour);
00193     
00194                      
00195 protected:
00196     void UpISR(void);
00197     void DownISR(void);
00198     void LeftISR(void);
00199     void RightISR(void);
00200     void ButtonSampleISR(void);
00201     short ThresholdToShort(unsigned int Value);
00202     short UpCount(void);
00203     short DownCount(void);
00204     short LeftCount(void);
00205     short RightCount(void);
00206     
00207     PwmOut          m_BluePWM;
00208     PwmOut          m_RedPWM;
00209     PwmOut          m_GreenPWM;
00210     PwmOut          m_WhitePWM;
00211     
00212     InterruptIn     m_UpInterrupt;
00213     InterruptIn     m_DownInterrupt;
00214     InterruptIn     m_LeftInterrupt;
00215     InterruptIn     m_RightInterrupt;
00216     
00217     DigitalIn       m_Button;
00218     Ticker          m_ButtonSampleTicker;  
00219     
00220     unsigned int    m_UpCount;
00221     unsigned int    m_DownCount;
00222     unsigned int    m_LeftCount;
00223     unsigned int    m_RightCount;
00224     
00225     int             m_ButtonState;
00226     unsigned int    m_ButtonNewStateCount;        
00227 };
00228 
00229 } // namespace AFP
00230 using namespace AFP;
00231 
00232 #endif /* _BBTRACKBALL_H__BBTRACKBALL_H_ */