Firmware versions

From Capsule version 1.2.0 and newer we recommend using two firmware versions:

4.8.4 (for use with signal and resistance mesarument mode)
4 6 3 (latest supported version without signal and resistance mesarument mode support)

Warning: If you want to work with signal and resistance measurement mode, please update your devices to version 4.8.4. This mode is not fully supported on earlier versions, due changes in resist mesarument machanics.

Capsule is intended for working with devices based on physiological signals measurement and classification.

Basic paradigms are: EEG (NFB), PPG (Cardio), Movement data (gyroscope and accelerometer)

For using Capsule to build one's own application the dynamic libraries (.dll / .dylib) are included with a header files for Windows and MacOS operatings systems. Aso Apple Flamework included for iOS operating system and Shared Library for Android operating system.

Package contains example projects:

main.cpp - for "ready to use" EEG and PPG metrics
FilteredSignalExample.cpp - for RAW signal with applied verified digital filters
RawSignalExample.cpp - for RAW signal directlry from device

A GUI version of Capsule for Windows and MacOS operating systems is also included in this package.

Following OS versions are supported:

Microsoft Windows 10 20H2 - 11
Apple MacOS 12.6 - 14.5
Apple iOS 13 - 17.4.1
Google Android - 10 - 14

Basically, each Capsule API session with a device must include 6 stages:

Capsule abtract

C API parameter	Parameter description	Type	Value from	Value to
IndividualFrequency	IAF	float	7	13
IndividualPeakFrequency	IAPF	float	7	13
IndividualPeakFrequencyPower	iapf power	float	0	infinity (excluding)
IndividualPeakFrequencySuppression	iapf suppression	float	0	infinity (excluding)
IndividualBandwidth	individual alpha range width	float	0	6
IndividualNormalizedPower	normalized alpha range power	float	0	1
LowerFrequency	alpha range lower bound	float	7	13
UpperFrequency	alpha range upper bound	float	7	13
Heart Rate	heart rate (beats per minute/pulse)	float	0	180
Stress Index (Baevskiy)	Stress Index (Baevskiy)	float	0	infinity (excluding)
SAT Index (Kaplan)	SAT Index (Kaplan)	float	0	infinity (excluding)
GravityBaseline	GravityBaseline	float	0	infinity (excluding)
ProductivityBaseline	ProductivityBaseline	float	0	infinity (excluding)
FatigueBaseline	FatigueBaseline	float	0	infinity (excluding)
ReverseFatigueBaseline	ReverseFatigueBaseline	float	0	infinity (excluding)
RelaxBaseline	RelaxBaseline	float	0	infinity (excluding)
ConcentrationBaseline	ConcentrationBaseline	float	0	infinity (excluding)
FatigueScore	FatigueScore	float	0	infinity (excluding)
GravityScore	GravityScore	float	0	infinity (excluding)
ConcentrationScore	ConcentrationScore	float	0	infinity (excluding)
RelaxationScore	RelaxationScore	float	0	infinity (excluding)
AccumulatedFatigue	AccumulatedFatigue	float	0	10
FatigueGrowth	FatigueGrowth	int	0	3
AlphaRangeBegin	alpha range start	float	7	13
AlphaRangeEnd	alpha range end	float	7	13
RelaxPoint	RelaxPoint	int	0	5
StressPoint	StressPoint	int	0	2
RelaxBaseline	RelaxBaseline	float	0	infinity (excluding)
FatigueBaseline	FatigueBaseline	float	0	infinity (excluding)
GravityBaseline	GravityBaseline	float	0	infinity (excluding)
ConcentrationBaseline	ConcentrationBaseline	float	0	infinity (excluding)
IsArtifacted	EEG artifacts	bool	TRUE	FALSE
Focus	focus scale	float	0	100
Chill	chill scale	float	0	100
Stress	stress scale	float	0	100
Anger	anger scale	float	0	100
SelfControl	self-control scale	float	0	100
Relaxation	Physiological States Value	float	0	1
Fatigue	Physiological States Value	float	0	1
Concentraition	Physiological States Value	float	0	1
Involvement	Physiological States Value	float	0	1
Stress	Physiological States Value	float	0	1
None	Physiological States Value	float	0	1
nfbArtifacts	Physiological States Value	bool	TRUE	FALSE
cardioArtifacts	Physiological States Value	bool	TRUE	FALSE

