This header file defines the ThinkGear Communications Driver (TGCD) API, which is a set of functions for users to connect to and receive data from a ThinkGear data stream. More...

Macros
#define	THINKGEAR_API extern

#define	WINVER 0x0501

#define	TG_MAX_CONNECTION_HANDLES 128
	Maximum number of Connections that can be requested before being required to free one. More...

#define	TG_BAUD_1200 1200
	Baud rate for use with TG_Connect() and TG_SetBaudrate(). More...

#define	TG_BAUD_2400 2400

#define	TG_BAUD_4800 4800

#define	TG_BAUD_9600 9600

#define	TG_BAUD_57600 57600

#define	TG_BAUD_115200 115200

#define	TG_STREAM_PACKETS 0
	Data format for use with TG_Connect() and TG_SetDataFormat(). More...

#define	TG_STREAM_5VRAW 1

#define	TG_STREAM_FILE_PACKETS 2

#define	TG_DATA_BATTERY 0
	Data types that can be requested from TG_GetValue(). More...

#define	TG_DATA_POOR_SIGNAL 1

#define	TG_DATA_ATTENTION 2

#define	TG_DATA_MEDITATION 3

#define	TG_DATA_RAW 4

#define	TG_DATA_DELTA 5

#define	TG_DATA_THETA 6

#define	TG_DATA_ALPHA1 7

#define	TG_DATA_ALPHA2 8

#define	TG_DATA_BETA1 9

#define	TG_DATA_BETA2 10

#define	TG_DATA_GAMMA1 11

#define	TG_DATA_GAMMA2 12

#define	TG_DATA_BLINK_STRENGTH 37

Functions
THINKGEAR_API int	TG_GetDriverVersion ()
	Returns a number indicating the version of the ThinkGear Communications Driver (TGCD) library accessed by this API. More...

THINKGEAR_API int	TG_GetNewConnectionId ()
	Returns an ID handle (an int) to a newly-allocated ThinkGear Connection object. More...

THINKGEAR_API int	TG_SetStreamLog (int connectionId, const char *filename)
	As a ThinkGear Connection reads bytes from its serial stream, it may automatically log those bytes into a log file. More...

THINKGEAR_API int	TG_SetDataLog (int connectionId, const char *filename)
	As a ThinkGear Connection reads and parses Packets of data from its serial stream, it may log the parsed data into a log file. More...

THINKGEAR_API int	TG_WriteStreamLog (int connectionId, int insertTimestamp, const char *msg)

THINKGEAR_API int	TG_WriteDataLog (int connectionId, int insertTimestamp, const char *msg)

THINKGEAR_API int	TG_EnableLowPassFilter (int connectionId, int rawSamplingRate)
	As a ThinkGear Connection reads and parses raw EEG wave values (via the TG_ReadPackets() function), the driver can automatically apply a 30Hz low pass filter to the raw wave data. More...

THINKGEAR_API int	TG_EnableBlinkDetection (int connectionId, int enable)
	Enables and disables the non-embedded eye blink detection. More...

THINKGEAR_API int	TG_Connect (int connectionId, const char *serialPortName, int serialBaudrate, int serialDataFormat)
	Connects a ThinkGear Connection, given by `connectionId`, to a serial communication (COM) port in order to communicate with a ThinkGear module. More...

THINKGEAR_API int	TG_ReadPackets (int connectionId, int numPackets)
	Attempts to use the ThinkGear Connection, given by `connectionId`, to read `numPackets` of data from the serial stream. More...

THINKGEAR_API int	TG_GetValueStatus (int connectionId, int dataType)
	Returns Non-zero if the `dataType` was updated by the most recent call to TG_ReadPackets(). More...

THINKGEAR_API float	TG_GetValue (int connectionId, int dataType)
	Returns the most recently read value of the given `dataType`, which is one of the TG_DATA_* constants defined above. More...

THINKGEAR_API int	TG_SendByte (int connectionId, int b)
	Sends a byte through the ThinkGear Connection (presumably to a ThinkGear module). More...

