Library to handle SpaceBall, SpaceMouse and SpaceOrb on serial port. Gets access to 3D rotation and translation vector as well as button status. (USB is not supported)

Dependents:   SpaceBall_Example

Library to handle SpaceBall, SpaceMouse and SpaceOrb on serial port. Gets access to 3D rotation and translation vector as well as button status. (USB is not supported)

All handling and decoding is done in the RX interrupt and the vector values can be read out asynchronously with different coordinate mappings.

Example:

#include "mbed.h"
#include "SpaceBall.h"
 
PwmOut led[] = {(LED1), (LED2), (LED3), (LED4) };
SpaceBall SBall(p9, p10);   // tx, rx, bSOrb
 
int main() {
    SBall.Init();
    
    while(1) {
 
        led[0] = abs( SBall[TX] ) + abs( SBall[TY] ) + abs( SBall[TZ] );
        led[1] = abs( SBall[RX] );
        led[2] = abs( SBall[RY] );
        led[3] = abs( SBall[RZ] );
        
        wait_us(500);
    }
}

In this exaple the 4 LEDs are powered dependent on force at the Spaceball. LED1 shows the sum of all translation forces. LED2 to LED4 shows the rotation forces.

For more information about SpaceBall devices see manufactorers page http://www.3dconnexion.com

For connecting a SpaceBall (or SpaceMouse or SpaceOrb) to mbed see page wiki/Serial-Connection

Example: SpaceBall 4000

/media/uploads/jocis/spaceball1.jpg

Files at this revision

API Documentation at this revision

Comitter:
jocis
Date:
Wed Sep 03 07:36:43 2014 +0000
Parent:
3:7bacae57a30b
Commit message:
Added documentation

Changed in this revision

SpaceBall.h Show annotated file Show diff for this revision Revisions of this file
diff -r 7bacae57a30b -r f953792e45cb SpaceBall.h
--- a/SpaceBall.h	Tue Sep 02 09:34:06 2014 +0000
+++ b/SpaceBall.h	Wed Sep 03 07:36:43 2014 +0000
@@ -22,7 +22,7 @@
  
 #include "mbed.h"
 
-/* Spaceball Button bit-masks */
+/** Spaceball Button bit-masks */
 #define SBALL_BUTTON_1        0x0001   /* bit  0 */
 #define SBALL_BUTTON_2        0x0002   /* bit  1 */
 #define SBALL_BUTTON_3        0x0004   /* bit  2 */
@@ -58,19 +58,61 @@
 
 #define SPACEBALL_MAX_LENGTH    128
 
+/** Axis enumeration for function GetAxis() */
 enum eSpaceBallAxis { 
     TX=0, TY, TZ, 
     Right=0, Forward, Up, 
     RX=3, RY, RZ,
     Pitch=3, Roll, Yaw };
 
