Protocol Tab

The "Protocol" tab houses all triggering parameters, including which frequency bands to trigger at, which phase to trigger, the number of triggers, the port of the triggers, and other parameters.

Protocol Management

Working with Protocols after a fresh startup

Whenever you start the bossapp, it will boot with only a placeholder protocol configuration with a single condition. Each time you open or restart the bossapp, you must load, edit or create the protocol configuration you wish to use.

Creating a Protocol

You can make a new protocol from scratch by clicking the "New" button in the "Protocol Management" box. It is also possible to use the template or a previous protocol to make a new protocol by using the "Add" and "Delete" buttons. In this case, it is highly recommend to edit the default name "My Protocol". To do so, right click on the dropdown Protocol menu, and select "Edit name".

Enter Protocol Name

This name will show up for your protocol within the bossapp. It is not the file name that it will be saved under on your computer. Enter a name here, and it will appear in the Protocol Control box dropdown at the top of the bosssapp. The protocol name can be edited at any time by right clicking on the Protocol dropdown menu.

Saving a Protocol

To save a protocol, click the "Save" button. In the pop-up window, name the file and save it in whichever folder you choose.

Don't forget to export and save the Protocol as a file for later use

Creating a new protocol does not save the protocol. Until saved, this protocol will only exist within the open session of the bossapp. Once the bossapp is closed, this protocol will be deleted.
Any changes made to a protocol, once opened, do not automatically save to the protocol file on your computer. If you change the protocol, save it as a new file on your computer.

Naming Convention Notes

Protocols have a "Protocol name," shown in the bossapp, and a "file name," shown in your computer files.
The "Protocol name" is given when you click "New" in the pop-up window. This can be changed at any time from the context menu.
The "file name" is given when you click "Save" in the pop-up window. This can be changed anytime from the File Explorer on your computer.
The "Protocol name" and the "file name" can be the same. They can also be different. You may decide which works best for you.

Deleting a Protocol

Clicking the “Delete" button removes the current protocol from the current session of the bossapp. “Delete" does not delete the file from your computer if the protocol was previously saved. To delete the protocol file from your computer, open File Explorer, find the file, and delete it.

Loading a Protocol

To load a previously saved protocol file, click the “Load" button to navigate to your saved file.

Save permanent changes of modified protocols

Any changes made to a protocol do not automatically save to the protocol file on your computer. If you change the protocol, save it as a new file on your computer.

Protocol Control

Condition Switch Order

The "Condition Switch Order" dropdown allows you to choose which order the conditions you define in the condition table run. The options are

Sequential: The conditions will run in order.
Random: The conditions will run in random order. Every time the protocol is run, the order will be different.
Marker based: Each condition will have a specific marker value defined in the "Condition Activation Marker" column and when that marker is received, this condition will start. The order of the conditions in the table does not matter.

Reset

Pressing the "Reset" button restarts the entire protocol from the beginning of the first condition.

Note

If the protocol is stopped from the "Protocol Control" box at the top of the bossapp (in the "Top Bar"), it will stop and reset only the current condition when resumed from the top bar.

Run Condition

If "Autostart" is not selected for a condition in the "Condition Table", that condition will not start on its own when the previous condition finishes. Press the "Run Condition" when you are ready to start the pending condition.

Parameters

Minimum Trigger Interval [s]

This parameter allows you to define a "wait time" between conditions. This time starts when the final trigger in the previous condition is sent.

Marker Output Pulse Width [s]

This parameter defines the constant pulse width sent by the bossdevice according to the marker configuration. See this section for more details.

Marker Force Next Condition [-]

When this marker is received, the protocol will immediately stop the current condition and start the next condition. This is the same as pressing the "Next" button.

Conditions Table

Each row in the Protocol tab is a condition. Each condition defines a set of criteria that must be met for a trigger to be sent, how many times these criteria should send a trigger, and the structure of that trigger. When one condition is finished, the next condition will start automatically if "Autostart" is selected, or wait for until the "Run Condition" button is pressed if "Autostart" is not selected. This allows for multiple triggering criteria within a single protocol and multiple trigger structures. When running, the current condition will be highlighted in orange. If completed successfully, the condition will show green. If "Force Next Condition" was selected during this condition, the skipped row will be highted blue.

