Developer Tools 2.

1 Development Guide
June 21, 2010

e NeuroSky product families consist of hardware and software components for simple integration of this biosensor technology into consumer and industrial end-applications. All products are designed and manufactured to meet exacting consumer speci cations for quality, pricing, and feature sets. NeuroSky sets itself apart by providing buildingblock component solutions that oer friendly synergies with related and complementary technological solutions.

Reproduction in any manner whatsoever without the written permission of NeuroSky Inc. is strictly forbidden. Trademarks used in this text: eSense, inkGear, MDT, NeuroBoyand NeuroSkyare trademarks of NeuroSky Inc.

NO WARRANTIES: THE DOCUMENTATION PROVIDED IS "AS IS" WITHOUT ANY EXPRESS OR IMPLIED WARRANTY OF ANY KIND INCLUDING WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT OF INTELLECTUAL PROPERTY, INCLUDING PATENTS, COPYRIGHTS OR OTHERWISE, OR FITNESS FOR ANY PARTICULAR PURPOSE. IN NO EVENT SHALL NEUROSKY OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF PROFITS, BUSINESS INTERRUPTION, COST OF REPLACEMENT GOODS OR LOSS OF OR DAMAGE TO INFORMATION) ARISING OUT OF THE USE OF OR INABILITY TO USE THE DOCUMENTATION PROVIDED, EVEN IF NEUROSKY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. , SOME OF THE ABOVE LIMITATIONS MAY NOT APPLY TO YOU BECAUSE SOME JURISDICTIONS PROHIBIT THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES.

Contents
What's New Introduction About NeuroSky's inkGear inkGear Connector (TGC) inkGear Communications Driver (TGCD) Windows PC Development . . . . . . . . . Files . . . . . . . . . . . . . . . . . . . API Documentation . . . . . . . . . . Examples . . . . . . . . . . . . . . . . Execution . . . . . . . . . . . . . . . . Windows Mobile Development . . . . . . . Files . . . . . . . . . . . . . . . . . . . API Documentation . . . . . . . . . . Execution . . . . . . . . . . . . . . . . Mac OS X Development . . . . . . . . . . . API Documentation . . . . . . . . . . J2ME (Symbian) Mobile Development . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 5 6 7 8 8 8 8 9 9 9 9 10 10 10 11 11 12 12

inkGear Stream Parser Generic Development (All Other Platforms, Including Microprocessors) . . . . . . . . . .

3
June 21, 2010 | 2009-2010 NeuroSky, Inc. All Rights Reserved.

Chapter 1

What's New
Version 2.1 of the Developer Tools adds access to eye blink information. Using this information, applications can be made aware of when a user blinks and then respond accordingly. e software interface to access eye blink values is virtually identical to that used to access eSense values, so blink integration into an existing MindSet-capable application should be simple. Important: ough eye blink information is made available in the inkGear Connector, it is only available for applications using the JSON API applications using the Binary Socket Packet format will not have access to this blink information. is is part of an eventual deprecation of the Binary Socket Packet format.

4
June 21, 2010 | 2009-2010 NeuroSky, Inc. All Rights Reserved.

Chapter 2

Introduction
is development guide will direct you to the les and code samples you'll need to develop BCIenabled applications using the NeuroSky MindSet for any platform, from PCs to microprocessors. e MDT oers 4 levels of interfaces for communicating with MindSet headsets. From highest level to lowest level, they are: 1. the inkGear Connector (TGC) (Windows and Mac OS X executables) 2. the inkGear Communications Driver (TGCD) (Windows, Windows Mobile, Mac OS X, and J2ME (Symbian) libraries) 3. the inkGear Stream Parser (source code for any C platform) e two higher-level interfaces supply executables and binary libraries for some of the most common platforms, like Windows and Mac OS X, while the lowest-level Stream Parser interface provides source code and low level communication stream specs that allow MindSet development on virtually any platform that can receive a Bluetooth serial data stream. Please jump directly ahead to the appropriate chapter for the interface and platform you are interested in developing for, or read on to learn about all the interfaces.

5
June 21, 2010 | 2009-2010 NeuroSky, Inc. All Rights Reserved.