THINKGEAR_API int	TG_SetBaudrate (int connectionId, int serialBaudrate)
	Attempts to change the baud rate of the ThinkGear Connection, given by `connectionId`, to `serialBaudrate`. More...

THINKGEAR_API int	TG_SetDataFormat (int connectionId, int serialDataFormat)
	Attempts to change the data Packet parsing format used by the ThinkGear Connection, given by `connectionId`, to `serialDataFormat`. More...

THINKGEAR_API int	TG_EnableAutoRead (int connectionId, int enable)
	Enables or disables background auto-reading of the connection. More...

THINKGEAR_API void	TG_Disconnect (int connectionId)
	Disconnects the ThinkGear Connection, given by `connectionId`, from its serial communication (COM) port. More...

THINKGEAR_API void	TG_FreeConnection (int connectionId)
	Frees all memory associated with the given ThinkGear Connection. More...

Detailed Description

This header file defines the ThinkGear Communications Driver (TGCD) API, which is a set of functions for users to connect to and receive data from a ThinkGear data stream.

There are three "tiers" of functions in this API, where functions of a lower "tier" should not be called until an appropriate function in the "tier" above it is called first:

Tier 1:  Call anytime
    TG_GetDriverVersion()
    TG_GetNewConnectionId()
Tier 2:  Requires TG_GetNewConnectionId()
    TG_SetStreamLog()
    TG_SetDataLog()
    TG_EnableLowPassFilter()
    TG_Connect()
    TG_FreeConnection()
Tier 3:  Requires TG_Connect()
    TG_ReadPackets()
    TG_GetValueStatus()
    TG_GetValue()
    TG_SendByte()
    TG_SetBaudrate()
    TG_SetDataFormat()
    TG_Disconnect()

Regarding preprocessor macro constants: Typical users do not need to (and should NOT) define any special macros in order to use this header file with a ThinkGear Communications Driver shared library (i.e. .dll or .so). The following macros should only be defined by maintainers of the ThinkGear Communications Driver shared library itself: THINKGEAR_DLL_COMPILE (or NO_DLL_MODIFIERS) COMPILE_FOR_JNI

Author: Kelvin Soo

Version

4.2 Sep 28, 2009 Kelvin Soo

Added TG_EnableLowPassFilter() function. Compatible with TGCD version 10 and above.

4.1 Jun 26, 2009 Kelvin Soo

Updated name of library from ThinkGear Connection API to ThinkGear Communications Driver (TGCD). The library still uses ThinkGear Connection objects and IDs to communicate.

4.0 May 14, 2008 Kelvin Soo

Overhauled API entirely to support new features of ThinkGear-EM.

3.2 Nov 29, 2007 Kelvin Soo

Initial version.

Macro Definition Documentation

#define TG_BAUD_115200 115200

#define TG_BAUD_1200 1200

Baud rate for use with TG_Connect() and TG_SetBaudrate().

#define TG_BAUD_2400 2400

#define TG_BAUD_4800 4800

#define TG_BAUD_57600 57600

#define TG_BAUD_9600 9600

#define TG_DATA_ALPHA1 7

#define TG_DATA_ALPHA2 8

#define TG_DATA_ATTENTION 2

#define TG_DATA_BATTERY 0

Data types that can be requested from TG_GetValue().

Only certain data types are output by certain ThinkGear chips and headsets. Please refer to the Communications Protocol document for your chip/headset to determine which data types are available for your hardware.

#define TG_DATA_BETA1 9

#define TG_DATA_BETA2 10

#define TG_DATA_BLINK_STRENGTH 37

#define TG_DATA_DELTA 5

#define TG_DATA_GAMMA1 11

#define TG_DATA_GAMMA2 12

#define TG_DATA_MEDITATION 3

#define TG_DATA_POOR_SIGNAL 1

#define TG_DATA_RAW 4

#define TG_DATA_THETA 6

#define TG_MAX_CONNECTION_HANDLES 128

Maximum number of Connections that can be requested before being required to free one.

#define TG_STREAM_5VRAW 1

#define TG_STREAM_FILE_PACKETS 2

