API Methods and Properties

Table of Contents
bossdevice Methods arm bossdevice configure_generator_sequence manualTrigger disarm initialize sendPulse start stop clearPersonalSettings changeBossdeviceIP setparam selectFirmware installFirmwareOnToolbox plot_generator_sequence Properties theta alpha beta sample_and_hold_seconds spatial_filter_weights min_inter_trig_interval triggers_remaining marker_pulse_width_sec generator_sequence num_eeg_channels num_aux_channels isConnected isRunning isArmed isGeneratorRunning bossdevice_oscillation Methods ignore Properties phase_target phase_plusminus amplitude_min amplitude_max lpf_fir_coeffs bpf_fir_coeffs offset_samples

bossdevice

Methods

arm

Arming bossdevice would allow bossdevice to actively search for the Brain states already set into it and generate the TTL output sequence configured using “configure_time_port_marker” upon every instance of detection.
bd.arm

bossdevice

The bossdevice API can be initialized as a MATLAB Class object and provides access to its methods and functions to generate various TTL outputs and define multiple brain states upon which the predefined TTL output sequence to be released.
bd = bossdevice; % "bd" class object is created in MATLAB workspace

configure_generator_sequence

configure_generator_sequence method of bossdevice allows you to prepare a sequence of TTL output in [time duration port marker] vector style. Maximum of 400 TTL outputs can be loaded onto this configuration method. In order to prepare a single TTL output in [time duration port marker] style, just give input argument as [0 0.001 1 1] vector. Each TTL output in this vector has four elements, first index being time after trigger, the second element is the pulse width in seconds, the third element is the port number of bossdevice to deliver the output pulse and the last elment is the 8-bit event marker to be generated and written to the Biosignal processor for respective TTL output.
bd.configure_generator_sequence([2 0.1 3 144]);
% configures a TTL output sequence in which the pulse will be delivered 2 seconds after the trigger
% with a pulse width of 0.1s, on the 3rd port and event writes 144 marker on the Biosignal processor
 
bd.configure_generator_sequence([3 0.1 3 144; 4 0.3 2 128]);
% configures 2 TTL output sequences in which the first pulse will be delivered 3 seconds after the trigger
% with a pulse width of 0.1s, on the 3rd port and will writes 144 marker on the Biosignal processor,
% and then the second pulse will be delivered 4 seconds after the trigger (approximately one second after the first pulse),
% with a pulse width of 0.3s, on the 2nd port and writes 128 event marker on the Biosignal processor

manualTrigger

Sends a single trigger with the current active sequence. See configure_generator_sequence for more information about generating custom trigger sequences. The function is blocking and will wait until the sequence is complete.
% Set trigger configuration on bossdevice
bd.configure_generator_sequence([2 0.1 3 144]);
 
% Sends trigger
bd.manualTrigger;

disarm

Disarming bossdevice would allow bossdevice to stop search for the Brain states already by now “Armed’ into it and immediately stops the generation of the planned TTL output sequence configured using “configure_time_port_marker” .
bd.disarm

initialize

Initializes the bossdevice by establishing the connection and loading the firmware. When the bossdevice is initialized, the real-time application can be started with the start method.
bd.initialize

sendPulse

sendPulse method of the bossdevice class allows you to generate 1 TTL pusle at a specified Output port (out of 4) of the bossdevice.
bd.sendPulse(1) % delivers a single pulse at the Output port 1
 
bd.sendPulse(3, 0.1, 44) % delivers a single pulse at the Output port 3 of width 0.1s and sends a marker of value 44

start

Starts running the firmware on the bossdevice with the default parameter settings, generator and trigger status.
bd.start

stop

Stops the firmware running on the bossdevice. Any pulse triggering or processing will stop immediately. It leaves the bossdevice on idle and the firmware ready for another test.
bd.stop

clearPersonalSettings

Clear any bossdevice target settings including name and IP address that may have been entered by the user and restores the factory settings "bossdevice" and "192.168.7.5" respectively.

changeBossdeviceIP

Change the remote IP address on the bossdevice used for the host-target communication.
bd.changeBossdeviceIP('192.168.1.5') % Introduce the new IP address desired for the bossdevice
After executing this command, the bossdevice will reboot. Please wait a few seconds, until the device is back online before executing further commands.

setparam

The setparam method can be used to tune parameters on the bossdevice. This is useful in some advanced use cases. For example, consider the following commands to control the triggering in the bossdevice by remote markers sent from the amplifier.
bd.setparam('MRK','remote_enable_value',51);
bd.setparam('MRK','remote_disable_value',52);

selectFirmware

Open user dialog to select firmware file (.mldatx file extension) to load into the bossdevice.
bd.selectFirmware;

installFirmwareOnToolbox

