XNeuroSDK 1.0.6.25

Overview

Neurosdk is a powerful tool for working with neuro-sensors BrainBit, BrainBitBlack, Callibri and Kolibri. All these devices work with BLE 4.2+ technology. Xamarin SDK is designed for Android and iOS platforms. SDK allows you to connect, read the parameters of devices, as well as receive signals of various types from the selected device.

Getting Started

Android:

Because sdk uses the bluetooth api you need to set up the project.

For Android you need to add permissions to use geolocation and bluetooth to the manifest. You can read more about this on AndroidDeveloper.

<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" />
<uses-permission android:name="android.permission.BLUETOOTH_ADMIN" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" tools:targetApi="31" android:usesPermissionFlags="neverForLocation" />

Permissions to location and bluetooth requests as:

        private void requestPermissions()
        {
            bool permissionsGranted = Build.VERSION.SdkInt >= BuildVersionCodes.S ?
                (ContextCompat.CheckSelfPermission(Android.App.Application.Context, Manifest.Permission.BluetoothScan) == (int)Permission.Granted &&
                 ContextCompat.CheckSelfPermission(Android.App.Application.Context, Manifest.Permission.BluetoothConnect) == (int)Permission.Granted) :
                (ContextCompat.CheckSelfPermission(Android.App.Application.Context, Manifest.Permission.Bluetooth) == (int)Permission.Granted &&
                 ContextCompat.CheckSelfPermission(Android.App.Application.Context, Manifest.Permission.AccessFineLocation) == (int)Permission.Granted &&
                 ContextCompat.CheckSelfPermission(Android.App.Application.Context, Manifest.Permission.AccessCoarseLocation) == (int)Permission.Granted);

            if (permissionsGranted)
            {
                ...
            }
            else
            {
                String[] permissions = Build.VERSION.SdkInt >= BuildVersionCodes.S ?
                    new String[] { Manifest.Permission.BluetoothScan, Manifest.Permission.BluetoothConnect } :
                    new String[] { Manifest.Permission.Bluetooth, Manifest.Permission.AccessFineLocation, Manifest.Permission.AccessCoarseLocation };
                ActivityCompat.RequestPermissions((Activity)MainActivity.ActivityContext, permissions, REQUEST_PERMISSIONS);
            }
        }

Then, in MainActivity.cs add NeuroSDK.NeuroSDKSetup.Initialize() before LoadApplication :

   protected override void OnCreate(Bundle savedInstanceState)
        {
            base.OnCreate(savedInstanceState);
			...
            NeuroSDK.NeuroSDKSetup.Initialize();

            LoadApplication(new App());
        }

iOS

For iOS you need to add a key to Info.plist:

<key>NSBluetoothAlwaysUsageDescription</key>
<string>Explanation to using bluetooth</string>

UWP

You need to open package manifest and add enable capability "Bluetooth".

Another way is add this capability manually:

1. Go into UWP project folder
2. Open Package.appxmanifest file
3. Into Capabilities section add: <DeviceCapability Name="bluetooth"/>

Windows DotNet

You don't need to configure anything.

Usage

Scanner

The scanner works like this:

1. Create scanner. When creating a scanner, you need to specify the type of device to search. It can be either one device or several. Here is example for two type of devices - BrainBit and Callibri.

Scanner scanner = new Scanner(SensorFamily.SensorLECallibri, SensorFamily.SensorLEBrainBit);

2. During the search, you can get a list of found devices using a callback. To do this, you need to subscribe to receive the event, and unsubscribe after the search is completed:

private void Scanner_Founded(IScanner scanner, IReadOnlyList<SensorInfo> sensors)
{
    foreach(SensorInfo sensorInfo in sensors){
        Console.WriteLine(sensorInfo.Name + ": " + sensorInfo.Address);
    }
}

scanner.EventSensorsChanged += Scanner_Founded;
...
scanner.EventSensorsChanged -= Scanner_Founded;

3. Start and stop search

scanner.Start();
...
scanner.Stop();

4. Additionally, a list of found devices can be obtained using a separate method.

IReadOnlyList<SensorInfo> sensors = scanner.Sensors;