1 Create Client

Create client

Methods:

Warning: By default Capsule creates data foldier with name "Capsule Data" at user application data directory. Choose clCClient_CreateWithName or clCClient_Create methods.

If you want to create data folier at other directory use methods clCClient_CreateWithDataDirectory and clCClient_CreateWithDataDirectoryAndName. Sometimes system wide administrator privileges may be required.

Get device events:

Initialize client events handlers:

2 Locate and connect to a device via BLE protocol

Device connection flow

2.1 Device connection:

Methods:

Get device events:

Initialize device events handlers:

2.2 Choose device mode

PPG and MEMS usage

Warning: If you need to use MEMS and PPG sensors you should start them separately prior creating a session via clCDeviceMode.

2.2.1 Regular device settings

The device can operate in two modes:

signal mesarument or resistance measurement (Signal / Resistance)
combined signal mesarument and resistance mesarument (Signal + Resistance)

Signal / Resistance

To switch to resistance mode use clCDevice_SwitchMode(clCDevice, clC_DM_Resistance) Make sure the electrode quality is satisfactory before switching to signal mode.

To switch to signal mode use clCDevice_SwitchMode(clCDevice, clC_DM_Signal).

Signal + Resistance

Use clCDevice_SwitchMode(clCDevice, clC_DM_SignalAndResist) to work with signal+resistance mode.

Warning: Initialize the calibrator and classifier after the resistance values are below 1000 kOhm. Otherwise, you will not be able to complete the calibration, due poor signal quality.

Impedance measurement

Methods:

clCResistances_GetCount - the number of channels
clCResistances_GetChannelName - the name of a channel
clCResistances_GetValue - the resistance of a channel

Get device's resistances events:

clCDevice_GetOnResistancesEvent

Initialize device's resistances events handlers:

clCDeviceDelegateResistances_Set

The resistance value for each channel, in order to receive a good signal, is recommended to be lowered according to the following estimate:

Above 1000 kOhm - bad quality
500 to 1000 kOhm - average quality
Below 500 kOhm - good quality

Switch device to signal mode

Methods:

Get channel info:

You can use these methods any time after creating the device.

Get device mode events:

clCDevice_GetOnModeSwitchedEvent

Initialize device mode events handlers:

clCDeviceDelegateMode_Set

In signal mode received EEG data already free of miographic artefacts. If artefacts detected invalid value, are not sent via API.

2.2.2 Work with Cardio metrics (available on PRO devices)

Methods:

Get cardio events:

clCCardio_GetOnIndexesUpdateEvent - Heart Rate, Stress Index (Baevskiy) and SAT Index (Kaplan)
clCCardio_GetOnCalibratedEvent

Initialize cardio events handlers:

2.2.3 Work with accelerometer and gyroscope readings (available on PRO devices)

The classifier unites accelerometer and gyroscope integrated in Neiry Headband Pro and is called clCMEMS (MEMS - micro electro mechanical system) for brevity.

Methods:

Get MEMS events:

MEMS event contains multiple sensor readings coupled with timepoints

clCMEMS_GetOnMEMSTimedDataUpdateEvent

Get accelerometer and gyroscope readings from MEMS event:

clCMEMSTimedData_GetCount - the number of readings
clCMEMSTimedData_GetAccelerometer - accelerometer orientation
clCMEMSTimedData_GetGyroscope - gyroscope orientation
clCMEMSTimedData_GetTimepoint - timepoint of a reading

Initialize MEMS events handlers:

clCMEMSDelegateMEMSTimedDataUpdate_Set

3 License verification

Licence required to work with "ready to use" metrics, based at physyological signals. Such as NFB, Productivity, Emotions, Cardio, States classification results. Filtered EEG signal also require licence.

