Contributions:XsensMTwLogger

From BCI2000 Wiki
Jump to navigation Jump to search

An BCI2000 extension that records synchronized rotational data into states, using XSens’s MTw motion tracking sensors.

An actual image of a MTw

Location

https://www.bci2000.org/svn/trunk/src/contrib/Extensions/XSensMTwLogger

Versioning

Authors

Alexander Belsten (belsten@neurotechcenter.org)

William Engelhardt (engelhardt@neurotechcenter.org)

Version History

  • 2021-07-06: Initial public release by Alexander Belsten (belsten@neurotechcenter.org)

Source Code Revisions

  • Initial development: 6329
  • Tested under: 6329
  • Known to compile under: 6330
  • Broken since: --

Video Overview



Functional Description

Records the X, Y, and Z positions of multiple Xsens MTw (Motion Tracking - wireless) IMUs (Inertial Measurement Units) to events.

Integration into BCI2000

To enable the extension in your CMake configuration, enable EXTENSIONS_XSENSMTWLOGGER=On in the Extensions folder of the CMake GUI and then generate the BCI2000 Visual Studio solution in CMake. Next, open the solution with Visual Studio and rebuild the signal source module with which you want to use the extension. Once the extension is built into the source module, you can enable it by appending --LogXsensMTw=1 to the source module start executable command in your batch file. Also, --NumberOfMTws=1 needs to be appended as well. Set this equal to the exact number of MTw's you want connected.

Installation and Set-Up

To install the drivers for the MTw Awinda, go to their Software Downloads Page and download the latest stable software package for your operating system for "MTw Awinda." This installs the needed drivers; now BCI2000 can connect to the MTws. Mtws are wireless and communicate with your PC via a USB signal receiver. This signal receiver must be plugged into your computer to record from the MTws. This receiver should be blinking in sync with the MTws when they are recording.

Coordinate System

In the figure below, the orange rectangle is the MTw. Three axes are defined, the X, Y, and Z. X and Z range from -180 to 180 degrees, while Y spans from -90 to 90 degrees. All three coordinates are rotational, which means MTws do not directly measure translational movement.

XSensMTwCoordinateSystem.png

Parameters

User configurable Parameters

The motion trackers are configured in the Source tab within the MTw section.

LogXsensMTw

Set to 0 (uncheck) to disable the MTw logger, or 1 (checked) to enable the logger. This should be set in your batch file by appending --LogXsensMTw=1 to the source module start executable command.

NumberOfMTws

The exact number of MTw's that will be connected. 1 is the default, but this number can go up to as many MTw's as you have. This parameter should be set in your batch file by appending --NumberOfMTws=X, where X is the number of MTw's that will be connected. This parameter can only be set in the batch file and will not appear in the Source tab.

MasterUpdateRate

A default value of 80 Hz. This is the frequency that data is updated from the MTws to BCI2000. Below is a table provided by their MTw Awinda User Manual of the maximum update rates relative to the number of MTws connected.

Maximum Update Rates
Number of MTws Update Rate (Hz)
1-5 120
6-9 100
10 80
11-20 60
21-32 40

DataPrescaler

A default value of 10,000,000. The most efficient prescaler is 11,930,464, but for simplicity’s sake this value is rounded. Details about what this value does is located in Converting Back to Degrees below.

State Variables

MTw1X, MTw1Y, MTw1Z

These states record the three rotational data values per MTw. See the Coordinate System section to see how X, Y, and Z are defined. If more than one MTw is connected, their label will continue to increase by 1, i.e., MTw2X, MTw3X, etc. The MTws connect in order of lowest serial code to highest serial code, so if multiple MTws are being recorded, MTw1 will always have the lowest serial code number. The serial codes and their respective IDs are printed in the operator log for clarity’s sake. This allows you to distinguish what MTw is recording to what state.

Converting Back to Degrees

The MTws record data in units of degrees, with the X and Z axes ranging from -180 to 180 degrees, and the Y axis ranging from -90 to 90 degrees. They also record a high precision of 6 decimal places. BCI2000 records integers to states, which means that anything after the decimal point will be cut off. If the data is kept as is, this would greatly reduce the quality of the data we are collecting.

BCI2000 can record states with up to 32 bits, which is the resolution we need to record the high quality data from the MTws. To do this, the original data will be multiplied by the parameter DataPrescaler, and shifted up by 2^31.

To convert the data back into degrees, use Matlab or a similar program to

  1. Subtract 2^31 from every value.
  2. Divide the data by the DataPrescaler.

This should now leave you with data in degrees!

See also

User Reference:Logging Input, Contributions:Extensions