SensorInfo contains information about device:

5. After you finish working with the scanner, you need to clean up the resources used.

scanner.Dispose();

Sensor

You need to create a device using a scanner. All manipulations with the device will be performed without errors only if the device is connected.

// BrainBit
BrainBitSensor sensor = scanner.CreateSensor(sensorInfo) as BrainBitSensor;

// Callibri
CallibriSensor sensor = scanner.CreateSensor(sensorInfo) as CallibriSensor;

Device creation is a blocking method, so it must be called from separate thread.

Manage connection state

Connection status can be obtained in two ways. The first one is using the sensor property State.

The second way is in real time using a callback:

 private void EventSensorStateChanged(ISensor sensor, SensorState sensorState)
{
    Console.WriteLine(sensorState);
}
...
sensor.EventSensorStateChanged += EventSensorStateChanged;
...
sensor.EventSensorStateChanged -= EventSensorStateChanged;

A connection can be in two states: connected (InRange) and disconnected (OutOfRange).

Important! The state change callback will not come after the device is created, only after disconnecting (device lost from the scope or using a method) and then connected. The device does not automatically reconnect.

You can connect and disconnect from device manually by methods Connect() and Disconnect(). To receive connection state in real time you need to subscribe to stateChanged event. Also you can get connection state by sensor's property.

sensor.Disconnect();
...
sensor.Connect();

Battery

Also, you can get power value from each device by sensor property BattPower or by callback in real time:

private void EventBatteryChanged(ISensor sensor, int battPower)
{
    Console.WriteLine("Power: " + battPower);
}
...
sensor.EventBatteryChanged += EventBatteryChanged;
...
sensor.EventBatteryChanged -= EventBatteryChanged;

Parameters

Each device has its own settings, and some of them can be configured as you need. Not all settings can be changed and not every device supports all settings.

Firstly you need to find out what parameters the device supports and whether they can be changed:

var parameters = sensor.Parameters;

Info about parameter includes two fields:

• the name of the parameter, represented by an enumeration
• parameter availability for manipulation. Can be one of three values:
  • read - read-only
  • read and write - parameter can be changed
  • read and notify - parameter is updated over time

You can also check if the parameter is supported, for example Gain:

if(sensor.IsSupportedParameter(SensorParameter.ParameterGain)){
...
}

Each device has a specific set of modules. You can find out which modules the device has using the property Feature:

var features = sensor.Features;

You can also check if the feature is supported, for example Signal:

if(sensor.IsSupportedFeature(SensorFeature.FeatureSignal)){
...
}

The device can execute certain commands. The list of supported commands can be obtained as follows:

var commands = sensor.Commands;

And also check if the device can execute the desired command:

if(sensor.IsSupportedCommand(SensorCommand.StartSignal)){
...
}

BrainBit, BrainBitBlack

The BrainBit and BrainBitBlack is a headband with 4 electrodes and 4 data channels - O1, O2, T3, T4. The device has a frequency of 250 Hz, which means that data on each of the channels will come at a frequency of 250 samples per second. The parameters of this device, such as gain, data offset and the other, cannot be changed, if you try to do this, an exception will appear.

sensor.Gain = SensorGain.SensorGain1; // <- This throw an exeption!

You can distinguish BrainBit device from Flex by the firmware version number: if the SensorVersion.FwMajor is more than 100 - it's Flex, if it's less than BrainBit.

BrainBitBlack, unlike BrainBit, requires pairing with a PC/mobile device. So, before connecting to the BBB, you must put it into pairing mode. SDK starts the pairing process automatically.

To use the BrainBit features, you need to bring the sensor type to a BrainBit or BrainBitBlack device type. The sensor as such does not provide signal or resistance values.

BrainBitSensor sensor = scanner.CreateSensor(info) as BrainBitSensor;
// or
BrainBitBlackSensor sensor = scanner.CreateSensor(info) as BrainBitBlackSensor;
// or
var sensor = = scanner.CreateSensor(info);
// or
Sensor sensor = scanner.CreateSensor(info);
BrainBitSensor BBsensor = sensor as BrainBitSensor;

Receiving signal