#define TG_STREAM_PACKETS 0

Data format for use with TG_Connect() and TG_SetDataFormat().

#define THINKGEAR_API extern

#define WINVER 0x0501

Function Documentation

THINKGEAR_API int TG_Connect	(	int	connectionId,
		const char *	serialPortName,
		int	serialBaudrate,
		int	serialDataFormat
	)

Connects a ThinkGear Connection, given by connectionId, to a serial communication (COM) port in order to communicate with a ThinkGear module.

It is important to check the return value of this function before attempting to use the Connection further for other functions in this API.

Parameters

connectionId	The ID of the ThinkGear Connection to connect, as obtained from TG_GetNewConnectionId().
serialPortName	The name of the serial communication (COM) stream port. COM ports on PC Windows systems are named like '' (remember that backslashes in strings in most programming languages need to be escaped), while COM ports on Windows Mobile systems are named like 'COM4:' (note the colon at the end). Linux COM ports may be named like '/dev/ttys0'. Refer to the documentation for your particular platform to determine the available COM port names on your system.
serialBaudrate	The baudrate to use to attempt to communicate on the serial communication port. Select from one of the TG_BAUD_* constants defined above, such as TG_BAUD_9600 or TG_BAUD_57600.
serialDataFormat	The type of ThinkGear data stream. Select from one of the TG_STREAM_* constants defined above. Most applications should use TG_STREAM_PACKETS (the data format for Embedded ThinkGear). TG_STREAM_5VRAW is supported only for legacy non-embedded purposes.

Returns: -1 if connectionId does not refer to a valid ThinkGear Connection ID handle.; -2 if serialPortName could not be opened as a serial communication port for any reason. Check that the name is a valid COM port on your system.; -3 if serialBaudrate is not a valid TG_BAUD_* value.; -4 if serialDataFormat is not a valid TG_STREAM_* type.; 0 on success.

THINKGEAR_API void TG_Disconnect ( int connectionId )

Disconnects the ThinkGear Connection, given by connectionId, from its serial communication (COM) port.

Note that after this call, the Connection will not be valid to use with any of the API functions that require a valid ThinkGear Connection, except TG_SetStreamLog(), TG_SetDataLog(), TG_Connect(), and TG_FreeConnection().

Note that TG_FreeConnection() will automatically disconnect a Connection as well, so it is not necessary to call this function unless you wish to reuse the connectionId to call TG_Connect() again.

Parameters

connectionId The ID of the ThinkGear Connection to disconnect, as obtained from TG_GetNewConnectionId().

THINKGEAR_API int TG_EnableAutoRead	(	int	connectionId,
		int	enable
	)

Enables or disables background auto-reading of the connection.

This has the following implications:

Setting enabled to anything other than 0 will enable background auto-reading on the specified connection. Setting enabled to 0 will disable it.
Enabling causes a background thread to be spawned for the connection (only if one was not already previously spawned), which continuously calls TG_ReadPacket( connectionId, -1 ) at 1ms intervals.
Disabling will kill the background thread for the connection.
While background auto-reading is enabled, the calling program can use TG_GetValue() at any time to get the most-recently-received value of any data type. The calling program will have no way of knowing when a value has been updated. For most data types other than raw wave value, this is not much of a problem if the program simply polls TG_GetValue() once a second or so.
The current implementation of this function will not include proper data synchronization. This means it is possible for a value to be read (by TG_GetValue()) at the same time it is being written to by the background thread, resulting in a corrupted value being read. However, this is extremely unlikely for most data types other than raw wave value.
While background auto-reading is enabled, the TG_GetValueStatus() function is pretty much useless. Also, the TG_ReadPackets() function should probably not be called.

Parameters

connectionId	The connection to enable/disable background auto-reading on.
enable	Zero (0) to disable background auto-reading, any other value to enable.

Returns: -1 if connectionId does not refer to a valid ThinkGear Connection ID handle.; -2 if unable to enable background auto-reading.; -3 if an error occurs while attempting to disable background auto-reading.; 0 on success.

