.. highlight:: java

Sensor Fusion
=============

The `SensorFusion <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/SensorFusion.html>`_ module interacts with the 
sensor fusion algorithm running on MetaMotion boards.  When using the sensor fusion algorithm, it is important that you do not simultaenously use the 
Accelerometer, Gyro, and Magnetometer modules; the algorithm configures those sensors internally based on how you configure the sensor fusion algorithm.

To activate the sensor fusion algorithm, first set the fusion mode and data ranges, then call `start <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/SensorFusion.html#start-com.mbientlab.metawear.module.SensorFusion.DataOutput...->`_ with the desired algorithm data, 
enumerated by the `DataOutput <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/SensorFusion.DataOutput.html>`_ enum.

Mode
----
The sensor fusion algorithm has 4 
`fusion modes <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/SensorFusion.Mode.html>`_, listed in the below table:

======== ==========================================================================
Mode     Description                             
======== ==========================================================================
NDoF     Calculates absolute roeintation from accelerometer, gyro, and magnetometer
IMUPlus  Calculates relative orientation in space from accelerometer and gyro data
Compass  Determines geographic direction from th Earth's magnetic field
M4G      Similar to IMUPlus except rotation is detected with the magnetometer
======== ==========================================================================

The mode is set via a `ConfigEditor <https://mbientlab.com/docs/metawear/android/2/com/mbientlab/metawear/module/SensorFusion.ConfigEditor.html>`_ 
object which is retrieved by calling configure.  ::

    import com.mbientlab.metawear.module.SensorFusion;

    // Set mode to NDoF, accel range to +/-8G
    // Note that accel range is not set through the Accelerometer module
    final SensorFusion sensorFusion = mwBoard.getModule(SensorFusion.class);
    sensorFusion.configure()
        .setMode(SensorFusion.Mode.NDOF)
        .setAccRange(SensorFusion.AccRange.AR_8G)
        .commit();


Data
----
The sensor fusion algorithm provides raw acceleration, rotation, and magnetic field values along with quaternion values and Euler angles.  Furthermore, 
the source of acceleration can be separated into gravity and linear acceleration and both values are also provided.  Keep in mind that each sensor  
fusion mode has different sets of available data and produces it at different rates.

======== ===== ===== ====
Mode     Acc   Gyro  Mag                       
======== ===== ===== ====
NDoF     100Hz 100Hz 25Hz
IMUPlus  100Hz 100Hz N/A
Compass  25Hz  N/A   25Hz
M4G      50Hz  N/A   50Hz
======== ===== ===== ====

Also note that the units and type casting of the sensor fusion data is different for each type of data..

============== ======= =======================
Data           Units   Casted Data
============== ======= =======================
Acceleration    g      CorrectedCartesianFloat
Rotation       deg/s   CorrectedCartesianFloat
Magnetic Field uT      CorrectedCartesianFloat
Quaternion      None   Quaternion
Euler Angles   degrees EulerAngle
Linear Acc      g      CartesianFloat
Gravity         g      CartesianFloat
============== ======= =======================

::

    // stream quaternion values from the board
    sensorFusion.routeData().fromQuaternions().stream("quaternion").commit()
        .onComplete(new CompletionHandler<RouteManager>() {
            @Override
            public void success(RouteManager result) {
                result.subscribe("quaternion", new MessageHandler() {
                    @Override
                    public void process(Message msg) {
                        Log.i("example", msg.getData(SensorFusion.Quaternion.class).toString());
                    }
                });
                sensorFusion.start(SensorFusion.DataOutput.QUATERNIONS);
            }
        });