Chapter 3

About NeuroSky's ThinkGear

inkGear is the technology inside every NeuroSky product (including the MindSet) or partner product, that enables a device to interface with the wearer's brainwaves. It includes the sensor that touches the forehead, the contact and reference points located on the ear pad and the onboard chip that processes all of the data. Both the raw brainwaves and the eSense Meters (Attention and Meditation) are calculated on the inkGear chip. inkGear technology in the MindSet powers the development tools, drivers, and APIs provided in the MDT.

6
June 21, 2010 | 2009-2010 NeuroSky, Inc. All Rights Reserved.

Chapter 4

ThinkGear Connector (TGC)

e inkGear Connector (TGC) is an executable that provides a daemon-like service that manages communications with inkGear devices, such as the MindSet, that are connected to the computer. e TGC runs continuously in the background, and keeps an open socket on the local user's computer, allowing applications to connect to it and receive information from the connected inkGear devices. is means that any application in any language that can open and read from sockets (such as Flash's ActionScript3, and other scripting languages) can connect to and receive data from MindSet headsets. e TGC is provided as an executable for the following platforms: Windows Mac OS X For more information on the TGC, including how to run it, and how to write applications to communicate with it, please browse to the MDT's ThinkGear Connector/ directory, and read the inkgear Connector Development Guide.

7
June 21, 2010 | 2009-2010 NeuroSky, Inc. All Rights Reserved.

Chapter 5

ThinkGear Communications Driver (TGCD)

e inkGear Communications Driver (TGCD) is a device driver with a simple API that allows communication between an Application on a computer (or mobile device) and a inkGear chip/module/headset. It is available as a .dll (for x86 or ARMV4I platforms), as a .bundle (for Mac OS X platforms), or as a .java library (for J2ME/Symbian platforms).

Windows PC Development
e easiest way to begin Windows PC development is by using the provided inkGear Communications Driver (TGCD), for Win32 or Windows Mobile, and looking over the example program.

Files
Here are the development le(s) you'll need to add to your development environment/project. You only need to add le(s) for the language you intend to use:

Language C/C++ C# Java (via JNI)

Project File(s) (under ThinkGear Communications Driver/win32/) thinkgear.h and thinkgear.lib

ThinkGear.cs ThinkGear.java

API Documentation
Look for API documentation in the directories and les below:

Reference TGCD API (doxygen) TGCD API (javadoc)

Language C/C++ Java (via JNI)

File (under ThinkGear Driver/docs/)

html/index.html java/index.html

Communications

e primary documentation for the TGCD API's for the C# and Java(JNI) languages in the .cs and .java wrapper les respectively, and are almost identical to the C/C++ API from which they are derived, with only possibly some cosmetic naming changes. It is recommended that you refer directly to the contents of the .cs or .java les themselves for API documentation for those languages.

8
June 21, 2010 | 2009-2010 NeuroSky, Inc. All Rights Reserved.

Chapter 5 ThinkGear Communications Driver (TGCD)

Otherwise, you may refer to the doxygen-generated C/C++ html documentation mentioned in the table above. Important: In Windows, COM port names should have a \\.\ prepended to them. It is a required pre x for addressing serial ports above COM9, but is optional otherwise. Read this MSDN document for more details (particularly the section on "Win32 Device Namespaces").

Examples
Here is an example C program that uses the most important parts of the TGCD API, along with instructions for setting up and compiling the program in Visual Studio: Example/tutorial/guide Sample C/C++ App Visual Studio 2005 Guide File (under tgcd/win32/)
thinkgear_testapp.c README.txt

e function calls relating to the TGCD API in that example are almost identical to the function calls that would need to be made in C# or Java/JNI, so please use the C example as a guide towards building your rst MindSet application in those languages.

Execution
For all languages, once you have built an executable, you'll need to place the TGCD DLL (called thinkgear.dll) in the same directory as the executable (or in an appropriate place on your system PATH) in order to run the executable: Driver TGCD DLL File (under ThinkGear Communications Driver/win32/)
thinkgear.dll