+/** Mapping enumeration for function GetAxis() to adapt coordinate system */
 enum eSpaceBallMapping { 
     RAW=0, CNC, CNCvert };
 
 /** SpaceBall class, based on serial connection
- *
- * Example:
- * @code
+*
+* Library to handle SpaceBall, SpaceMouse and SpaceOrb on serial port. Gets access to 3D rotation and translation vector as well as button status
+*
+* Supported devices:
+* - Spaceball 2003A
+* - Spaceball 2003B
+* - Spaceball 2003 FLX
+* - Spaceball 3003
+* - Spaceball 3003 FLX
+* - Spaceball 4000 FLX
+* - SpaceMouse
+* - SpaceOrb (Note: Flag has to be set in constructor)
+*
+* Note: USB or wireless devices are NOT supported by this class
+*
+* Serial connection (D-Sub 9p male):
+* - 3 <--- RS232 Driver <--- mbed TX
+* - 2 ---> RS232 Driver ---> mbed RX
+* - 5 ----| GND
+* - 4 <--- Power +9...+12 volt
+* - 7 <--- Power +9...+12 volt
+*
+* Example: (illuminates LEDs dependent on force at the Spaceball)
+* @code
+#include "mbed.h"
+#include "SpaceBall.h"
+
+PwmOut led[] = {(LED1), (LED2), (LED3), (LED4) };
+SpaceBall SBall(p9, p10);   // tx, rx, bSOrb
+
+int main() {
+    SBall.Init();
+    
+    while(1) {
+
+        led[0] = abs( SBall[TX] ) + abs( SBall[TY] ) + abs( SBall[TZ] );
+        led[1] = abs( SBall[RX] );
+        led[2] = abs( SBall[RY] );
+        led[3] = abs( SBall[RZ] );
+        
+        wait_us(500);
+    }
+}
  * @endcode
  */
 class SpaceBall {
@@ -78,20 +120,31 @@
     
     /** Create a input object connected to the specified serial pin
      *
-     * @param pin PwmOut pin to connect to 
+     * @param tx    Serial TX pin to connect to 
+     * @param rx    Serial RX pin to connect to 
+     * @param bSpaceOrb    Flag to select device. false = SpaceBall and SpaceMouse. true = SpaceOrb  
      */
     SpaceBall ( PinName tx, PinName rx, bool bSpaceOrb=false );
+    
+    /** destructor */
     ~SpaceBall() {};
 
-    /** ...
+    /** initializing the connection to the device
      *
-     * @param xxx ...
      */
     void Init();
     
+    /** Set mapping mode for function GetAxis() to adapt coordinate system
+     *
+     * @param mapping   Mapping mode
+     */
     void SetMapping ( int mapping )
     {   _mapping = mapping; }
     
+    /** Gets the translation axis (push, pull) as 3D vector
+     *
+     * @param fValue[]   Return vector with X, Y and Z
+     */
     void GetTranslation ( float* fValue[3] ) const
     {
         *fValue[0] = GetAxis ( TX );
@@ -99,6 +152,10 @@
         *fValue[2] = GetAxis ( TZ );
     }
     
+    /** Gets the rotation axis as 3D vector
+     *
+     * @param fValue[]   Return vector with Pitch, Roll and Yaw
+     */
     void GetRotation ( float* fValue[3] ) const
     {
         *fValue[0] = GetAxis ( RX );
@@ -106,23 +163,67 @@
         *fValue[2] = GetAxis ( RZ );
     }
     
+    /** Gets a single axis value. Coordinate system is mapped according function SetMapping() 
+     *
+     * @param nAxis   Axis index/name
+     * @return        Axis value as scaled float
+     */
     float GetAxis ( int nAxis ) const;
     
+    /** Gets a single axis value. Coordinate system is mapped according function SetMapping() 
+     *
+     * @param nAxis   Axis index/name
+     * @return        Axis value as unscaled int (as provided by the SpaceBall)
+     */
     int GetAxisRaw ( int nAxis ) const;
     
+    /** Gets a single axis value as [] operator. Coordinate system is mapped according function SetMapping() 
+     *
+     * Usage: float x = spaceball[RX];
+     *
+     * @param nAxis   Axis index/name
+     * @return        Axis value as scaled float
+     */
     float operator[] (eSpaceBallAxis nAxis) const
     {   return GetAxis ( nAxis ); }
+    
+    /** Gets a single axis value as [] operator. Coordinate system is mapped according function SetMapping() 
+     *
+     * Usage: float x = spaceball[3];
+     *
+     * @param nAxis   Axis index/name
+     * @return        Axis value as scaled float
+     */
     float operator[] (int nAxis) const
     {   return GetAxis ( nAxis ); }
     
+    /** Gets the button states as an bit-combination. See definitions of Spaceball Button bit-masks
+     *
+     * @return        Buttons bit-combination
+     */
     int GetButtons() const
     {   return _buttons; }
     
+    /** Gets the button states as an bit-combination as int operator. See definitions of Spaceball Button bit-masks
+     *
+     * Usage: int b = spaceball;
+     *
+     * @return        Buttons bit-combination
+     */
     operator int (void) const
     {   return GetButtons(); }
     
+    /** Sets the additional scaling factor for function GetAxis() 
+     *
+     * @param fScale  Scaling factor
+     */
     void SetScale ( float fScale=1.0f )
     {   _fScale = fScale; }
+
+    /** Gets the additional scaling factor for function GetAxis() 
+     *
+     * @return        Scaling factor
+     */
     float GetScale ( void )
     {   return _fScale; }