To receive signal data, you need to subscribe to the corresponding callback. The values will be received as a packet from four channels at once, which will avoid desynchronization between them. The values come in volts. In order for the device to start transmitting data, you need to start a signal using the execute command. This method is also recommended to be run in an separate thread.

private void onBrainBitSignalDataRecived(ISensor sensor, BrainBitSignalData[] data)
{
    Console.WriteLine("Data: " + data);
}
...
sensor.EventBrainBitSignalDataRecived += onBrainBitSignalDataRecived;
sensor.ExecCommand(SensorCommand.CommandStartSignal);
...
sensor.EventBrainBitSignalDataRecived -= onBrainBitSignalDataRecived;
sensor.ExecCommand(SensorCommand.CommandStopSignal);

Recieving resistance

BrainBit and BrainBitBlack also allow you to get resistance values. With their help, you can determine the quality of the electrodes to the skin.

private void onBrainBitResistDataRecived(ISensor sensor, BrainBitResistData data)
{
    Console.WriteLine("Data: " + data);
}
...
sensor.EventBrainBitResistDataRecived += onBrainBitResistDataRecived;
sensor.ExecCommand(SensorCommand.CommandStartResist);
...
sensor.EventBrainBitResistDataRecived -= onBrainBitResistDataRecived;
sensor.ExecCommand(SensorCommand.CommandStopResist);

Callibri MF, Kolibri

The Callibri family of devices has a wide range of built-in modules. For each of these modules, the SDK contains its own processing area. It is recommended before using any of the modules to check if the module is supported by the device using one of the methods IsSupportedFeature, IsSupportedCommand or IsSupportedParameter

To use the Callibri features, you need to bring the sensor type to a Callibri device type. The sensor as such does not provide signal or electrodes state values.

CallibriSensor sensor = scanner.CreateSensor(info) as CallibriSensor;
// or
var sensor = = scanner.CreateSensor(info);
// or
Sensor sensor = scanner.CreateSensor(info);
CallibriSensor sensor = sensor as CallibriSensor;

Receiving signal

To receive signal data, you need to subscribe to the corresponding callback. The values come in volts. In order for the device to start transmitting data, you need to start a signal using the execute command. This method is also recommended to be run in an separate thread.

private void onCallibriSignalDataRecived(ISensor sensor, CallibriSignalData[] data)
{
    Console.WriteLine("Data: " + data);
}
...
sensor.EventCallibriSignalDataRecived += onCallibriSignalDataRecived;
sensor.ExecCommand(SensorCommand.CommandStartSignal);
...
sensor.EventCallibriSignalDataRecived -= onCallibriSignalDataRecived;
sensor.ExecCommand(SensorCommand.CommandStopSignal);

The sampling rate can be controlled using the SamplingFrequency property. For example, at a frequency of 1000 Hz, the device will send 1000 samples per second. Supports frequencies 125/250/500/1000/2000/4000 Hz. You can also adjust the signal offset (DataOffset) and signal power (Gain).

sensor.Gain = SensorGain.SensorGain6;
sensor.DataOffset = SensorDataOffset.DataOffset3;
sensor.SamplingFrequency = SamplingFrequency.FrequencyHz1000;

Check electrodes state

Allows you to determine the presence of electrical contact of the device electrodes with human skin. It can be in three states:

• Normal - The electrodes have normal skin contact. Low electrical resistance between electrodes. The expected state when working with physiological signals.
• Detached - High electrical resistance between electrodes. High probability of interference in the physiological signal.
• HighResistance - There is no electrical contact between the electrodes of the device.

To receive data, you need to subscribe to the corresponding callback and start signal pickup.

private void onCallibriElectrodeStateChanged(ISensor sensor, CallibriElectrodeState elState)
{
    Console.WriteLine(elState);
}
...
sensor.EventCallibriElectrodeStateChanged += onCallibriElectrodeStateChanged;
sensor.ExecCommand(SensorCommand.CommandStartSignal);
...
sensor.EventCallibriElectrodeStateChanged -= onCallibriElectrodeStateChanged;
sensor.ExecCommand(SensorCommand.CommandStopSignal);