Once you are comfortable with the API and the example program, you'll nd additional low level details, full descriptions of inkGear Data Types, Command Byte tables, and other advanced information in the Mindset Communications Protocol document (found in the MDT's ThinkGear/ directory).

Windows Mobile Development

Using the TGCD to interface with a MindSet on devices running Windows Mobile (WinMo) is virtually identical to Windows PC Development, except that you'll need to use a dierent set of les.

Files
Here are the development le(s) you'll need to add to your development environment/project. You only need to add le(s) for the language you intend to use:

Windows Mobile Development

June 21, 2010 | 2009-2010 NeuroSky, Inc. All Rights Reserved.

Chapter 5 ThinkGear Communications Driver (TGCD)

Language C/C++ C# Java (via JNI)

Project File(s) (under ThinkGear Communications Driver/winmobile/) thinkgear.h and thinkgear_ARMV4I.lib

ThinkGear_ARMV4I.cs

Not supported

API Documentation
e API for WinMo is the same as the one described in Windows PC Development. C#-speci c API is documented within the .cs wrapper le itself, and is almost identical to the C/C++ API, with only possibly some cosmetic naming changes. Please refer directly to the ThinkGear_ARMV4I.cs le for C# API documentation. Important: Serial COM ports on WinMo devices have a colon appended to their names, e.g. COM1:, COM2:, etc.. Also, please refer to Windows PC Development for code samples and starter projects that can be adapted to WinMo, as they are similar for WinMo (since the APIs are the same). WinMo-speci c examples and tutorials are not available at this time.

Execution
Once your program is compiled and deployed, you'll also need to use this DLL, compiled for mobile ARMV4I processors. Place it in the same directory as your deployed executable, or wherever else DLLs can be found by the WinMo system PATH:

Driver TGCD DLL

File (under ThinkGear Communications Driver/winmobile/)

thinkgear_ARMV4I.dll

Mac OS X Development
Here are the development le(s) you'll need to add to your development environment/project. You only need to add le(s) for the language you intend to use:

Language C/C++ C# Java (via JNI)

Project File(s) (under ThinkGear Communications Driver/macosx/)

ThinkGear.bundle

Not supported Not supported

Mac OS X Development
June 21, 2010 | 2009-2010 NeuroSky, Inc. All Rights Reserved.

10

Chapter 5 ThinkGear Communications Driver (TGCD)

API Documentation
e API for Mac OS X is the same as the one described in Windows PC Development. In addition, refer to the How To Use e inkGear API In Xcode (Mac OS X) document for additional information about using the API on Mac OS X (found in ThinkGear Communications Driver/macosx/). An example Cocoa/Carbon application using the TGCD API is described in the document inkGear API MacOSX Example (also found in ThinkGear Communications Driver/macosx/).

J2ME (Symbian) Mobile Development

Symbian devices supporting J2ME can use the Java libraries in the MDT's ThinkGear Communications Driver/j2me/ directory to develop applications: See ThinkGear Communications Driver/j2me/javadoc/index.html for documentation.

J2ME (Symbian) Mobile Development

June 21, 2010 | 2009-2010 NeuroSky, Inc. All Rights Reserved.

11

Chapter 6

ThinkGear Stream Parser

Generic Development (All Other Platforms, Including Microprocessors)
For all other platforms not covered by the TGC nor TGCD, it is up to the application to open the serial I/O communication channel (COM port or direct serial UART). Please refer to the platform's documentation for "serial I/O" or "UART" on how to open and read from such a channel, as serial I/O APIs tend to be platform-speci c. Once the communication channel is open and bytes can be read, we provide a Packet parsing library for parsing and decoding the incoming data bytes. e library is in the form of ANSI C source code (for compatibility even with most microprocessors), and can easily be ported to other languages as necessary: (You'll nd these les in the MDT's ThinkGear/ directory) ThinkGearStreamParser.h ThinkGearStreamParser.c Refer to the Mindset Communications Protocol (also found in the MDT's ThinkGear/ directory) for low-level specs, instructions, and sample code.

12
June 21, 2010 | 2009-2010 NeuroSky, Inc. All Rights Reserved.