RAW signal from device does not require licence, and can be used to build own classification.

First licence key verification require internet connection.

Licence key can be obtained from your device seller manager.

Before creating session license key must be verified, otherwise futher API methods won't work. License verification is performed via clCLicenseManager class which can be obtained via clCClient_GetLicenseManager method. To request license verification you need to pass license key and connected device instance from clCDevice to the clCLicenseManager_VerifyLicense method. When the license is verified, the handler obtained with clCLicenseManager_GetOnLicenseVerifiedEvent is called. This handler has a bool parameter which represents a success flag (true if license verified successfully, otherwise false).

Methods:

Get license manager's event:

clCLicenseManager_GetOnLicenseVerifiedEvent

Initialize license manager events' handlers:

clCLicenseManagerDelegateLicenseVerified_Set

Capsule flow license

4 Create session

This stage allows to create "session". After creation session's RAW data can be written in Capsule folder (HDF5 format), and further classification of physiological signals can be produced.

We recommend create only one session during working with device.

Warning: Do not create more than one session to avoid errors.

Methods:

Get session events:

Initialize session events handlers:

Session flow

5 Calibration

You can call clCNFBCalibrator_GetOnIndividualNFBCalibratedEvent before initialization brain rhythms if you don't need to send callibration results to your server.

Methods:

To get [IndividualFrequency, IndividualPeakFrequency, IndividualPeakFrequencyPower, IndividualPeakFrequencySuppression, IndividualBandwidth, IndividualNormalizedPower, LowerFrequency, UpperFrequency] a callback is used with a pointer to clCIndividualNFBData, which is set via clCNFBCalibratorDelegateIndividualNFBCalibrated_Set

Get calibration stage events:

If calibration fails, clCNFBCalibrator_GetOnIndividualNFBCalibratedEvent returns a fail reason.

FailReason values (if the calibration process failed you will receive the following responses):

0 - Calibration succeeded
1 - Too many artifacts
2 - Individual alpha peak frequency matches one of the alpha range borders

Initialize calibration stage events:

clCNFBCalibratorDelegateIndividualNFBCalibrationStage_Set
clCNFBCalibratorDelegateIndividualNFBCalibrated_Set
Differences between IAPF calibration methods

Method clCNFBCalibrator_CalibrateIndividualNFB requires 4 stages to train model:

Closed eyes - 20 sec
Open eyes - 20 sec
Closed eyes - 20 sec
Open eyes - 20 sec

Method clCNFBCalibrator_CalibrateIndividualNFBQuick will require 1 stage to train model:

Closed eyes - 30 sec

When [LowerFrequency, UpperFrequency, IndividualPeakFrequencySuppression] values are not needed, clCNFBCalibrator_CalibrateIndividualNFBQuick calibration method should be used, due to its short duration and easier process.

Calibration flow

6 Classifiers (nfb, emotions, productivity metrics, states)

Warning: We recommend initializing classifiers after receiving a callback from clCNFBCalibrator_GetOnIndividualNFBCalibratedEvent, where clCIndividualNFBCalibrationFailReason equal clC_IndividualNFBCalibrationFailReason_None

Classifiers flow

6.1. clCNFB

Methods:

To get [FeedbackData (Alpha, Beta, Theta), FeedbackSize, Timestamp] a callback is used with a pointer to clCNFBUserState, which is set via clCNFBDelegateNFBUserState_Set

Get NFB events:

Initialize NFB events:

You can receive values of the following main brain rhythms without calibration (model training): Theta (4-7 Hz), Alpha (7-13 Hz), Beta (15-30 Hz). All values are sent in mV^2.

6.2 Productivity metrics

To get [GravityBaseline, ProductivityBaseline, FatigueBaseline, ReverseFatigueBaseline, RelaxBaseline, ConcentrationBaseline] a callback is used with a pointer to clCNFBMetricsProductivityBaselines, which is set via clCNFBMetricsProductivity_InitialBaselineCalibratedEvent_Set