Copies the firmware file into the toolbox folder for later reuse. It is recommended to run selectFirmware first.
bd.selectFirmware;
bd.installFirmwareOnToolbox;

plot_generator_sequence

Plots the currently configured generator sequence that will be generated on the bossdevice as soon as a trigger is raised.
% Plots currently configured generator sequence
bd.plot_generator_sequence;
 
% Plots input generator sequence for a quick visual check
bd.plot_generator_sequence([0.1 0.01 1 44]);

Properties

theta

Refer to bossdevice_oscillation.

alpha

Refer to bossdevice_oscillation.

beta

Refer to bossdevice_oscillation.

sample_and_hold_seconds

Upon an artifactual event such as pulse artifact etc., the data gets distorted and is accumulated with a lot of noise, in order to hold the samples for a specified period of time, sample and hold period method can be helpful.
bd.sample_and_hold_seconds = 0.1; % hold the samples for 100 ms

spatial_filter_weights

Spatial filtering of the signals is an important step before commencing real-time brain states detection. The bossdevice allows to specify two different spatially filtered channels and can detect brain states (based on the target phase & amplitude) for both of these spatial filtered channels in parallel. If any one of them is specified then the other one is ignored and assigned 0 weights. The index of eeg_channels being streamed from the Biosignal processor e.g. ActiCHamp or NeurOne corrosponds to the index of the weights matrix explained below.
% assume that there are 5 EEG channels
bd.spatial_filter_weights = [0; -0.5; 1; -0.5; 0]; % the channel 1 will be assigned the given weights
% and all the eeg_channels for 2nd spatially filtered channel would have 0 weights
 
% assume that there are 3 EEG channels
bd.spatial_filter_weights = [0 -0.5; 1 1; 0 -0.5]; % the channel 1 will be assigned the weights given
% on first column and channel 2 will be assigned the weights given on 2nd column

min_inter_trig_interval

Minimum inter pulse interval allows you to define the time period for which the bossdevice should wait before generating another TTL output. It is the time span between falling and rising flanks of the trigger signal.
bd.min_inter_pulse_interval = 2; % bossdevivce will wait for 2 seconds before generating any TTL output

triggers_remaining

Number of triggers remaining for the current trial.

marker_pulse_width_sec

Tunable width of marker pulse signals in seconds. This pulse width is constant and independent of the TTL pulse outputs width.
bd.marker_pulse_width_sec = 0.001;

generator_sequence

Outputs the currently configured sequence of TTL output in [time duration port marker].

num_eeg_channels

bossdevice can work on maximum of 128 EEG channels, however the minimum number of channels required to work with EEG associated features of bossdevice have been kept flexible and can be defined as in number of EEG cannnels being streamed from your Biosignal Processor.
bd.num_eeg_channels = 64; % informing bossbox that 64 EEG channels are being streamed frm your Biosignal Processor

num_aux_channels

bossdevice can work on maximum of 8 Auxiliary/Biopolar/EMG channels, however the minimum number of channels required to work with Auxiliary Channels associated features of bossdevice have been kept flexible and can be defined as in number of Aux cannnels being streamed from your Biosignal Processor.
bd.num_aux_channels = 8; % informing bossbox that 8 aux/Emg/Bipolar channels are being streamed frm your Biosignal Processor

isConnected

Gets bossdevice connected status.

isRunning

Gets bossdevice execution or running status.

isArmed

Gets bossdevice armed status.

isGeneratorRunning

Gets bossdevice generator running status.

bossdevice_oscillation

Methods

ignore

Set amplitude and phase tolerance values that will disable triggering for the corresponding oscillation. You can pass an additional argument to the ignore command if you want to ignore a certain channel. Passing no argument will ignore all the channels.
bd.alpha.ignore(1);
bd.beta.ignore(2);
bd.theta.ignore;

Properties

phase_target

bossdevice contains 3 built in Oscillatory phase prediction models each for Theta (4-8 Hz), Alpha (8-14Hz) and Beta (14-30Hz) frequency bands. Real-time phase detection can be performed for maximum of 2 different, pre-specified spatially filtered channels in parallel. This method allows to define a target phase in radians for a particular frequency band.
bd.alpha.phase_target([spatial_filter_channel_number]) = phase_angle_in_radians % sets target phase of Alpha Oscillation
 
bd.alpha.phase_target(1) = 0; % bossdevice is loaded to detect peak (0 radians) from first spatially filtered channel
% with the assumption that the Oscillation is in Alpha frequency band
 
bd.beta.phase_target(2) = pi; % bossdevice is loaded to detect trough(pi radians) from second spatially filtered channel
% with the assumption that the Oscillation is in Beta frequency band

phase_plusminus

