Differences
This shows you the differences between two versions of the page.
| Previous revision | |||
| — | hinkgear.net_sdk_dev_guide_and_api_reference [2026/08/13 08:17] (current) – external edit 127.0.0.1 | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| + | <texit info> | ||
| + | author=NeuroSky, | ||
| + | title=NeuroSky SDK for .NET: Development Guide and API Reference | ||
| + | </ | ||
| + | ## NeuroSky SDK for .NET: Development Guide and API Reference ## | ||
| + | |||
| + | ====== Introduction ====== | ||
| + | |||
| + | This guide will teach you how to use the **NeuroSky SDK for .NET** to write Windows apps that can utilize bio-signal data from NeuroSky' | ||
| + | |||
| + | This guide (and the entire **NeuroSky SDK for .NET** for that matter) is intended for programmers who are already familiar with standard .NET development using Microsoft Visual Studio. | ||
| + | |||
| + | If you are already familiar with creating typical .NET apps, then the next step is to make sure you have downloaded the **NeuroSky SDK for .NET**. | ||
| + | |||
| + | < | ||
| + | Need to add SDK download URL once we figure out where our .NET SDK is published publicly. | ||
| + | |||
| + | Currently available from: [[engineering: | ||
| + | |||
| + | Note that we currently have a link on http:// | ||
| + | </ | ||
| + | |||
| + | ===== NeuroSky SDK for .NET Contents ===== | ||
| + | * **NeuroSky SDK for .NET: Development Guide and API Reference** (this document) | ||
| + | * libs/: | ||
| + | * **ThinkGear.dll** library | ||
| + | * **JayrockJson.dll** supporting library | ||
| + | * **NLog.dll** supporting library | ||
| + | * **NLog.xml** and **NLog.config** configuration files | ||
| + | * **NLog.LICENSE.txt** and **Jayrock.LICENCE.txt** licence files | ||
| + | * **TG-HelloEEG.exe** - a reference build of the HelloEEG sample project | ||
| + | * **HelloEEG Sample Project** source code | ||
| + | |||
| + | You'll find the .dll, configuration files and 3rd party license documents in the '' | ||
| + | |||
| + | You'll find the source code of the " | ||
| + | ===== Supported NeuroSky Hardware ===== | ||
| + | |||
| + | The NeuroSky SDK for .NET can only be used with the following NeuroSky devices, chips, and modules: | ||
| + | |||
| + | * MindWave Mobile | ||
| + | * MindWave (RF) | ||
| + | * MindBand | ||
| + | * MindSet | ||
| + | * ThinkCap | ||
| + | |||
| + | |||
| + | * TGAM module | ||
| + | * TGAT ASIC | ||
| + | |||
| + | |||
| + | < | ||
| + | |||
| + | ====== Your First Project: HelloEEG console ====== | ||
| + | |||
| + | HelloEEG is a sample project we've included in the **NeuroSky SDK for .NET** that demonstrates how to setup, connect, and handle data to a NeuroSky device. Add the project to your Visual Studio by following these steps: | ||
| + | |||
| + | - from the Visual Studio Toolbar, select **File** --> **New** --> **Project From Existing Code...** | ||
| + | - In the New Project From Existing Code wizard, select the project type of " | ||
| + | - click the "Next >" button | ||
| + | - browse to the place you have expanded the SDK files. (" | ||
| + | - check the box to include subfolders. | ||
| + | - enter a name of " | ||
| + | - choose Output type of " | ||
| + | - click the " | ||
| + | - at the Toolbar select **Project** --> **HelloEEG Properties...** | ||
| + | - change the Assembly name to HelloEEG | ||
| + | - set the Target framework to ".NET Framework 3.5" | ||
| + | - if you are asked to Confirm the Framework change, click " | ||
| + | - at the Toolbar select **View** --> **Solution Explorer** | ||
| + | - in the Solution Explorer pane select and expand the " | ||
| + | - if you see a exclamation mark warning on " | ||
| + | - select it and right click, and remove the reference to " | ||
| + | - select the " | ||
| + | - choose the browse TAB, choose the folder " | ||
| + | - at the Toolbar select **Build** --> **Build Solution** | ||
| + | - if there are no errors, you should be able to browse the code, make modifications, | ||
| + | |||
| + | < | ||
| + | < | ||
| + | |||
| + | ====== Developing Your Own NeuroSky Sensor Apps for .NET ====== | ||
| + | |||
| + | ===== Preparing Your .NET Project ===== | ||
| + | |||
| + | The **NeuroSky SDK for .NET**' | ||
| + | |||
| + | ===== The ThinkGear.dll ====== | ||
| + | |||
| + | To start with, add the **ThinkGear.dll** file to your .NET application' | ||
| + | |||
| + | ===== The NeuroSky.ThinkGear Namespace ===== | ||
| + | |||
| + | The **NeuroSky SDK for .NET**' | ||
| + | |||
| + | <code csharp> | ||
| + | using NeuroSky.ThinkGear; | ||
| + | </ | ||
| + | |||
| + | ===== Using the NeuroSky.ThinkGear Namespace ===== | ||
| + | |||
| + | < | ||
| + | |||
| + | The '' | ||
| + | * '' | ||
| + | * '' | ||
| + | |||
| + | To use the classes, first declare a '' | ||
| + | |||
| + | <code csharp> | ||
| + | private Connector connector; | ||
| + | connector = new Connector(); | ||
| + | </ | ||
| + | |||
| + | < | ||
| + | |||
| + | Next, create '' | ||
| + | |||
| + | <code csharp> | ||
| + | connector.DeviceConnected | ||
| + | connector.DeviceFound | ||
| + | connector.DeviceNotFound | ||
| + | connector.DeviceConnectFail | ||
| + | connector.DeviceDisconnected += new EventHandler( OnDeviceDisconnected ); | ||
| + | connector.DeviceValidating | ||
| + | </ | ||
| + | |||
| + | In the handler for the '' | ||
| + | |||
| + | <code csharp> | ||
| + | void OnDeviceConnected( object sender, EventArgs e ) { | ||
| + | |||
| + | Connector.DeviceEventArgs deviceEventArgs = (Connector.DeviceEventArgs)e; | ||
| + | Console.WriteLine( "New Headset Created." | ||
| + | | ||
| + | deviceEventArgs.Device.DataReceived += new EventHandler( OnDataReceived ); | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Now, whenever data is received from the device, the '' | ||
| + | |||
| + | <code csharp> | ||
| + | void OnDataReceived( object sender, EventArgs e ){ | ||
| + | |||
| + | /* Cast the event sender as a Device object, and e as the Device' | ||
| + | Device d = (Device)sender; | ||
| + | Device.DataEventArgs de = (Device.DataEventArgs)e; | ||
| + | |||
| + | /* Create a TGParser to parse the Device' | ||
| + | TGParser tgParser = new TGParser(); | ||
| + | tgParser.Read( de.DataRowArray ); | ||
| + | | ||
| + | /* Loop through parsed data TGParser for its parsed data... */ | ||
| + | for( int i=0; i< | ||
| + | |||
| + | // See the Data Types documentation for valid keys such | ||
| + | // as " | ||
| + | | ||
| + | if( tgParser.ParsedData[i].ContainsKey(" | ||
| + | Console.WriteLine( "Raw Value:" | ||
| + | } | ||
| + | | ||
| + | if( tgParser.ParsedData[i].ContainsKey(" | ||
| + | Console.WriteLine( "PQ Value:" | ||
| + | } | ||
| + | | ||
| + | if( tgParser.ParsedData[i].ContainsKey(" | ||
| + | Console.WriteLine( "Att Value:" | ||
| + | } | ||
| + | |||
| + | if( tgParser.ParsedData[i].ContainsKey(" | ||
| + | Console.WriteLine( "Med Value:" | ||
| + | } | ||
| + | | ||
| + | | ||
| + | } | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | When you would like to begin the Familiarity and/or Mental Effort ((you may see older documents refer to this as "Task Difficulty", | ||
| + | <code csharp> | ||
| + | connector.setTaskFamiliarityEnable(true); | ||
| + | connector.setMentalEffortEnable(true); | ||
| + | </ | ||
| + | |||
| + | Once you have the handlers set up as described above, you can have your '' | ||
| + | |||
| + | Before exiting, your application **must** close the '' | ||
| + | |||
| + | <code csharp> | ||
| + | connector.close(); | ||
| + | </ | ||
| + | |||
| + | If '' | ||
| + | |||
| + | ===== Events ===== | ||
| + | If you choose to connect by stating a specific COM port, it will take the following steps: | ||
| + | - connector.Connect(portName); | ||
| + | - connector.Connect in turn validates the COM port. So the DeviceValidating event is triggered | ||
| + | - if the COM port was valid, it connects to the device. The DeviceFound event is never triggered | ||
| + | - if the COM port was invalid, the DeviceNotFound event is triggered. | ||
| + | |||
| + | If you choose to connect by using the AUTO approach, it will take the following steps: | ||
| + | - connector.Find(); | ||
| + | - if it is able to find a COM port with valid ThinkGear Packets, it triggers DeviceFound. Otherwise, the DeviceNotFound event is triggered | ||
| + | - the OnDeviceFound method in turn calls connector.Connect(tempPortName); | ||
| + | - if the COM port was valid, it connects to the device. | ||
| + | - if the COM port was invalid, the DeviceNotFound event is triggered. | ||
| + | |||
| + | ==== Tips on using ThinkGear.NET ==== | ||
| + | * In order to connect quickly, your application should always remember across sessions the last COM '' | ||
| + | * If an unexpected disconnection occurs, your application should try to reconnect automatically and prompt the user to check their headset device for the following: | ||
| + | * Battery is properly inserted into the headset device, and has sufficient charge (or try a new battery) | ||
| + | * Headset device is turned on | ||
| + | * Headset device is properly paired in Bluetooth settings | ||
| + | * Headset device is within range of the Bluetooth receiver (within 10m unobstructed) | ||
| + | |||
| + | ====== API Reference ====== | ||
| + | ===== Connector class ===== | ||
| + | |||
| + | ==== Methods ==== | ||
| + | |||
| + | === Connect to a device === | ||
| + | |||
| + | == void Connect(string portName) == | ||
| + | Attempts to open a connection with the port name specified by '' | ||
| + | * DeviceConnected - A connection was successfully opened on portName | ||
| + | * DeviceConnectFail - The connection attempt was unsuccessful | ||
| + | |||
| + | == void ConnectScan() == | ||
| + | Attempts to open a connection to the first Device seen by the Connector. Calling this method results in one of two events being broadcasted: | ||
| + | * DeviceConnected - A connection was successfully opened on portName | ||
| + | * DeviceConnectFail - The connection attempt was unsuccessful | ||
| + | |||
| + | == void ConnectScan(string portName) == | ||
| + | Same as ConnectScan but scans the port specified by portName first. Calling this method results in one of two events being broadcasted: | ||
| + | * DeviceConnected - A connection was successfully opened on portName | ||
| + | * DeviceConnectFail - The connection attempt was unsuccessful | ||
| + | |||
| + | === Disconnect from a device === | ||
| + | |||
| + | == void Disconnect() == | ||
| + | Closes all open connections. Calling this method will result in the following event being broadcasted for each open device: | ||
| + | * DeviceDisconnected - The device was disconnected | ||
| + | |||
| + | == void Disconnect(Connection connection) == | ||
| + | Closes a specific Connection specified by '' | ||
| + | * DeviceDisconnected - The device was disconnected | ||
| + | |||
| + | == void Disconnect(Device device) == | ||
| + | Closes a specific Device specified by '' | ||
| + | * DeviceDisconnected - The device was disconnected | ||
| + | |||
| + | |||
| + | === Send bytes to a device === | ||
| + | |||
| + | == void Send(string portName, byte[] bytesToSend) == | ||
| + | Sends an array of bytes to a specific port | ||
| + | |||
| + | === Configure Familiarity/ | ||
| + | |||
| + | == void enableMentalEffort() DEPRECATED == | ||
| + | Starts recording data for 60 seconds. Once the recording is complete, the Mental Effort will be calculated. Note: the first time the Mental Effort ((older documents refer to "Task Difficulty", | ||
| + | |||
| + | == void enableFamiliarity() DEPRECATED == | ||
| + | Starts recording data for 60 seconds. Once the recording is complete, the Familiarity will be calculated. Note: the first time the Familiarity is calculated, the result is 0. | ||
| + | |||
| + | ==== Events | ||
| + | |||
| + | == DeviceFound == | ||
| + | Occurs when a ThinkGear device is found. This is where the application chooses to connect to that port or not. | ||
| + | |||
| + | == DeviceNotFound == | ||
| + | | ||
| + | |||
| + | == DeviceValidating == | ||
| + | Occurs right before the connector attempts a serial port. Mainly used to notify the GUI which port it is trying to connect. | ||
| + | |||
| + | == DeviceConnected == | ||
| + | Occurs when a ThinkGear device is connected. This is where the application links the OnDataReceived for that device. | ||
| + | |||
| + | == DeviceConnectFail == | ||
| + | Occurs when the Connector fails to connect to that port specified. | ||
| + | |||
| + | == DeviceDisconnected == | ||
| + | Occurs when the Connector disconnects from a ThinkGear device. | ||
| + | |||
| + | == DataReceived == | ||
| + | Occurs when data is available from a ThinkGear device. | ||
| + | |||
| + | ===== TGParser Class ===== | ||
| + | |||
| + | < | ||
| + | Is there a missing '' | ||
| + | </ | ||
| + | |||
| + | The TGParser class is used to convert the received data into easily accessible data contained in a Dictionary. | ||
| + | |||
| + | ==== Methods | ||
| + | |||
| + | == Dictionary< | ||
| + | Parses the raw headset data in '' | ||
| + | |||
| + | When connected to a MindSet, MindWave, or MindWave Mobile headset, the '' | ||
| + | |||
| + | ^ Key ^ Description ^ Data Type ^ | ||
| + | | Time | TimeStamps of packet received | double | | ||
| + | | Raw | Raw EEG data | short | | ||
| + | | EegPowerDelta | Delta Power| uint | | ||
| + | | EegPowerTheta | Theta Power | uint | | ||
| + | | EegPowerAlpha1 | Low Alpha Power | uint | | ||
| + | | EegPowerAlpha2 | High Alpha Power | uint | | ||
| + | | EegPowerBeta1 | Low Beta Power |uint| | ||
| + | | EegPowerBeta2 | High Beta Power |uint| | ||
| + | | EegPowerGamma1 | Low Gamma Power |uint| | ||
| + | | EegPowerGamma2 | High Gamma Power |uint| | ||
| + | | Attention | Attention eSense | double | | ||
| + | | Meditation | Meditation eSense | double | | ||
| + | | Zone | performance Zone | double | | ||
| + | | PoorSignal | Poor Signal | double | | ||
| + | | BlinkStrength | Strength of detected blink. The Blink Strength ranges from 1 (small blink) to 255 (large blink). Unless a blink occurred, nothing will be returned. Blinks are only calculated if PoorSignal is less than 51. | uint | | ||
| + | | Familiarity (BETA) | Familiarity measures how well the subject is learning a new task or how well his performance is with certain task. Familiarity algorithm can be used for both within-trial monitoring (continuous real-time tracking) and between-trial comparison. A trial can be of any length equal to or more than 1 minute. | ||
| + | | Mental Effort (BETA) | Mental Effort measures how hard the subject’s brain is working, i.e. the amount of workload involved in the task. Mental Effort algorithm can be used for both within-trial monitoring (continuous real-time tracking) and between-trial comparison. A trial can be of any length equal to or more than 1 minute. | ||
| + | < | ||
| + | | MindWandering | Mind Wandering Level. The Mind Wandering Level ranges from 1 (low Mind Wandering) to 10 (high Mind Wandering). The Mind Wandering algorithm updates once every 0.5 seconds, assuming PoorSignal is less than 51. If PoorSignal is above 51, nothing is returned. | double | | ||
| + | </ | ||
| + | |||
| + | |||
| + | |||
| + | When connected to a ThinkCap, the '' | ||
| + | ^ Key ^ Description ^ Data Type ^ | ||
| + | | Time | TimeStamps of packet received | double | | ||
| + | | RawCh1 | EEG Channel 1 | short | | ||
| + | | RawCh2 | EEG Channel 2 | short | | ||
| + | | RawCh3 | EEG Channel 3 | short | | ||
| + | | RawCh4 | EEG Channel 4 | short | | ||
| + | | RawCh5 | EEG Channel 5 | short | | ||
| + | | RawCh6 | EEG Channel 6 | short | | ||
| + | | RawCh7 | EEG Channel 7 | short | | ||
| + | | RawCh8 | EEG Channel 8 | short | | ||
| + | |||
| + | |||
| + | |||
| + | ====== ThinkGear Data Types ====== | ||
| + | The ThinkGear data types are generally divided into two groups: data types that are only applicable for EEG sensor devices, and data types that are typically applicable to all ThinkGear-based devices. | ||
| + | |||
| + | ===== General ===== | ||
| + | These data types are generally available from most or all types of ThinkGear hardware devices. | ||
| + | |||
| + | ==== POOR_SIGNAL/ | ||
| + | |||
| + | This integer value provides an indication of how good or how poor the bio-signal is at the sensor. | ||
| + | |||
| + | This is an extremely important value for any app using ThinkGear sensor hardware to always read, understand, and handle. | ||
| + | < | ||
| + | This updated version converts poorSignal values read from different hardware devices. It converts them into a uniform format. (unlike earlier version of the SDK) | ||
| + | If you have software that reacts to the poorSignal value, you should evaluate that software to see if changes need to be made | ||
| + | </ | ||
| + | < | ||
| + | **In order to interpret this value you must first decide which type of NeuroSky sensor you are using. As the interpretation is different for the different types of sensors.** | ||
| + | |||
| + | **For EEG sensor hardware:** | ||
| + | A value of 0 indicates that the bio-sensor is not able to detect any obvious problems with the signal at the sensor. | ||
| + | |||
| + | **For ECG/EKG (CardioChip) sensor hardware:** | ||
| + | A value of 200 indicates the bio-sensor contacts are all currently in contact with a conductive subject (such as a user's skin), while a value of 0 indicates the opposite: that not all the contacts are in proper contact with a conductive subject. | ||
| + | |||
| + | </ | ||
| + | **Poor signal may be caused by a number of different things.** | ||
| + | severity, they are: | ||
| + | |||
| + | * Sensor, ground, or reference electrodes not being on a person' | ||
| + | * Poor contact of the sensor, ground, or reference electrodes to a person' | ||
| + | * Excessive motion of the wearer (i.e. moving head or body excessively, | ||
| + | * Excessive environmental electrostatic noise (some environments have strong electric signals or static electricity buildup in the person wearing the sensor). | ||
| + | * Excessive biometric noise | ||
| + | |||
| + | For EEG modules, a certain amount of noise is unavoidable in normal usage of ThinkGear sensor hardware, and both NeuroSky' | ||
| + | been designed to detect, correct, compensate for, account for, and tolerate | ||
| + | many types of signal noise. | ||
| + | in using the eSense(tm) values, such as Attention and Meditation, do not need | ||
| + | to worry as much about the '' | ||
| + | the Attention and Meditation values will not be updated while '' | ||
| + | is greater than zero, and that the headset is not being worn while '' | ||
| + | applications which need to be more sensitive to noise (such as some medical | ||
| + | or research applications), | ||
| + | when there is even minor noise detected. | ||
| + | |||
| + | < | ||
| + | Kelvin, I have made some adjustments, | ||
| + | they just need to know how to interpret it for their product. | ||
| + | I suppose we could add a way for the developer to pass in the sensor type. | ||
| + | Dave | ||
| + | |||
| + | I have keep most of your thoughts below for the background material. | ||
| + | |||
| + | **Thanks for making the adjustments, | ||
| + | |||
| + | I've been preparing to formally tackle this problem for years, by defining an ID that the hardware can send out to identify itself, and by pushing the hardware guys to clearly define the output characteristics of the hardware in their specs, but it requires the hardware guys to actually implement it in their hardware and specs. | ||
| + | --- // | ||
| + | |||
| + | ---- | ||
| + | |||
| + | This name is in transition. | ||
| + | |||
| + | That's all historical now. We've agreed that going forward, using the term SENSOR_STATUS is better for all involved (since many developers had a slightly difficult time wrapping their head around the concept of " | ||
| + | |||
| + | The other point is that the mechanism for detecting 200 is entirely different, it is a special value that is looking for an impedance level so high that suggests an open circuit. | ||
| + | |||
| + | The final thing to be careful of is the " | ||
| + | |||
| + | --- // | ||
| + | |||
| + | </ | ||
| + | |||
| + | |||
| + | ==== RAW_DATA ==== | ||
| + | |||
| + | This data type supplies the raw sample values acquired at the bio-sensor. | ||
| + | |||
| + | As an example, the majority of ThinkGear devices sample at 512Hz, with a possible value range of -32768 to 32767. | ||
| + | |||
| + | As another example, to convert TGAT-based EEG sensor values (such as TGAT, TGAM, MindWave Mobile, MindWave, MindSet) to voltage values, use the following conversion: | ||
| + | < | ||
| + | (rawValue * (1.8/4096)) / 2000 | ||
| + | </ | ||
| + | |||
| + | ==== RAW_MULTI ==== | ||
| + | |||
| + | //This data type is not currently used by any current commercially-available ThinkGear products. | ||
| + | |||
| + | ===== EEG ===== | ||
| + | These data types are only available from EEG sensor hardware devices, such as the MindWave Mobile, MindSet, MindBand, and TGAM chips and modules. | ||
| + | |||
| + | ==== ATTENTION ==== | ||
| + | |||
| + | This int value reports the current eSense(tm) Attention meter of | ||
| + | the user, which indicates the intensity of a user's level of mental " | ||
| + | or " | ||
| + | directed (but stable) mental activity. | ||
| + | Distractions, | ||
| + | Attention meter levels. | ||
| + | interpreting eSense(tm) levels in general. | ||
| + | |||
| + | By default, output of this Data Value is enabled. | ||
| + | once a second. | ||
| + | |||
| + | ==== MEDITATION ==== | ||
| + | |||
| + | This unsigned one-byte value reports the current eSense(tm) Meditation meter of | ||
| + | the user, which indicates the level of a user's mental " | ||
| + | " | ||
| + | measure of a person' | ||
| + | relaxing all the muscles of the body may not immediately result in a | ||
| + | heightened Meditation level. | ||
| + | circumstances, | ||
| + | Meditation is related to reduced activity by the active mental processes in | ||
| + | the brain, and it has long been an observed effect that closing one's eyes | ||
| + | turns off the mental activities which process images from the eyes, so | ||
| + | closing the eyes is often an effective method for increasing the Meditation | ||
| + | meter level. | ||
| + | sensory stimuli may lower the Meditation meter levels. | ||
| + | below for details about interpreting eSense(tm) levels in general. | ||
| + | |||
| + | By default, output of this Data Value is enabled. | ||
| + | once a second. | ||
| + | |||
| + | === eSense Meters === | ||
| + | |||
| + | For all the different types of eSense(tm) (i.e. Attention, Meditation), | ||
| + | meter value is reported on a relative eSense(tm) scale of 1 to 100. On this | ||
| + | scale, a value between 40 to 60 at any given moment in time is considered | ||
| + | " | ||
| + | conventional EEG measurement techniques (though the method for determining a | ||
| + | ThinkGear baseline is proprietary and may differ from conventional EEG). A | ||
| + | value from 60 to 80 is considered " | ||
| + | as levels being possibly higher than normal (levels of Attention or Meditation | ||
| + | that may be higher than normal for a given person). | ||
| + | considered " | ||
| + | levels of that eSense(tm). | ||
| + | |||
| + | Similarly, on the other end of the scale, a value between 20 to 40 indicates | ||
| + | " | ||
| + | " | ||
| + | of distraction, | ||
| + | each eSense(tm). | ||
| + | |||
| + | ==== ZONE ==== | ||
| + | |||
| + | This value reports the current performance Zone of | ||
| + | the subject. | ||
| + | transitions from one Zone to another. | ||
| + | |||
| + | This algorithm uses the Attention and Mediation values to guide a subject to their best performance. | ||
| + | |||
| + | To be in the Elite Zone (9), the subject must hold their Attention level a value of at least 94 and simultaneously holding their Meditation level steady or increasing. | ||
| + | |||
| + | To be in the Intermediate Zone (5), the subject must hold their Attention level a value of at least 64 and simultaneously holding their Meditation level steady or increasing. | ||
| + | |||
| + | To be in the Beginner Zone (1), the subject must hold their Attention level a value of at least 28 and simultaneously holding their Meditation level steady or increasing. | ||
| + | |||
| + | The Not Ready Zone (0) is all Attention levels below 28 and subjects from the Beginner Zone whose Meditation levels are decreasing. | ||
| + | |||
| + | All Zone calculations are suspended and values reset if the sensor doesn' | ||
| + | |||
| + | < | ||
| + | This is a different implementation of performance Zone compared to other NeuroSky products. | ||
| + | Reference: Golf Putting Training Algorithm v 2.0, September 2012, Dr. KooHyoung Lee. | ||
| + | </ | ||
| + | |||
| + | |||
| + | ==== BLINK ==== | ||
| + | |||
| + | This int value reports the intensity of the user's most recent eye blink. Its value ranges from 1 to 255 and it is reported whenever an eye blink is detected. The value indicates the relative intensity of the blink, and has no units. | ||
| + | |||
| + | The Detection of Blinks must be enabled. | ||
| + | |||
| + | <code java> | ||
| + | if (setBlinkDetectionEnabled(true)) { | ||
| + | // return true, means success | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not supported because: | ||
| + | // | ||
| + | // | ||
| + | // | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | The current configuration can be retrieved. | ||
| + | <code java> | ||
| + | if (getBlinkDetectionEnabled()) { | ||
| + | // return true, means it is enabled | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not currently configured | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | < | ||
| + | If these methods are called before the '' | ||
| + | '' | ||
| + | </ | ||
| + | |||
| + | ==== EEG_POWER ==== | ||
| + | |||
| + | This Data Value represents the current magnitude of 8 commonly-recognized types of EEG frequency bands. | ||
| + | |||
| + | The eight EEG powers are: delta (0.5 - 2.75Hz), | ||
| + | theta (3.5 - 6.75Hz), low-alpha (7.5 - 9.25Hz), high-alpha (10 - 11.75Hz), | ||
| + | low-beta (13 - 16.75Hz), high-beta (18 - 29.75Hz), low-gamma (31 - 39.75Hz), | ||
| + | and mid-gamma (41 - 49.75Hz). | ||
| + | |||
| + | By default, output of this Data Value is enabled, and it is output approximately once a second. | ||
| + | < | ||
| + | It isn't valid to compare the values from sample to sample. I think the intention is to describe a comparison of the different frequency band values within a particular sample. That there is an automatic scaling that happens in the hardware when values get large. All of the band values within a particular sample will be scaled the same way. But since there is no indication that the scaling has been done it isn't valid to compare frequency band values across different samples. These should be though of as unsigned 24 bit numbers. (that is: values in range of 0 to 0x00ffffff) dlordemann 27-nov-2012 | ||
| + | </ | ||
| + | |||
| + | ==== THINKCAP_RAW ==== | ||
| + | |||
| + | //This data type is not currently used by any current commercially-available ThinkGear products. | ||
| + | |||
| + | ==== POSITIVITY ==== | ||
| + | |||
| + | Values -100 to +100, indicates that the subject is attentive, the more negative values mean the subject is less attentive and the more positive values mean more attentive. | ||
| + | |||
| + | < | ||
| + | This feature is not currently available. | ||
| + | </ | ||
| + | < | ||
| + | The Calculation of Positivity must be enabled. And once enabled it will run continuously until disabled. | ||
| + | < | ||
| + | Positivity can not be used concurrently with Familiarity or Mental Effort. | ||
| + | </ | ||
| + | <code java> | ||
| + | if (setPositivityEnable(true)) { | ||
| + | // return true, means success | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not supported because: | ||
| + | // | ||
| + | // | ||
| + | // | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | The current configuration can be retrieved. | ||
| + | <code java> | ||
| + | if (getPositivityEnable()) { | ||
| + | // return true, means it is enabled | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not currently configured | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | < | ||
| + | If these methods are called before the '' | ||
| + | '' | ||
| + | </ | ||
| + | |||
| + | < | ||
| + | This algorithm is resource and computation intensive. If you need to run with the Debugger, be aware that this calculation may take many minutes to complete when the debugger is engaged. It will complete and present it's results. Without the debugger engaged, this calculation should complete in a few seconds. | ||
| + | </ | ||
| + | </ | ||
| + | |||
| + | ==== FAMILIARITY (BETA) ==== | ||
| + | |||
| + | When applied to single-channel EEG data collected from the forehead area, the Familiarity algorithm measures how well a subject is learning a task, and correlates with how well his performance is with certain tasks. The Familiarity algorithm works well with both motor (e.g. drawing) and mental (e.g. reciting) tasks. The algorithm can be used for monitoring a subject' | ||
| + | |||
| + | The Familiarity algorithm must be applied to at least 1 minute of EEG data. A Familiarity Index will be output by the algorithm after the first 60s, and then every N seconds after that (N is the predefined output rate; default: 10s). | ||
| + | |||
| + | A typical way to use the Familiarity algorithm is for an application to prompt a subject to be relaxing, with their eyes open, doing nothing, for the first 60s while taking the initial measurement. | ||
| + | |||
| + | Alternatively, | ||
| + | |||
| + | For presenting, studying, and interpreting the data, each reported Familiarity Index (FI) value can be compared for percent changes either (1) against the baseline value, or (2) against the FI value immediately preceding it. | ||
| + | |||
| + | The Familiarity Index is a floating point number with arbitrary units. | ||
| + | |||
| + | An example on how to use the algorithm could be found in the sample application – “HelloEEG”. | ||
| + | |||
| + | A few example tasks that the algorithm can to: painting (" | ||
| + | |||
| + | < | ||
| + | A common baseline method is under investigation to enhance the usability of the algorithm. With this method, a 60s baseline is needed only in the first time you use the algorithm. The EEG data during this 60s baseline recording should be stored, and be used to fill up the analysis window buffer (i.e. to be the first 60s input data) when you use the algorithm the second time. New baseline data could be recorded again anytime if you find there' | ||
| + | </ | ||
| + | |||
| + | To use the Familiarity algorithm in the NeuroSky SDK/API library, it must first be enabled: | ||
| + | |||
| + | <code java> | ||
| + | if (setTaskFamiliarityEnable(true)) { | ||
| + | // return true, means success | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not supported because: | ||
| + | // | ||
| + | // | ||
| + | // | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | At any time, the status of the algorithm (whether it is enabled) can be queried: | ||
| + | <code java> | ||
| + | if (getTaskFamiliarityEnable()) { | ||
| + | // return true, means it is enabled | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not currently configured | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | Using just '' | ||
| + | |||
| + | It is possible to configure the algorithm to run continuously: | ||
| + | |||
| + | <code java> | ||
| + | if (setTaskFamiliarityRunContinuous(true)) { | ||
| + | // return true, means success | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not supported because: | ||
| + | // | ||
| + | // | ||
| + | // | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | < | ||
| + | Enabling Continuous Mode does not automatically also enable the algorithm itself; you must still call '' | ||
| + | </ | ||
| + | |||
| + | The current Continuous Mode configuration can be retrieved: | ||
| + | <code java> | ||
| + | if (getTaskFamiliarityRunContinuous()) { | ||
| + | // return true, means it is enabled | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not currently configured | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | < | ||
| + | If these methods are called before the '' | ||
| + | '' | ||
| + | </ | ||
| + | |||
| + | < | ||
| + | This algorithm is resource and computation intensive. If you need to run with the Debugger, be aware that this calculation may take many minutes to complete when the debugger is engaged. It will output its results only after its calculations are complete. | ||
| + | </ | ||
| + | ==== MENTAL EFFORT (BETA) ==== | ||
| + | |||
| + | When applied to single-channel EEG data collected from forehead area, the Mental Effort algorithm measures the amount of workload exerted by subject' | ||
| + | |||
| + | The Mental Effort algorithm must be applied to at least 1 minute of EEG data. A Mental Effort Index will be output by the algorithm after the first 60s, and then every N seconds after that (N is the predefined output rate; default: 10s). | ||
| + | |||
| + | A typical way to use the Mental Effort algorithm is for an application to prompt a subject to be relaxing, with their eyes open, doing nothing, for the first 60s while taking the initial measurement. | ||
| + | |||
| + | Alternatively, | ||
| + | |||
| + | For presenting, studying, and interpreting the data, each reported Mental Effort Index (MEI) value can be compared for percent changes either (1) against the baseline value, or (2) against the MEI value immediately preceding it. | ||
| + | |||
| + | The Mental Effort Index is a floating point number with arbitrary units. | ||
| + | |||
| + | An example on how to use the algorithm could be found in the sample application – “HelloEEG”. | ||
| + | |||
| + | A few example tasks that the algorithm can to: arithmetic calculation ("Math 24" available in http:// | ||
| + | |||
| + | < | ||
| + | A common baseline method is under investigation to enhance the usability of the algorithm. With this method, a 60s baseline is needed only in the first time you use the algorithm. The EEG data during this 60s baseline recording should be stored, and be used to fill up the analysis window buffer (i.e. to be the first 60s input data) when you use the algorithm the second time. New baseline data could be recorded again anytime if you find there' | ||
| + | </ | ||
| + | |||
| + | To use the Mental Effort algorithm ((older documents may refer to the " | ||
| + | |||
| + | <code java> | ||
| + | if (setMentalEffortEnable(true)) { | ||
| + | // return true, means success | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not supported because: | ||
| + | // | ||
| + | // | ||
| + | // | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | At any time, the status of the algorithm (whether it is enabled) can be queried: | ||
| + | <code java> | ||
| + | if (getMentalEffortEnable()) { | ||
| + | // return true, means it is enabled | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not currently configured | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | Using just '' | ||
| + | |||
| + | It is possible to configure the algorithm to run continuously: | ||
| + | |||
| + | <code java> | ||
| + | if (setMentalEffortRunContinuous(true)) { | ||
| + | // return true, means success | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not supported because: | ||
| + | // | ||
| + | // | ||
| + | // | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | |||
| + | < | ||
| + | Enabling Continuous Mode does not automatically also enable the algorithm itself; you must still call '' | ||
| + | </ | ||
| + | |||
| + | The current Continuous Mode configuration can be retrieved. | ||
| + | <code java> | ||
| + | if (getMentalEffortRunContinuous()) { | ||
| + | // return true, means it is enabled | ||
| + | |||
| + | | ||
| + | } | ||
| + | else { | ||
| + | // return false, meaning not currently configured | ||
| + | |||
| + | | ||
| + | } | ||
| + | </ | ||
| + | < | ||
| + | If these methods are called before the '' | ||
| + | '' | ||
| + | </ | ||
| + | |||
| + | < | ||
| + | This algorithm is resource and computation intensive. If you need to run with the Debugger, be aware that this calculation may take many minutes to complete when the debugger is engaged. It will output its results only after its calculations are complete. | ||
| + | </ | ||
| + | |||
| + | ====== Proper App Design ====== | ||
| + | < | ||
| + | |||
| + | * If your app's Handler receives a '' | ||
| + | * If a '' | ||
| + | * If a '' | ||
| + | * If a '' | ||
| + | * See [[#TGDevice States]] for more info. | ||
| + | |||
| + | * Always make sure your app is handling the [[#POOR SIGNAL/ | ||
| + | |||
| + | * To make the user experience consistent, familiar, and easy-to-learn and use for end customers across platforms and devices, your app should be designed to follow the guidelines and conventions described in NeuroSky' | ||
| + | |||
| + | ====== Troubleshooting ====== | ||
| + | < | ||
| + | |||
| + | If you need further help, you may visit http:// | ||
| + | is any new information. | ||
| + | |||
| + | To contact NeuroSky for support, please visit http:// | ||
| + | send email to [email protected]. | ||
| + | |||
| + | For developer community support, please visit our community forum on | ||
| + | http:// | ||
| + | |||
| + | ====== Important Notices ====== | ||
| + | |||
| + | The algorithms included in this SDK are solely for promoting the awareness of personal wellness and health and are not a substitute for medical care. The algorithms are not to be used to diagnose, treat, cure or prevent any disease, to prescribe any medication, or to be a substitute for a medical device or treatment. In some circumstances, | ||
| + | |||
| + | The algorithms may not function well or may display accurate data if the user has a pacemaker. | ||
| + | |||
| + | |||
| + | === Warnings and Disclaimer of Liability === | ||
| + | |||
| + | THE ALGORITHMS MUST NOT BE USED FOR ANY ILLEGAL USE, OR AS COMPONENTS IN LIFE SUPPORT OR SAFETY DEVICES OR SYSTEMS, OR MILITARY OR NUCLEAR APPLICATIONS, | ||
| + | YOUR USE OF THE SOFTWARE DEVELOPMENT KIT, THE ALGORITHMS AND ANY OTHER NEUROSKY PRODUCTS OR SERVICES IS “AS-IS, | ||
| + | |||
| + | IN NO EVENT SHALL NEUROSKY BE LIABLE FOR ANY SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES, INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS OR INCOME, WHETHER OR NOT NEUROSKY HAD KNOWLEDGE, THAT SUCH DAMAGES MIGHT BE INCURRED. | ||
| + | |||
| + | |||
| + | |||
| + | |||
| + | < | ||
| + | ====== APPENDIX C: Enabling the use of Personalization ====== | ||
| + | |||
| + | Your code to initialize the '' | ||
| + | It must also enable writing to the Android file system. SEE [[#APPENDIX D]]. | ||
| + | <code java> | ||
| + | public void onCreate(Bundle savedInstanceState) { | ||
| + | //... | ||
| + | btAdapter = BluetoothAdapter.getDefaultAdapter(); | ||
| + | if( btAdapter != null ) { | ||
| + | TGDevice.ekgPersonalizationEnabled = true; | ||
| + | |||
| + | tgDevice = new TGDevice( btAdapter, handler ); | ||
| + | } | ||
| + | //... | ||
| + | } | ||
| + | </ | ||
| + | </ | ||
| + | < | ||
| + | ====== NLog.dll License Terms ====== | ||
| + | |||
| + | Copyright (c) 2004-2011 Jaroslaw Kowalski < | ||
| + | |||
| + | All rights reserved. | ||
| + | |||
| + | Redistribution and use in source and binary forms, with or without | ||
| + | modification, | ||
| + | are met: | ||
| + | |||
| + | * Redistributions of source code must retain the above copyright notice, | ||
| + | this list of conditions and the following disclaimer. | ||
| + | |||
| + | * Redistributions in binary form must reproduce the above copyright notice, | ||
| + | this list of conditions and the following disclaimer in the documentation | ||
| + | and/or other materials provided with the distribution. | ||
| + | |||
| + | * Neither the name of Jaroslaw Kowalski nor the names of its | ||
| + | contributors may be used to endorse or promote products derived from this | ||
| + | software without specific prior written permission. | ||
| + | |||
| + | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | ||
| + | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | ||
| + | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | ||
| + | ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE | ||
| + | LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | ||
| + | CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | ||
| + | SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | ||
| + | INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | ||
| + | CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | ||
| + | ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF | ||
| + | THE POSSIBILITY OF SUCH DAMAGE. | ||
| + | |||
| + | ====== JayrockJson.dll License Terms ====== | ||
| + | |||
| + | LGPL 3: http:// | ||
| + | </ | ||