Simple Examples:

You could design a Protocol with a condition that sends 5 TMS pulses at alpha peaks from port 1, then 5 TMS pulses at alpha troughs from port 1, and then 5 TMS pulses at alpha peaks from port 1.
You could design a Protocol with a condition that sends 5 TMS pulses at beta troughs through port 1, then a condition to send 10 TMS pulses at theta peaks through port 1.
You could design a Protocol with a condition that sends 10 TMS pulses at theta troughs through port 1 and then a condition that simultaneously sends 10 TMS pulses through port 1 and 10 TTL triggers through port 2 into a stimulus display software at beta peaks.

Less Simple Example

You could have a protocol that sends a burst of 5 TMS pulses through port 1 every time both alpha and theta are at their peak until 15 of these bursts have been triggered. After 15 instances of condition 1, a second condition waits for a marker from a stimulus display software and then simultaneously sends a single TMS pulse through port 1 and a TTL pulse into the EEG data through port 2.

Name

Give each condition any name that makes sense. It may be useful to keep the protocol index present in the name.

Autostart

If "Autostart" is selected, the selected condition will start as soon as the previous condition finishes. If "Autostart" is not selected, the selected condition will not start until the user manually starts it using the "Run Condition" button in the "Protocol Control" box. Disabling "Autostart" can be used to create a break in the protocol that can be used to check or adjust data quality, give the subject a break, or other actions that cannot happen wile the protocol is running.

Trigger Configuration

Warning

Legacy protocol files including example protocols used during the pre-release used a different trigger configuration format. These files can still be opened as protocols and will cause errors.
If your Trigger Configuration cell displays "1x4 table", the protocol is using legacy format and will cause problems.
If your Trigger Configuration cell displays "1x7 table", and then upon opening the cell, the column names are "Var 1, Var2, etc.", the protocol is using legacy format and will cause problems.
If your protocol is using legacy Trigger Configuration, remake the protocol from scratch by clicking on "new" in the protocol management box. If you need assistance, please reach out to support@sync2brain.com

Double-click on this cell to open the trigger configuration. Here, you can define which ports your triggers are sent through, how many triggers are sent each time the defined criteria are met for each condition, and which markers are sent. Note the window's title in the top bar to figure out what condition you are editing. Close this window, and double-click on the corresponding row, if you want to edit a different condition.

Please use the visualization on the right panel as a supporting tool as you define the triggers configuration, it will immediately reflect every change applied on the table.

Note

You must click “Accept”, or your changes will be disregarded.

Time [s]

The time point, in seconds, the positive flank for the pulse and the marker are sent with respect to the trigger (t=0s). If you want the pulse and trigger to be sent as soon as the condition is met, set "Time" to 0. If you want the pulse and trigger to be sent 500ms after the condition is met, set "Time" to 0.5.

Pulse Width [s]

How long the TTL pulse should last in seconds.

Note

Some receiving devices may limit how short the TTL pulse can be and still be detected by the device. If your device does not receive pulses, it may be helpful to make them longer and try again.

Port #1-4 Checkboxes

Check the box for all ports that you want to send the pulse defined in this row.

Marker

Marker value to send from the "Marker Out" parallel ports of the bossdevice. This is useful for additional experiment logging.

Trigger Configuration Examples

If I wanted to send 1 pulse out of port 1 (the BNC port labeled Trigger 1 on the bossdevice) to a TMS machine as soon as the condition was met, I would enter "0" in "Time [s]" and "1" under "Encoded Port". If I needed my pulse to be a certain length to be registered by my TMS machine, I would increase the value in "Pulse Width [s]". In this case, I'm not using markers and will enter "0" in that column.
If I wanted to repeat the first example, but send an additional identical pulse out of port 2 into my EEG data stream via bnc/TTL, I would click the checkbox for Port #2. I may need to adjust the "Pulse Width [s]" if it is not detected by my EEG device.
If I wanted to send a pulse to my TMS from port 1 500ms after the conditions were met, I would set "Time [s]" to "0.5" and select the check for Port 1.
If I wanted to send a marker into the EEG data stream or into a stimulus display software via the "Marker Out" db25/parallel port on the bossdevice, I would define how long I want to wait after the condition is met before sending under "Time [s]" and which value I want the marker to be under "Marker". I would not select any port checkboxes in this case.