Defining absolute target phase angles in order to detect a brain state is often prone to error mainly due to the resolution of data obtained after sampling rate transition. In order to overcome this digitization resolution error another parameter has to be defined such that the vicinities of the target phase shall be made clear to the detection algorithm. For an instance, while detecting a 0 radians phase, the phase vector would probably look like this [-0.001324 -0.00234 0.00243 0.004324], and since none of them are mathematically equivalent to zero therefore in order to not allow to skip such Oscillatory Peak events and to increase the accuracy of the phase detection, a tolerance value is to be provided.
bd.alpha.phase_plusminus([spatial_filter_channel_number]) = phase_tolerance_in_radians % sets target phase tolerance
% of Alpha Oscillation [spatial_filter_channel_number] is an integer having value 1 or 2.
 
%Note: While targeting a random phase, the tolerance could go as high as possible i.e. pi radians or Nxpi radians e.g. 2pi etc
bd.alpha.phase_plusminus(1) = pi/40; % bossdevice is loaded to detect the setted target phase with a tolerance
% of pi/40 radians from first spatially filtered channel with the assumption that the Oscillation is in Alpha frequency band

amplitude_min

Defining minimum amplitude threshold in order to match a specific brain state is important. The bossdevice allows to define minimum amplitude threshold in micro volts that must be reached along with other brain state associated conditions such as maximum amplitude, phase target, and phase tolerance in order to be able to declare the brain state as detected and generate TTL output sequence. The bossdevice contains 3 built in Oscillatory minimum amplitude estimation models each for Theta (4-8 Hz), Alpha (8-14Hz) and Beta (14-30Hz) frequency bands. Real-time minimum amplitude detection can be performed for maximum of 2 different, pre-specified spatially filtered channels in parallel.
bd.alpha.amplitude_min(1) = 1000; % bossdevice is loaded to monitor the specified minimum amplitude threshold
% from first spatially filtered channel with the assumption that the Oscillation is in Alpha frequency band

amplitude_max

Defining maximum amplitude threshold in order to match a specific brain state is important. The bossdevice allows to define maximum amplitude threshold in micro volts that must be not be reached in order to be able to declare the brain state as detected and generare TTL output sequence. The bossdevice contains 3 built in Oscillatory maximum amplitude estimation models each for Theta (4-8 Hz), Alpha (8-14Hz) and Beta (14-30Hz) frequency bands. Real-time maximum amplitude detection can be performed for maximum of 2 different, pre-specified spatially filtered channels in parallel.
bd.alpha.amplitude_max(1) = 1000; % bossdevice is loaded to monitor the specified maximum amplitude threshold
% from first spatially filtered channel with the assumption that the Oscillation is in Alpha frequency band

lpf_fir_coeffs

Spatially filtered channel’s signals described in the “spatial_filter_weights” function are passed through a low pass FIR filter for anti-aliasing. The coefficients of this filter can be specified using this function provided that the filter has an order of 100 at maximum.
bd.alpha.lpf_fir_coeffs = fir1(6, 125/(1000/2));
bd.beta.lpf_fir_coeffs = fir1(6, 125/(1000/2));
bd.theta.lpf_fir_coeffs = fir1(6, 125/(1000/2));

bpf_fir_coeffs

Low pass filtered channel’s signal described in the “lpf_fir_coeffs” function is then pass through an FIR Band Pass filter. The coefficients of this filter can be specified using this function provided that the filter has an order of 100 at maximum.
bd.alpha.bpf_fir_coeffs = firls(80, [0 (11 + [-5 -2 +2 +5]) (500/2)]/(500/2), [0 0 1 1 0 0], [1 1 1] ); %creates FIR Band Pass filter
% of order "80" , around peak frequency of 11 Hz and assigned it to Alpha model of bossdevice
 
bd.beta.bpf_fir_coeffs = firls(100, [0 (19 + [-5 -2 +2 +5]) (1000/2)]/(1000/2), [0 0 1 1 0 0], [1 1 1] ); %creates FIR Band Pass filter
% of order "100" , around peak frequency of 19 Hz and assigned it to Beta model of bossdevice
 
bd.theta.bpf_fir_coeffs = firls(65, [0 (6 + [-2 -1 +1 +2]) (250/2)]/(250/2), [0 0 1 1 0 0], [1 1 1] ); %creates FIR Band Pass filter
% of order "65" , around peak frequency of 6 Hz and assigned it to Theta model of bossdevice

offset_samples

Number of samples within the phase being analyzed counting backwards. The larger the value the older the first sample in time is being considered, and therefore, a larger time span. This is a scalar value that can be different for every phase.
Please refer to demo_phase_prediction_error_simple to see an example of how number of offset samples can be used to adjust the offset in the computation of the phase prediction error.
Return to home