AmmSensor Software Development Kit

Create your own innovative 3D motion capture and analysis applications
Read acceleration, angular velocity, magnetic field data in real-time
Retrieve sensor orientation data as either Quaternions or unit vectors directly from the Kalman filter
Communicate with multiple sensors simultaneously
Control all functions of the AmmSensor via firmware commands
Read and write sensor firmware information and calibration data
Program in any Windows .Net language using Visual Studio
Royalty free Windows .Net compatible DLL
Transmits data at 250Hz in binary format for fast motion updates
Simple VB demo program included for easy learning curve
Sample application output is stored as ASCII text files and can be automatically sent to a spreadsheet

Description

The AmmSensor is a wireless Bluetooth compatible MEMS 3D sensor device. It is light, small and fast. It combines an accelerometer, gyroscope and magnetometer, all tri-axial, plus a driver software library (DLL) to produce accurate, dynamic sensor orientation data in the form of either Quaternions or unit vectors.

The Software Development Kit (SDK) allows software programmers to create their own applications. It provides access to all the raw sensor outputs (acceleration, angular velocity and Earth’s magnetic field direction), plus calculated outputs of dynamic sensor orientation in the form of either Quaternions or unit vectors.

The AmmSensor SDK is developed in Visual Studio 2008 using C# and the .Net platform. This allows it to run on all current versions of Microsoft Windows including Windows 7, Vista and XP.

The SDK includes a Dynamic Linked Library whose functions can be called from programs developed by the user. Any .Net compatible language can be used; C++, C# and VB. Comprehensive documentation on the function calls and the firmware commands that control the sensor are included.

Also included is a sample program called AmmSampleApp. This program shows how to connect to the sensor via Bluetooth using a COM port, and how to extract and display data in real-time. It also allows the user to capture and save the data directly to a spreadsheet. The resultant file is a comma delimited ASCII text file.

Note that you will need a Windows computer that has Bluetooth capability that is already installed and Visual Studio 2008 with VB to view and run the sample application. This sample application can be used as the basis for applications created by the user.

Definitions of Output Data

Raw Data

Data that has not been calibrated and is still in raw count units directly from the sensors in question. Really only useful for development and testing.

Count

The current sample count number; cycles from 1001 to 16000 then starts again.

Count

m_raw_count

Cycle

The number of cycles that Count has cycled through.

Cycle

m_raw_cycle

Temp

The internal temperature of the sensor in raw units.

RawTemp

m_raw_temp

Unique ID

This is the current sample count from the time that the AmmSensor began communicating.

m_raw_uniqueID

UniqueCount

Raw Ax, Ay, Az

Acceleration vector from the 3-axis accelerometer; measured with respect to the local coordinate axes of the sensor; in raw count units. These values represent how much the sensor is accelerating in a linear sense. Note that gravity is included in this vector.

RawAccelX, RawAccelY, RawAccelZ

m_raw_accX, m_raw_accY, m_raw_accZ

Raw Mx, My, Mz

Magnetometer vector from the 3-axis magnetometer; measured with respect to the local coordinate axes of the sensor; in raw count units. These values represent a vector that is pointing to magnetic north. Note that it is not parallel to the ground and in fact points into the ground.

RawMagX, RawMagY, RawMagZ

m_raw_magX, m_raw_magY, m_raw_magZ

Raw Gx, Gy, Gz

Angular rotation rate vector from the 3-axis gyro; measured with respect to the local coordinate axes of the sensor; in raw count units. These values represent how fast the sensor is spinning around each of its axes.

RawGyroX, RawGyroY, RawGyroZ

m_raw_gyroX, m_raw_gyroY, m_raw_gyroZ

Converted Data

Data that has been converted into physical units using the calibration parameters. Calibration is done at the factory and is stored in the memory of the sensor. Each sensor has its own unique calibration parameters.

Time

Time in seconds since started.

Time

m_conv_time

Temp

Still same as raw temp, has not as yet been scaled.

ConvTemp

m_conv_temp

Ax, Ay, Az

Scaled accelerometer vector; measured with respect to the local coordinate axes of the sensor; in m/s/s. Note that gravity is included in this vector.

RawAccelX, RawAccelY, RawAccelZ

m_conv_accX, m_conv_accY, m_conv_accZ

Mx, My, Mz

