SpaceBall.h

00001 /* mbed SpaceBall, SpaceMouse and SpaceOrb Library
00002  * Copyright (c) 2012 Jochen Krapf
00003  *
00004  * Permission is hereby granted, free of charge, to any person obtaining a copy
00005  * of this software and associated documentation files (the "Software"), to deal
00006  * in the Software without restriction, including without limitation the rights
00007  * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
00008  * copies of the Software, and to permit persons to whom the Software is
00009  * furnished to do so, subject to the following conditions:
00010  *
00011  * The above copyright notice and this permission notice shall be included in
00012  * all copies or substantial portions of the Software.
00013  *
00014  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
00015  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
00016  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
00017  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
00018  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
00019  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
00020  * THE SOFTWARE.
00021  */
00022  
00023 #include "mbed.h"
00024 
00025 /** Spaceball Button bit-masks */
00026 #define SBALL_BUTTON_1        0x0001   /* bit  0 */
00027 #define SBALL_BUTTON_2        0x0002   /* bit  1 */
00028 #define SBALL_BUTTON_3        0x0004   /* bit  2 */
00029 #define SBALL_BUTTON_4        0x0008   /* bit  3 */
00030 #define SBALL_BUTTON_5        0x0010   /* bit  4 */
00031 #define SBALL_BUTTON_6        0x0020   /* bit  5 */
00032 #define SBALL_BUTTON_7        0x0040   /* bit  6 */
00033 #define SBALL_BUTTON_8        0x0080   /* bit  7 */
00034 #define SBALL_BUTTON_9        0x0100   /* bit  8 */
00035 #define SBALL_BUTTON_10       0x0200   /* bit  9 */
00036 #define SBALL_BUTTON_11       0x0400   /* bit 10 */
00037 #define SBALL_BUTTON_12       0x0800   /* bit 11 */
00038 
00039 /* The Spaceball 3003 and 3003 FLX only have "left" and "right" buttons */
00040 #define SBALL_BUTTON_RIGHT    0x1000   /* bit 12 */
00041 #define SBALL_BUTTON_LEFT     0x2000   /* bit 13 */
00042 
00043 /* The Spaceball 2003A and 2003B have a dedicated pick button on the ball */
00044 /* The Spaceball 2003 FLX uses "button 9" as the pick button.             */
00045 /* All of them return this as "button 9" in their encoded button data     */
00046 #define SBALL_BUTTON_PICK      SBALL_BUTTON_RIGHT   /* bit  12 */
00047 
00048 /* On Spaceball 2003A and 2003B, the Rezero is "button 8" on the device */
00049 /* On the newer devices, there are dedicated rezero buttons */
00050 #define SBALL_BUTTON_REZERO  0x4000   /* bit 14 */
00051 
00052 /* The Spaceball 4000 FLX has a configurable palm rest which can be in    */
00053 /* either "left" or "right" handed mode.  When it is configured in "left" */
00054 /* handed mode, the "lefty" bit is set, and coordinate systems need to be */
00055 /* inverted on one axis.                                                  */
00056 #define SBALL_MODE_LEFTY     0x8000   /* bit 15 */
00057 
00058 
00059 #define SPACEBALL_MAX_LENGTH    128
00060 
00061 /** Axis enumeration for function GetAxis() */
00062 enum eSpaceBallAxis { 
00063     TX=0, TY, TZ, 
00064     Right=0, Forward, Up, 
00065     RX=3, RY, RZ,
00066     Pitch=3, Roll, Yaw };
00067 
00068 /** Mapping enumeration for function GetAxis() to adapt coordinate system */
00069 enum eSpaceBallMapping { 
00070     RAW=0, CNC, CNCvert };
00071 
00072 /** SpaceBall class, based on serial connection
00073 *
00074 * Library to handle SpaceBall, SpaceMouse and SpaceOrb on serial port. Gets access to 3D rotation and translation vector as well as button status
00075 *
00076 * Supported devices:
00077 * - Spaceball 2003A
00078 * - Spaceball 2003B
00079 * - Spaceball 2003 FLX
00080 * - Spaceball 3003
00081 * - Spaceball 3003 FLX
00082 * - Spaceball 4000 FLX
00083 * - SpaceMouse
00084 * - SpaceOrb (Note: Flag has to be set in constructor)
00085 *
00086 * Note: USB or wireless devices are NOT supported by this class
00087 *
00088 * Serial connection (D-Sub 9p male):
00089 * - 3 <--- RS232 Driver <--- mbed TX
00090 * - 2 ---> RS232 Driver ---> mbed RX
00091 * - 5 ----| GND
00092 * - 4 <--- Power +9...+12 volt
00093 * - 7 <--- Power +9...+12 volt
00094 *
00095 * Example: (illuminates LEDs dependent on force at the Spaceball)
00096 * @code
00097 #include "mbed.h"
00098 #include "SpaceBall.h"
00099 
00100 PwmOut led[] = {(LED1), (LED2), (LED3), (LED4) };
00101 SpaceBall SBall(p9, p10);   // tx, rx, bSOrb
00102 
00103 int main() {
00104     SBall.Init();
00105     
00106     while(1) {
00107 
00108         led[0] = abs( SBall[TX] ) + abs( SBall[TY] ) + abs( SBall[TZ] );
00109         led[1] = abs( SBall[RX] );
00110         led[2] = abs( SBall[RY] );
00111         led[3] = abs( SBall[RZ] );
00112         
00113         wait_us(500);
00114     }
00115 }
00116  * @endcode
00117  */
00118 class SpaceBall {
00119 public:
00120     
00121     /** Create a input object connected to the specified serial pin
00122      *
00123      * @param tx    Serial TX pin to connect to 
00124      * @param rx    Serial RX pin to connect to 
00125      * @param bSpaceOrb    Flag to select device. false = SpaceBall and SpaceMouse. true = SpaceOrb  
00126      */
00127     SpaceBall ( PinName tx, PinName rx, bool bSpaceOrb=false );
00128     
00129     /** destructor */
00130     ~SpaceBall() {};
00131 
00132     /** initializing the connection to the device
00133      *
00134      */
00135     void Init();
00136     
00137     /** Set mapping mode for function GetAxis() to adapt coordinate system
00138      *
00139      * @param mapping   Mapping mode
00140      */
00141     void SetMapping ( int mapping )
00142     {   _mapping = mapping; }
00143     
00144     /** Gets the translation axis (push, pull) as 3D vector
00145      *
00146      * @param fValue[]   Return vector with X, Y and Z
00147      */
00148     void GetTranslation ( float* fValue[3] ) const
00149     {
00150         *fValue[0] = GetAxis ( TX );
00151         *fValue[1] = GetAxis ( TY );
00152         *fValue[2] = GetAxis ( TZ );
00153     }
00154     
00155     /** Gets the rotation axis as 3D vector
00156      *
00157      * @param fValue[]   Return vector with Pitch, Roll and Yaw
00158      */
00159     void GetRotation ( float* fValue[3] ) const
00160     {
00161         *fValue[0] = GetAxis ( RX );
00162         *fValue[1] = GetAxis ( RY );
00163         *fValue[2] = GetAxis ( RZ );
00164     }
00165     
00166     /** Gets a single axis value. Coordinate system is mapped according function SetMapping() 
00167      *
00168      * @param nAxis   Axis index/name
00169      * @return        Axis value as scaled float
00170      */
00171     float GetAxis ( int nAxis ) const;
00172     
00173     /** Gets a single axis value. Coordinate system is mapped according function SetMapping() 
00174      *
00175      * @param nAxis   Axis index/name
00176      * @return        Axis value as unscaled int (as provided by the SpaceBall)
00177      */
00178     int GetAxisRaw ( int nAxis ) const;
00179     
00180     /** Gets a single axis value as [] operator. Coordinate system is mapped according function SetMapping() 
00181      *
00182      * Usage: float x = spaceball[RX];
00183      *
00184      * @param nAxis   Axis index/name
00185      * @return        Axis value as scaled float
00186      */
00187     float operator[] (eSpaceBallAxis nAxis) const
00188     {   return GetAxis ( nAxis ); }
00189     
00190     /** Gets a single axis value as [] operator. Coordinate system is mapped according function SetMapping() 
00191      *
00192      * Usage: float x = spaceball[3];
00193      *
00194      * @param nAxis   Axis index/name
00195      * @return        Axis value as scaled float
00196      */
00197     float operator[] (int nAxis) const
00198     {   return GetAxis ( nAxis ); }
00199     
00200     /** Gets the button states as an bit-combination. See definitions of Spaceball Button bit-masks
00201      *
00202      * @return        Buttons bit-combination
00203      */
00204     int GetButtons() const
00205     {   return _buttons; }
00206     
00207     /** Gets the button states as an bit-combination as int operator. See definitions of Spaceball Button bit-masks
00208      *
00209      * Usage: int b = spaceball;
00210      *
00211      * @return        Buttons bit-combination
00212      */
00213     operator int (void) const
00214     {   return GetButtons(); }
00215     
00216     /** Sets the additional scaling factor for function GetAxis() 
00217      *
00218      * @param fScale  Scaling factor
00219      */
00220     void SetScale ( float fScale=1.0f )
00221     {   _fScale = fScale; }
00222 
00223     /** Gets the additional scaling factor for function GetAxis() 
00224      *
00225      * @return        Scaling factor
00226      */
00227     float GetScale ( void )
00228     {   return _fScale; }
00229 
00230 
00231 protected:
00232     Serial _serial;
00233     bool _bSpaceOrb;
00234     float _fScale;
00235     
00236     int _axis[6];      /* last translational data received */
00237     int _buttons;       /* current button status */
00238     
00239     void SerialISR(void);
00240     void Process ( char c );
00241     
00242     virtual void DoChangedAxis (void) {};
00243     virtual void DoChangedButtons (void) {};
00244     
00245 private:
00246     int m_erroroccured;  /* if set, we've received an error packet or packets */
00247     int m_resetoccured;  /* if set, ball was reset, so have to reinitialize it */
00248     int m_spaceball4000; /* if set, its a Spaceball 4000 */
00249     int m_leftymode4000; /* if set, Spaceball 4000 in "lefty" orientation */
00250 
00251     bool _escape;
00252     int _idx;
00253     char _data[SPACEBALL_MAX_LENGTH];
00254 
00255     float _fScaleR;
00256     float _fScaleT;
00257     int _mapping;
00258     
00259     void InitSB();
00260     void InitSO();
00261 
00262     void ProcessSB ( char c );
00263     void ProcessSO ( char c );
00264     
00265     void ProcessPacketSB ( void );
00266     void ProcessPacketSO ( void );
00267 
00268 };