THINKGEAR_API int TG_EnableBlinkDetection	(	int	connectionId,
		int	enable
	)

Enables and disables the non-embedded eye blink detection.

Non-embedded blink detection is disabled by default.

NOTE: The constants and thresholds for the eye blink detection is adjusted for TGAM1 only.

Parameters

connectionId	The ID of the ThinkGear Connection to enable low pass filtering for, as obtained from TG_GetNewConnectionId().
enable	Enables or disables the non-embedded eye blink detection.

Returns: -1 if connectionId does not refer to a valid ThinkGear Connection ID handle.; 0 on success.

THINKGEAR_API int TG_EnableLowPassFilter	(	int	connectionId,
		int	rawSamplingRate
	)

As a ThinkGear Connection reads and parses raw EEG wave values (via the TG_ReadPackets() function), the driver can automatically apply a 30Hz low pass filter to the raw wave data.

Subsequent calls to TG_GetValue() on TG_DATA_RAW will therefore return the filtered value. This is sometimes useful for visualizing (displaying) the raw wave when the ThinkGear is in an electrically noisy environment. This function only applies the filtering within the driver and does not affect the behavior of the ThinkGear hardware in any way. This function may be called at any time after calling TG_GetNewConnectionId().

Automatic low pass filtering is disabled by default.

NOTE: Automatic low pass filtering is currently only applicable to ThinkGear hardware that samples raw wave at 512Hz (such as TGAM in MindSet). It is not applicable to hardware that samples at 128Hz or 256Hz and should NOT be enabled for those hardware.

Parameters

connectionId	The ID of the ThinkGear Connection to enable low pass filtering for, as obtained from TG_GetNewConnectionId().
rawSamplingRate	Specify the sampling rate that the hardware is currently sampling at. Set this to 0 (zero) or any invalid rate at any time to immediately disable the driver's automatic low pass filtering. NOTE: Currently, the only valid raw sampling rate is 512 (MindSet headsets). All other rates will return -2.