Warning

You cannot send two overlapping pulses from the same port.
You cannot send two markers at the same time point.
Pulses sent from the BNC "Trigger Port"s and markers sent from the "Marker Out" db25/parallel port on the bossdevice RESEARCH are not TMS pulses. Pulses and markers sent from the bossdevice RESEARCH can initiate TMS pulses from your TMS machine, but they are not themselves the TMS pulses. The TMS pulses must be configured on your TMS machine. Whichever TMS pulse or sequence of TMS pulses you have set on your TMS machine will be activated when the TMS machine receives the correct pulse or marker from the bossdevice RESEARCH.

Hints

If you want to send pulses from multiple ports at the same time, select multiple port checkboxes, do not make multiple rows.
Row 2 cannot start until Row 1 has completed. You cannot send a 2s pulse from port 1 at t0 in row 1 and a 1s pulse from port 2 at t1 in row 2. The earliest the pulse in row 2 could start is at t2.
When pulses are sent from multiple ports at once or the rising edge of 1 pulse is the falling edge of another, the lines overlap and you can only see one color. To visually check, toggle the checkboxes one at a time.

Num. Cycles

This cell determines the number of cycles of this condition. If you want to trigger at alpha peaks 50 times, enter "50".

Since you can use the “Trigger Configuration” cell to send multiple pulses or markers each time a triggering criterion (e.g., peak alpha) is met, the “Num. Cycles” cell does not represent the number of pulses or markers sent from the bossdevice RESEARCH ports. For example, if each time peak alpha is detected, we fire a series of 3 pulses through port 1, and "50" was entered in "Num. Cycles", this cycle would happen 50 times for a total of 150 pulses from the bossdevice RESEARCH. Even more, if the TMS machine is configured to fire a triplet at each pulse from the bossdevice RESEARCH, 50 cycles would result in 150 triplets totaling 450 TMS pulses.

Enable Alpha/Beta/Theta

If this box is checked for one or more frequency bands, the criteria defined in Alpha/Beta/Theta Detection must be met to send a trigger. If Enable Alpha and Enable Theta are checked in the same condition, both criteria must be met to fire.

Alpha/Beta/Theta Target

Double-click on this cell to define the target phase and tolerance for this frequency bin when it is checked for a condition.

Note: These cells accept "pi" as a number.

You can enter π/2 as "pi/2," and it will calculate 1.5708, or you may enter "1.5708".
You can enter 3π/2 as "3*pi/2," and it will calculate 4.7124, or you can enter "4.7124".

Target Phase [rad]

This cell defines the phase you want to target. As a reference, positive peak is 0, negative peak is π, falling flank is π/2, and rising flank is -π/2.

Target Absolute Tolerance [rad]

Because we target a dynamic, complex biosignal in real-time, it is not always possible to have a continuous signal that presents clear or perfect peaks or troughs. This field defines the tolerance away from the exact target you chose that is still acceptable to fire at.

Note

The default is π (3.14) and should be changed for proper oscillation-targeted triggering.

Condition Activation Marker

It is possible to have the order of the conditions determined by incoming markers using the "Marker In" db25/parallel port on the bossdevice RESEARCH. For this to work, "Marker Based" must be selected from the "Protocol Control" box under the "Protocol" tab. In addition, each condition must have a unique marker value entered into the "Condition Activation Marker" column. When that marker is received by the bossdevice RESEARCH, the corresponding condition will start. A condition can be repeated if the corresponding marker is detected after that condition was completed. If a condition is completed and a new marker has not been received by the bossdevice RESEARCH, the stimulation remains idle until a marker is received.

Remote Enable/Disable Marker columns

The “Remote Enable/Disable Marker" fields define a window at which you can fire (i.e., firing is possible in the window between the two received markers only).

Move Up / Move Down

If you would like to move a condition up or down, click on the index of the row (the very left column, example in red) so that the row shows blue. Then use the Move Up/Move Down buttons to move the condition to the index that you would like it.