Revision 4:f953792e45cb, committed 2014-09-03

Comitter:

jocis

Date:

Wed Sep 03 07:36:43 2014 +0000

Parent:

3:7bacae57a30b

Commit message:

Added documentation

Changed in this revision

--- 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; }