Normalized magnetometer unit vector; values for each parameter range between 1 and -1. The vector is given with respect to the local coordinate system of the sensor. This is just a directional unit vector and so has no units.

RawMagX, RawMagY, RawMagZ

m_conv_magX, m_conv_magY, m_conv_magZ

Gx, Gy, Gz

Scaled angular velocity vector, measured with respect to the local coordinate axes of the sensor; in degrees per second. This is the one to use if you want angular velocity.

RawGyroX, RawGyroY, RawGyroZ

m_conv_gyroX, m_conv_gyroY, m_conv_gyroZ

Processed Data

More sophisticated algorithms are used to produce more accurate and extra derived parameters from a combination of the values from each of the different types of sensors on the AmmSensor. These algorithms may include integration, derivation and a complex Kalman filter.

Processed Time

Time in seconds since communication with AmmSensor began, same as ConvTime

Time

m_proc_time

Sensor Unit Vectors

These nine values give the orientation of the sensor at any point in time, with respect to the global reference frame. They are in fact the end point coordinate values of each sensor’s normalized internal axis; their values range between 1 and -1. The global reference frame is created from the gravity vector and the magnetic north vector.

The sensor x-axis coordinate end points measured with respect to the global reference frame are:

Xx, Xy, Xz

m_proc_rotMat00, m_proc_rotMat10, m_proc_rotMat20

The sensor y-axis coordinate end points measured with respect to the global reference frame are:

Yx, Yy, Yz

m_proc_rotMat01, m_proc_rotMat11, m_proc_rotMat21

The sensor z-axis coordinate end points measured with respect to the global reference frame are:

Zx, Zy, Zz

m_proc_rotMat02, m_proc_rotMat12, m_proc_rotMat22

Quaternions

Another convenient way of representing sensor orientation. This method uses only four components instead of nine as with unit vectors and so is more compact. See Wikipedia for more information.

QuaternionW, QuaternionX, QuaternionY, QuaternionZ

m_proc_quatW, m_proc_quatX, m_proc_quatY, m_proc_quatZ

Inertial Linear Acceleration

This vector quantity is the linear acceleration of the sensor as created by movement only; measured in m/s². The gravity vector is subtracted out. This process can only be done if the orientation of the sensor is known, i.e. we know where down is so gravity (9.81m/s²) can be subtracted away. Once this is done we know exactly what acceleration is created by movement alone. When the sensor is not moving this value should be zero. The values are given with respect to the global reference frame.

InertialAccelX, InertialAccelY, InertialAccelZ

m_proc_globalAccX, m_proc_globalAccY, m_proc_globalAccZ

Angular Acceleration

The angular velocity vector is differentiated to produce the angular acceleration vector; measured in rad/s² and given as its three components. It is given with respect to the sensor local axes.

AngularAccelX, AngularAccelY, AngularAccelZ

m_proc_gyroConvAccX, m_proc_gyroConvAccY, m_proc_gyroConvAccZ

Linear Velocity and Linear Position

Linear velocity (m/s) is produced from the integration of the inertial linear acceleration and linear position (m) is produced from the integration of the linear velocity. The initial position of the sensor is considered to be the origin and measurements are given with respect to the global reference frame. These quantities suffere from substantial integration drift; there is a reset function supplied that should be used before every use.

PositionX, PositionY, PositionZ

m_proc_globalPosX, m_proc_globalPosY, m_proc_globalPosZ

LinearVelX, LinearVelY, LinearVelZ

m_proc_globalVelX, m_proc_globalVelY, m_proc_globalVelZ

BOTH OF THESE VECTORS SUFFER FROM SIGNIFICANT DRIFT AND ARE OF MARGINAL VALUE. THEY ARE SUPPLIED FOR COMPLETENESS ONLY AND ARE NOT CONSIDERED ACCURATE.

Global Reference Frame

Z-axis is vertical pointing up

X-axis points in the direction of magnetic North

Y-axis is perpendicular to X and Z-axes pointing West

X, Y and Z axes form a right handed coordinate system

AmmSensor Unit Vectors

The Unit Vectors completely define the orientation of the AmmSensor local coordinate system. There are relatively simple equations available that allow you to convert these values into various types of orientation angles, including Euler angles and Joint Angle. AMM can help with these equations.