Returns: -1 if connectionId does not refer to a valid ThinkGear Connection ID handle.; -2 if rawSamplingRate is not a valid rate. Currently only a sampling rate of 512 (Hz) is valid (which is the raw sampling rate of MindSet headsets.; 0 on success.

THINKGEAR_API void TG_FreeConnection ( int connectionId )

Frees all memory associated with the given ThinkGear Connection.

Note that this function will automatically call TG_Disconnect() to disconnect the Connection first, if appropriate, so that it is not necessary to explicitly call TG_Disconnect() at all, unless you wish to reuse the connectionId without freeing it first for whatever reason.

Parameters

connectionId The ID of the ThinkGear Connection to disconnect, as obtained from TG_GetNewConnectionId().

THINKGEAR_API int TG_GetDriverVersion ( )

Returns a number indicating the version of the ThinkGear Communications Driver (TGCD) library accessed by this API.

Useful for debugging version-related issues.

Returns: The TGCD library's version number.

THINKGEAR_API int TG_GetNewConnectionId ( )

Returns an ID handle (an int) to a newly-allocated ThinkGear Connection object.

The Connection is used to perform all other operations of this API, so the ID handle is passed as the first argument to all functions of this API.

When the ThinkGear Connection is no longer needed, be sure to call TG_FreeConnection() on the ID handle to free its resources. No more than TG_MAX_CONNECTION_HANDLES Connection handles may exist simultaneously without being freed.

Returns: -1 if too many Connections have been created without being freed by TG_FreeConnection().; -2 if there is not enough free memory to allocate to a new ThinkGear Connection.; The ID handle of a newly-allocated ThinkGear Connection.

THINKGEAR_API float TG_GetValue	(	int	connectionId,
		int	dataType
	)

Returns the most recently read value of the given dataType, which is one of the TG_DATA_* constants defined above.

Use TG_ReadPackets() to read more Packets in order to obtain updated values. Afterwards, use TG_GetValueStatus() to check if a call to TG_ReadPackets() actually updated a particular dataType.

NOTE: This function will terminate the program with a message printed to stderr if connectionId is not a valid ThinkGear Connection, or if dataType is not a valid TG_DATA_* constant.

Parameters

connectionId The ID of the ThinkGear Connection to get a data value from, as obtained from TG_GetNewConnectionId().

dataType The type of data value desired. Select from one of the TG_DATA_* constants defined above. Although many types of TG_DATA_* constants are available, each model of ThinkGear hardware and headset will only output a certain subset of these data types. Refer to the Communication Protocol document for your particular ThinkGear hardware or headset to determine which data types are actually output by that hardware or headset. Data types that are not output by the headset will always return their default value of 0.0 when this function is called.

Returns: The most recent value of the requested dataType.

THINKGEAR_API int TG_GetValueStatus	(	int	connectionId,
		int	dataType
	)

Returns Non-zero if the dataType was updated by the most recent call to TG_ReadPackets().

Returns 0 otherwise.

Parameters

connectionId	The ID of the ThinkGear Connection to get a data value from, as obtained from TG_GetNewConnectionId().
dataType	The type of data value desired. Select from one of the TG_DATA_* constants defined above.

NOTE: This function will terminate the program with a message printed to stderr if connectionId is not a valid ThinkGear Connection, or if dataType is not a valid TG_DATA_* constant.

Returns: Non-zero if the dataType was updated by the most recent call to TG_GetValue(). Returns 0 otherwise.

THINKGEAR_API int TG_ReadPackets	(	int	connectionId,
		int	numPackets
	)

Attempts to use the ThinkGear Connection, given by connectionId, to read numPackets of data from the serial stream.

The Connection will (internally) "remember" the most recent value it has seen of each possible ThinkGear data type, so that any subsequent call to TG_GetValue() will return the most recently seen values.

Set numPackets to -1 to attempt to read all Packets of data that may be currently available on the serial stream.

Note that different models of ThinkGear hardware and headsets may output different types of data values at different rates. Refer to the "Communications Protocol" document for your particular headset to determine the rate at which you need to call this function.

Parameters

connectionId	The ID of the ThinkGear Connection which should read packets from its serial communication stream, as obtained from TG_GetNewConnectionId().
numPackets	The number of data Packets to attempt to read from the ThinkGear Connection. Only the most recently read value of each data type will be "remembered" by the ThinkGear Connection. Setting this parameter to -1 will attempt to read all currently available Packets that are on the data stream.

Returns: -1 if connectionId does not refer to a valid ThinkGear Connection ID handle.; -2 if there were not even any bytes available to be read from the Connection's serial communication stream.; -3 if an I/O error occurs attempting to read from the Connection's serial communication stream.; The number of Packets that were successfully read and parsed from the Connection.

THINKGEAR_API int TG_SendByte	(	int	connectionId,
		int	b
	)

Sends a byte through the ThinkGear Connection (presumably to a ThinkGear module).

This function is intended for advanced ThinkGear Command Byte operations.

WARNING: Always make sure at least one valid Packet has been read (i.e. through the TG_ReadPackets() function) at some point BEFORE calling this function. This is to ENSURE the Connection is communicating at the right baud rate. Sending Command Byte at the wrong baud rate may put a ThinkGear module into an indeterminate and inoperable state until it is reset by power cycling (turning it off and then on again).

NOTE: After sending a Command Byte that changes a ThinkGear baud rate, you will need to call TG_SetBaudrate() to change the baud rate of your connectionId as well. After such a baud rate change, it is important to check for a valid Packet to be received by TG_ReadPacket() before attempting to send any other Command Bytes, for the same reasons as describe in the WARNING above.

Parameters

connectionId	The ID of the ThinkGear Connection to send a byte through, as obtained from TG_GetNewConnectionId().
b	The byte to send through. Note that only the lowest 8-bits of the value will actually be sent through.

Returns: -1 if connectionId does not refer to a valid ThinkGear Connection ID handle.; -2 if connectionId is connected to an input file stream instead of an actual ThinkGear COM stream (i.e. nowhere to send the byte to).; -3 if an I/O error occurs attempting to send the byte (i.e. broken stream connection).; 0 on success.

THINKGEAR_API int TG_SetBaudrate	(	int	connectionId,
		int	serialBaudrate
	)

Attempts to change the baud rate of the ThinkGear Connection, given by connectionId, to serialBaudrate.

This function does not typically need to be called, except after calling TG_SendByte() to send a Command Byte that changes the ThinkGear module's baud rate. See TG_SendByte() for details and NOTE.

Parameters

connectionId	The ID of the ThinkGear Connection to send a byte through, as obtained from TG_GetNewConnectionId().
serialBaudrate	The baudrate to use to attempt to communicate on the serial communication port. Select from one of the TG_BAUD_* constants defined above, such as TG_BAUD_9600 or TG_BAUD_57600. TG_BAUD_57600 is the typical default baud rate for most ThinkGear models.

Returns: -1 if connectionId does not refer to a valid ThinkGear Connection ID handle.; -2 if serialBaudrate is not a valid TG_BAUD_* value.; -3 if an error occurs attempting to set the baud rate.; -4 if connectionId is connected to an input file stream instead of an actual ThinkGear COM stream.; 0 on success.

THINKGEAR_API int TG_SetDataFormat	(	int	connectionId,
		int	serialDataFormat
	)

Attempts to change the data Packet parsing format used by the ThinkGear Connection, given by connectionId, to serialDataFormat.

This function does not typically need to be called, and is provided only for special testing purposes.

Parameters

connectionId	The ID of the ThinkGear Connection to send a byte through, as obtained from TG_GetNewConnectionId().
serialDataFormat	The type of ThinkGear data stream. Select from one of the TG_STREAM_* constants defined above. Most applications should use TG_STREAM_PACKETS (the data format for Embedded ThinkGear modules). TG_STREAM_5VRAW is supported only for legacy non-embedded purposes.

Returns: -1 if connectionId does not refer to a valid ThinkGear Connection ID handle.; -2 if serialDataFormat is not a valid TG_STREAM_* type.; 0 on success.

THINKGEAR_API int TG_SetDataLog	(	int	connectionId,
		const char *	filename
	)

As a ThinkGear Connection reads and parses Packets of data from its serial stream, it may log the parsed data into a log file.

This is useful primarily for debugging purposes. Calling this function with a valid filename will turn this feature on. Calling this function with an invalid filename, or with filename set to NULL, will turn this feature off. This function may be called at any time for either purpose on a ThinkGear Connection.

Parameters

connectionId	The ID of the ThinkGear Connection to enable data logging for, as obtained from TG_GetNewConnectionId().
filename	The name of the file to use for data logging. Any existing contents of the file will be erased. Set to NULL or an empty string to disable stream logging by the ThinkGear Connection.

Returns: -1 if connectionId does not refer to a valid ThinkGear Connection ID handle.; -2 if filename could not be opened for writing. You may check errno for the reason.; 0 on success.

THINKGEAR_API int TG_SetStreamLog	(	int	connectionId,
		const char *	filename
	)

As a ThinkGear Connection reads bytes from its serial stream, it may automatically log those bytes into a log file.

This is useful primarily for debugging purposes. Calling this function with a valid filename will turn this feature on. Calling this function with an invalid filename, or with filename set to NULL, will turn this feature off. This function may be called at any time for either purpose on a ThinkGear Connection.

Parameters

connectionId	The ID of the ThinkGear Connection to enable stream logging for, as obtained from TG_GetNewConnectionId().
filename	The name of the file to use for stream logging. Any existing contents of the file will be erased. Set to NULL or an empty string to disable stream logging by the ThinkGear Connection.

Returns: -1 if connectionId does not refer to a valid ThinkGear Connection ID handle.; -2 if filename could not be opened for writing. You may check errno for the reason.; 0 on success.

THINKGEAR_API int TG_WriteDataLog	(	int	connectionId,
		int	insertTimestamp,
		const char *	msg
	)

THINKGEAR_API int TG_WriteStreamLog	(	int	connectionId,
		int	insertTimestamp,
		const char *	msg
	)

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation