Contributions:CyberGloveLogger

From BCI2000 Wiki
Jump to: navigation, search

Synopsis

A framework extension that logs state information from the CyberGlove into state variables.

Location

http://www.bci2000.org/svn/trunk/src/contrib/Extensions/CyberGloveLogger

Versioning

Author

Sidhant Sharma (ssharma@cyberglovesystems.com)

Version History

  • 03/11/2014 sidhantsharma: Initial version;
    • Supports 18 and 22 Sensor CyberGlove Models (wired & wireless versions)
    • Maximum 2 CyberGloves supported

Functional Description

The 18-sensor data glove features two bend sensors on each finger, four abduction sensors, plus sensors measuring thumb crossover, palm arch, wrist flexion, and wrist abduction.

The 22-sensor data glove has three flexion sensors per finger, four abduction sensors, a palm-arch sensor, and sensors to measure wrist flexion and abduction. Each sensor is extremely thin and flexible being virtually undetectable in the lightweight elastic glove.

The wireless CGIII motion capture system has been used in a wide variety of real-world applications, including digital prototype evaluation, virtual reality bio-mechanics, and animation. Specifications:

  • Number of sensors: 18 or 22
  • Sensor resolution: <1 degree
  • Sensor repeatability: 3 degrees (average standard deviation between wearings
  • Sensor linearity: maximum 0.6% standard deviation nonlinearity over full joint range
  • Sensor data rate: Up to 100 records/sec (SD card); up to 120 records/sec (USB and Wi-Fi)
  • Operating system and hosts: Windows 7 32 bit and 64 bit
  • Wireless technology: 802.11g Wi-Fi
  • Battery duration: 2 hours
  • Battery charger: External
  • Operating range: 100+ feet radius from Wi-Fi source (optimal environment)
  • Interface: 802.11g Wi-Fi, USB, micro SD card

Vendor

CyberGloves can be purchased from http://www.cyberglovesystems.com. The data glove product lines include CGI, CGII and CGIII. CGI is the wired version whereas CGII and CGIII work via Bluetooth and Wireless Technology respectively. Every CyberGlove comes with a User Manual, Drivers and UI software for Windows. A C++ based VirtualHand SDK is also available which includes a variety of demos and sample source code.

Integration into BCI2000

Compile the extension into your source module by enabling contributed extensions in your CMake configuration. You can do this by going into your root build folder and deleting CMakeCache.txt and re-running the project batch file, or by running cmake -i and enabling BUILD_CYBERGLOVELOGGER.

Once the extension is built into the source module, enable it by starting the source module with the --LogCyberGlove=1 command line argument. The 'CGS_VirtualHandDevice.dll, CGS_VirtualHandRegistry.dll and CGS_DeviceManagerCore.dll' dynamic link libraries have to be in the same directory as the executable module. Refer to CyberGloveLogger Extension Prerequisites/Requirements for useful information regarding using this extension.

CyberGloveLogger Extension Prerequisites/Requirements

CyberGlove DCU interface
- The CyberGloveSystems Software/drivers must be installed on the system before hand. 
- The recommended version is CyberGloveSystems SDK3.1.3 (32 bit) for Windows 7.
- The supported platforms are listed in the section Supported Platforms 
- A cyberglove must be connected/live in the DCU (Device Configuration Utility) interface each time for using the 
  CyberGloveLogger extension.
- The configuration in the DCU should be default (Configuration 1).
- A right handed glove has to be named RightGlove in the DCU.
- A left handed glove has to be named LeftGlove in the DCU.
- For recording two gloves simultaneously, both gloves should be connected in the DCU 
  and renamed as RightGlove and LeftGlove accordingly as in the image (Click to enlarge).
- If either of the gloves added in the DCU is not live/connected, an error message will pop up in BCI. 
- This will require you to check the connection or reconnect the glove in the DCU.
- The user manual that comes with the CyberGlove explains how to use and connect gloves in the DCU.

Supported Platforms

  • Windows XP, Windows Vista, Windows 7 32-bit, Windows 7 64-bit

Parameters

The CyberGlove is configured in the "Source" panel under the "Log Input" section

LogCyberGlove

The command-line parameter to enable the CyberGloveLogger is repeated here.

DataGloveDerivative

Whether to read positions(raw sensor values) or changes in position.

DataGloveHandedness

A list of "left" and "right" strings. For a single glove, it will be either "left" or "right" depending on the handedness. For two gloves, if you set this to "left right" then the first left-handed glove found will become glove 1 and the first right-handed glove found will become glove 2. Swapping the order, that is "right left" will make the first right handed glove as glove 1 and the first left handed glove as glove 2. Accordingly the data will be recorded into the states for each glove. You can also use "R" or "L" for 1 glove. "R L" or "L R" for 2 gloves (order is not important).

State Variables

The state name encodes the glove number (examples are shown below for CyberGlove1*; additional glove will have higher number). Secondly, the sensors numbers are 2 digits (Sensor01, Sensor02, etc).

The 22 Sensor CyberGlove sensor mapping is given in the table below. Note that the State CyberGlove1Sensor08 is always 0 or N/A.

For the 18 Sensor CyberGlove, additionally the outer joint raw sensor values for the index, ring, middle, and pinky fingers are all 0's.

 ----------------------------------------------------------------
 StateName           == Sensor                  | 18 sensor    | 22 sensor 
 ----------------------------------------------------------------
 CyberGlove1Sensor01 == ThumbRoll               | roll         | roll  
 CyberGlove1Sensor02 == ThumbInnerJoint         | flexure      | flexure 
 CyberGlove1Sensor03 == ThumbOuterJoint         | flexure      | flexure
 CyberGlove1Sensor04 == ThumbIndexAbduction     | abduction    | abduction
 CyberGlove1Sensor05 == IndexInnerJoint         | flexure      | flexure
 CyberGlove1Sensor06 == IndexMiddleJoint        | flexure      | flexure
 CyberGlove1Sensor07 == IndexOuterJoint         | N/A          | flexure
 CyberGlove1Sensor08 == EMPTY                   | N/A          | N/A
 CyberGlove1Sensor09 == MiddleInnerJoint        | flexure      | flexure
 CyberGlove1Sensor10 == MiddleMiddleJoint       | flexure      | flexure 
 CyberGlove1Sensor11 == MiddleOuterJoint        | N/A          | flexure
 CyberGlove1Sensor12 == MiddleIndexAbduction    | abduction    | abduction 
 CyberGlove1Sensor13 == RingInnerJoint          | flexure      | flexure
 CyberGlove1Sensor14 == RingMiddleJoint         | flexure      | flexure
 CyberGlove1Sensor15 == RingOuterJoint          | N/A          | flexure 
 CyberGlove1Sensor16 == RingMiddleAbduction     | abduction    | abduction
 CyberGlove1Sensor17 == PinkyInnerJoint         | flexure      | flexure
 CyberGlove1Sensor18 == PinkyMiddleJoint        | flexure      | flexure
 CyberGlove1Sensor19 == PinkyOuterJoint         | N/A          | flexure
 CyberGlove1Sensor20 == PinkyRingAbduction      | abduction    | abduction 
 CyberGlove1Sensor21 == PalmArch                | arch         | arch
 CyberGlove1Sensor22 == WristFlexion            | flexure      | flexure 
 CyberGlove1Sensor23 == WristAbduction          | abduction    | abduction
 ----------------------------------------------------------------


Troubleshooting

  • The following error will be encountered if Cyberglove drivers are not installed previously, and logging is enabled with --LogCyberGlove=1. To avoid this error, CyberGlove Systems 32-bit drivers must be installed on the system. The supported platforms are Windows XP, Vista, Windows 7 32-bit, and Windows 7-64 bit.
Error: CyberGlove Drivers not installed (Click to enlarge image)
  • The cyberglove definitions in the DCU are shown in the following images. The configuration used must be the default configuration (Configuration 1). A single right-handed glove should be named as RightGlove and a single left-handed glove should be named as LeftGlove. In the case of 2 gloves, the gloves should be named RightGlove and LeftGlove respectively.
Single right-handed glove definition (Click to enlarge image)
Single left-handed glove definition (Click to enlarge image)
Definition for two gloves (Click to enlarge image)
  • The gloves must be live in the DCU before using the CyberGloveLogger extension in BCI2000. The CyberGlove user manual, that comes with the gloves, explains how to connect the gloves in the DCU. To avoid error messages, add and connect the gloves in the DCU following proper naming convention as specified in CyberGloveLogger Extension Prerequisites/Requirements. Make sure the Device Manager is also running along with the DCU. The Device Manager automatically runs with the DCU application on Windows 7 systems. On Windows XP and Vista systems, the Device Manager has to be run separately followed by the DCU.
CyberGlove DCU(top image)and Device Manager(bottom image)

See also

User Reference:Logging Input, Contributions:Extensions