Receiving envelope

To get the values of the envelope, you need to subscribe to a specific event and start pickup. The channel must be configured in the same way as for a normal signal, and all parameters work the same way. Then the signal is filtered and decimated at 20 Hz.

private void onCallibriEnvelopeDataRecived(ISensor sensor, CallibriEnvelopeData[] data)
{
    Console.WriteLine("Data: " + data);
}
...
sensor.CallibriEnvelopeDataRecived += onCallibriEnvelopeDataRecived;
sensor.ExecCommand(SensorCommand.CommandStartEnvelope);
...
sensor.CallibriEnvelopeDataRecived -= onCallibriEnvelopeDataRecived;
sensor.ExecCommand(SensorCommand.CommandStopEnvelope);

MEMS

The MEMS microcircuit is optional on request. Its presence can be checked using the IsSupportedFeature method. This means that the device contains an accelerometer and a gyroscope. Contains information about the position of the device in space. Channel sampling frequency is 100 Hz.

MEMS data is a structure:

• PackNum - number for each packet
• Accelerometer - accelerometer data. Contains:
  • X - Abscissa Acceleration
  • Y - Y-axis acceleration
  • Z - Acceleration along the applicate axis
• Gyroscope - gyroscope data
  • X - The angle of inclination along the abscissa axis
  • Y - Inclination angle along the ordinate axis
  • Z - Angle of inclination along the axis of the applicate

Quaternion data is a structure:

• PackNum - number for each packet
• W - Rotation component
• X - Vector abscissa coordinate
• Y - Vector coordinate along the ordinate axis
• Z - The coordinate of the vector along the axis of the applicate

It is recommended to perform calibration on a flat, horizontal non-vibrating surface before starting work using the CalibrateMEMS command. Calibration state can be checked using the MEMSCalibrateStateCallibri property, it can take only two values: calibrated (true), not calibrated (false).

MEMS and quaternion available only to signal Callibri/Kolibri!

private void Sensor_EventQuaternionDataRecived(ISensor sensor, QuaternionData[] data)
{
    Console.WriteLine(data.ToString());
}

private void Sensor_EventMEMSDataRecived(ISensor sensor, MEMSData[] data)
{
    Console.WriteLine(data.ToString());
}
...
// Calibration
sensor.ExecCommand(SensorCommand.CommandCalibrateMEMS);
bool isCalibrated = sensor.MEMSCalibrateStateCallibri;

// For receiving MEMS
sensor.EventMEMSDataRecived += Sensor_EventMEMSDataRecived;
sensor.ExecCommand(SensorCommand.CommandStartMEMS);
...
sensor.EventMEMSDataRecived -= Sensor_EventMEMSDataRecived;
sensor.ExecCommand(SensorCommand.CommandStopMEMS);

// For quaternion
sensor.EventQuaternionDataRecived += Sensor_EventQuaternionDataRecived; 
sensor.ExecCommand(SensorCommand.CommandStartAngle);
...
sensor.EventQuaternionDataRecived -= Sensor_EventQuaternionDataRecived; 
sensor.ExecCommand(SensorCommand.CommandStopAngle);

Motion counter

Represents a motion counter. It can be configured using the CallibriMotionCounterParam property, in it:

• InsensThreshmG – Threshold of the algorithm's deadness in amplitude (in mg). The maximum value is 500mg. The minimum value is 0.
• InsensThreshSamp - Threshold of the algorithm's insensitivity in time (in samples with the MEMS sampling rate). The maximum value is 500 samples. The minimum value is 0.

You can find out the current number of movements using the MotionCounterCallibri property. You can reset the counter with the ResetMotionCounter command. No additional commands are needed to start the counter, it will be incremented all the time until the reset command is executed.

if(sensor.IsSupportedParameter(SensorParameter.ParameterMotionCounter))
{
    sensor.MotionCounterParamCallibri = new CallibriMotionCounterParam() { 
                    InsenseThresholdMG = 250,
                    InsenseThresholdSample = 250
                    };
    int motionCount = sensor.MotionCounterCallibri;
    sensor.ExecCommand(SensorCommand.CommandResetMotionCounter);
}