To get [FatigueScore, GravityScore, ConcentrationScore, RelaxationScore, AccumulatedFatigue, FatigueGrowth] a callback is used with a pointer to clCNFBMetricsProductivityValues, which is set via clCNFBMetricsProductivity_ValuesEvent_Set

To reset accumulated fatigue and start its calculation from zero method clCNFBMetricsProductivity_ResetAccumulatedFatigue is used.

Warning: If you have PRO device with PPG, use improved classifier Physiological States (section 5.4) to get a more accurate and advanced states detection.

To get [IAF, IAPF, IAPFPowerNormalized, AlphaRangeBegin, AlphaRangeEnd, RelaxPoint, StressPoint, RelaxBaseline, FatigueBaseline, GravityBaseline, ConcentrationBaseline, IsArtifacted] a callback is used with a pointer to clCNFBMetricsProductivityIndividualIndexes, which is set via clCNFBMetricsProductivity_IndividualMeasuredEvent_Set

RelaxPoint values:

0 - no condition
1 - involvement
2 - relaxation
3 - slight fatigue
4 - severe fatigue
5 - chronic fatigue

StressPoint values:

0 - no condition
1 - anxiety
2 - stress

If physiological state is not detected value "no condition" will be received.

For physiological states like Fatigue or Stress values can be received every 2.5 min (if miographics artifacts are not detected)

To get [ProductivityScore] a callback is used with a pointer to clCNFBMetricsProductivityIndividualIndexes, which is set via clCNFBMetricsProductivity_UpdateEvent_Set, to get a delegate, you can use for example clCNFBMetricsProductivity_GetOnUpdateEvent_1min or clCNFBMetricsProductivity_GetOnUpdateEvent_5min, clCNFBMetricsProductivity_GetOnUpdateEvent_15min, clCNFBMetricsProductivity_GetOnUpdateEvent_30min, clCNFBMetricsProductivity_GetOnUpdateEvent_60min

IAPF and IAF values can be received once per calibration.

For indexes like Fatigue Score or Concentration Index values can be received every 0.1 sec.

Cognitive (Productivity) Score can be received every 0.1 sec. For momentum values clCNFBMetricsProductivity_GetOnUpdateEvent_1min should be used.

For physiological states like Fatigue or Stress values can be received every 2.5 min (if miographics artifacts are not detected).

Methods:

Get productivity events:

Initialize productivity events:

6.3 Emotions

Methods:

To get [Focus, Chill, Stress, Anger, SelfControl] a callback is used with a pointer to clCEmotionalStates, which is set via clCEmotionsDelegateEmotionalStatesUpdate_Set

Get emotions events:

Initialize emotions events handlers:

For emotional states values can be received every 0.1 sec.

Full list of available methods can be found further in this documentation (File->File Members->Functions).

6.4 Physiological states

Physiological states

To get [relaxation, fatigue, none, concentration, involvement, stress, nfbArtifacts, cardioArtifacts] a callback is used with a pointer to clCPhysiologicalStatesValue, which is set via clCPhysiologicalStatesDelegatePhysiologicalStatesUpdate_Set.

To get baselines of [alpha, beta, alphaGravity, betaGravity, concentration] a callback is used with a pointer to clCPhysiologicalStatesBaselines, which is set via clCPhysiologicalStatesOnCalibratedEvent_Set. This callback is called after calibration and only once.

By default physiological state values are sent every 2 minute.

Warning: You can get Stress Index и SAT points before calibration. But values are correct only after Cardio calibration event. You need to subsctibe to the end event calibration, use clCCardio_GetOnCalibratedEvent to get correct values.

Methods:

Get physiological states events:

Initialize physiological states events:

7 RAW and RAW filtered signal

If you don't need to use metrics, you can work with raw signal.

To work with raw signal directly from device (EEG bandwidth from 1 to 120 hertz): you should subscribe to the event receiving a raw signal after device connection.
To work with a raw filtered signal directly from device with verified digital filters (effective EEG mesarument bandwidth set from 4 to 35 hertz): you should connect to device, select EEG signal mode, create a session with monopolar or bipolar channel mode.
To use classifiers, follow the standard flow described above.