Home ›

Migration guide from 0.5 to 0.6

Between libfreespace 0.5 and libfreespace 0.6, Hillcrest introduced the MotionEngine series of Freespace devices including the Scoop Remote Control and the FSRK-USB-2.  This family uses a slightly different set of HID messages than older devices, and libfreespace 0.6 supports both message formats.  The only reason to modify your code is if you are using a new MotionEngine device like the Scoop Pointer or FSRK-USB-2.  The two new messages used are the DataModeControl V2 message and the MotionEngine Output message.  Both are detailed below.

 

DataModeControl V2 Message

The DataModeControl V2 message is the new method of configuring MotionEngine devices' data output type (orientation, angular velocity, etc) and power management configuration (sleep, full motion, etc).  MotionEngine devices need to use the DataModeControlV2 and will not recognize the older DataModeControl message.

The new messages are defined in freespace_codecs.h with parameters as follows:
 

freespace_DataModeControlV2Request                

 
This message is sent from the host to the Freespace device requesting that the device enters a new data mode or power management configuration.
 

Data Fields   (detailed descriptions are below) 

 

ModeAndStatus 



          Operating Status:                            0 – Update the current operating mode as indicated
                                                                  1 – Report the current operating mode without changing it
 
          Operating Mode Requested:     Requests a change to the specified operating mode.  The Freespace device will enter the requested mode if allowed.
                                                                0 – Full Motion
                                                                1 – Sleep
                                                                2 – Deep Sleep
                                                                3 – Deep Deep Sleep
                                                                4 – Full Motion On
                                                                5 – RF on Motion
 
          Output Status:                                  0 – Update the current packet and format selections as indicated.
                                                                  1 – Report the current packet and format selections without changing them.
 

PacketSelect

 
          Select the output packet sent by the Freespace device to report motion data.
          0 – None
          1 – Mouse
          2 – BodyFrame
          3 – UserFrame
          4 – BodyUserFrame
          5 – DCE Out
          6 – Reserved
          7 – Reserved
          8 – MotionEngine Output
          9-255 - Reserved
 

Format Select

 
          Selects the format of the packet.                             Set to 0

Format Flags (FF1-FF7)

 
          See the MotionEngine Output Section for details
 
 

freespace_DataModeControlV2Response

This message is sent back to the host from the Freespace device confirming that a Data Mode Control V2 request was received and reporting back the new configuration.

Data Fields

  
 

MotionEngine Output Message

 

New Freespace devices now support a configurable data mode output.  Previously, you were limited to Cursor-Only, Body Frame, User Frame, or BodyUser Frame modes.  These sometimes would either not contain all the data desired by an application or contain extraneous data causing unnecessarily large packet sizes and communication times.
 
The Freespace MotionEngine now allows applications to select the specific data modes that are required by applications using the MotionEngineOutput message.  The legacy data types (Body Frame, User Frame, etc) are still supported and in the same format as older devices.
 
To use this message, select MotionEngineOutput option in the PacketSelect bit in the DataModeControlV2Request message.  Then, choose the desired data types by setting specific format flags to 1.  These format flags are used to enable various portions of the packet.  If a particular flag is set then that portion of the output is present.  If it is not set then that portion is not present.  If a portion of the output is not present then the remaining fields are moved ahead in the packet to fill in the gap left by the missing portion.  In other words, the packet is packed.  Trailing zeros are omitted.
 
Some formats and some feature flags may not be supported on a specific platform.  Also, some platforms may have a size limitation and therefore be unable to support the full 73 bytes of the MotionEngine Output message.
 
Motion outputs are formatted as 16-bit, fixed-point, signed numbers.  The binary point of each type of data is different and is specified in the field descriptions below.  The binary point is indicated by Qn where n is the number of fractional bits.  Thus, Q10 indicates 1 sign bit, 5 integer bits, and 10 fractional bits.  Error ranges are formatted as 8-bit, fixed-point, signed numbers.  In this case, for a Q10, the MSB is the sign bit with an implied 3 zeros followed by 7 fractional bits.
 
  
 
Button n:                                   0 - not pressed
                                                     1 - pressed
 
Delta X:                                      Q0. Changes in pointer location along the x-axis in dimensionless units call mickeys.  X positive moves the pointer right.
 
Delta Y:                                      Q0. Changes in pointer location along the y-axis in dimensionless units called mickeys.  Y positive moves the pointer down.
 
Delta Wheel:                             Scroll wheel motion in detects.  Up is positive
  
Linear Accel:                            Q10.  Reported in meters/second(2).  X positive is forward, Y positive is to the right, and Z positive is down with respect to the device frame of reference.
 
Linear Accel No Grav:            Q10.  Reported in meters/second(2).  X positive is forward, Y positive is to the right, and Z positive is down with respect to the device frame of reference.
 
Angular Vel:                              Q10.  Reported in radians/second.  X positive is tilt right (roll), Y positive is tilt up (pitch), and Z positive is turn right (yaw), with respect to the device frame of reference.
 
Magnetometer:                         Q12.  Reported in guass  [only available on 9-axis devices]
 
Linear Position:                        Q10.  [Not supported]
 
Angular Position:                     Q14.  Reported in dimensionless units.  The axes are given in quaternion form where A, B, C, and D represent the real, i, j, and k coefficients.
 
Linear Accel Error:                   Q10.  Reported in meters/second(2).  X positive is forward, Y positive is to the right, and Z positive is down with respect to the device frame of reference.
 
Linear Accel No Grav Error:   Q10.  Reported in meters/second(2).  X positive is forward, Y positive is to the right, and Z positive is down with respect to the device frame of reference.
 
Angular Vel Error:                     Q10.  Reported in radians/second.  X positive is tilt right (roll), Y positive is tilt up (pitch), and Z positive is turn right (yaw), with respect to the device frame of reference.
 
Magnetometer Error:                Q12.  Reported in gauss.
 
Linear Position Error:               [Not supported]
 
Angular Position Error:            Q14.  Reported in dimensionless units.  The axes are given in quaternion form where A, B, C, and D represent the real, i ,j, and k coefficients.