Cybernetic Interface System

Interprocess Communication Method

for Biofeedback Systems
communicating with the
CIS
OVERVIEW
The CIS is a platform for the creation of biofeedback-controlled virtual reality
applications. Content (called “feedback interfaces” or “interfaces”) for the CIS can be
created with off-the-shelf 3D modeling apps, and without requiring programming. The
content developer specification is covered by another document. This document covers
the specification for biofeedback systems to communicate to the CIS. There is a third
specification that covers the method for a program other than the biofeedback system to
hook to a feedback interface during training to get/set data in the interface.

The CIS is composed of multiple programs. The programs that provide feedback
interfaces are referred to as CIS “titles”, not “games”. This is because feedback
interfaces may, or may not, be “game-like”. Some interfaces could include task
challenges very much like a neuropsyche test.

A biofeedback system (hereafter referred to as an “acquisition system” because it

acquires the physiological data) communicates with a CIS title using the TCP/IP
protocol. Because of this, the CIS can be run on the same computer as the acquisition
system or over a LAN (internet usage is conceivably possible, but not tested).
Communication is handled via a TCP connection, and a UDP connection. The TCP
connection is used to pass commands. The UDP connection is used to pass the values of
physiological measurements used to drive feedback. Using TCP to pass commands
insures that the command messages will be received with no errors. This is critical
because a corrupted command could have unintended consequences. Values for real-time
physiological measurements that are used for feedback (i.e. amplitude, coherence%, etc.)
are sent via UDP, because the values are updated many times per second, and the values
in a UDP packet that gets dropped or corrupted will be refreshed in a small fraction of a
second anyway. UDP also has considerably less overhead because of the lack of error
correction, which makes it ideal to handle the network traffic associated with sending the
high volume of real-time feedback data.

A CIS title acts as a server receiving commands via TCP on port 1001. Once the
acquisition system has connected to this port, it will be able to send commands to the
CIS, as well as receive data that’s intended for UI support. Optionally, the data sent by
the CIS title to the acquisition system doesn’t have to be acted upon, but it does facilitate
a way for a system manufacturer to mirror the UI found in the CIS icon (located in the
system tray when a CIS title is running) in whatever form deemed most appropriate for
integration into the acquisition system’s own UI. The UDP connection is unidirectional
(acquisition system sending values to the CIS title), and is made on port 1003. An .ini
file is used to determine/set the IP address the acquisition system should use to contact a
CIS title. This .ini file is named “installed titles.ini” and can be found in
C:\BeyondVR\initialsOfTheAcquisitionSystem. The entry is “gamecomputer”, under the
[Setup] section. If “gamecomputer=local” then the acquisition system and the CIS are on
the same computer, and an IP address of 127.0.0.1 (loopback) should be used.

The CIS includes an application called the “Internal Signal Generator” (ISG). This
application is a “fake” acquisition system that sends simulated data to CIS titles. This
makes it possible for users to get familiar with using the CIS titles and the multitude of
feedback interfaces, without having to use a real biofeedback system (though it looks
similar to one). The ISG uses the specification laid out in this document, so it is a good
example to turn to for implementation ideas.
SETUP
CIS titles are installed to specific predetermined (at this time) directories. The directory
structure is C:\BeyondVR\initialsOfTheAcquisitionSystem\nameOfTitle. Currently, .ini
files are used to control a number of things related to the operation of CIS titles, and these
files are located in the directory where the title was installed. In this section of this
document, references to files or folders are relative to the install directory of the CIS title
unless explicitly noted otherwise.

When a CIS title first starts, it will automatically display the feedback interface it last
used. The file named “interface-initialsOfTheAcquisitionSystem.ini” contains two entries
under the “Setup” section that can be used to set some interface startup preferences.
1) interface= name of file The name of the interface to start up with. The interfaces are
found in the folder named “interface”, and end in the extension .wrl.
2) currentUser= a user’s id If this entry is modified before the title is started, the title
will use and save user defaults. This makes it possible for the title to start up with the
interface the client last used, instead of whatever the title last used. The interface
defaults for users are automatically stored in “patient settings.ini”.
Note: The file named “interface-ISG.ini” works in the same manner as the file named
“interface-initialsOfTheAcquisitionSystem.ini”, but it is for the Internal Signal Generator
(do not modify it).

Once feedback begins, objects in the scene will begin to respond. Training should be
broken down into “periods”. After a period is over, a report screen will be displayed,
showing the user’s progress. This cycle continues until the training is complete. A
period can be defined in any way – it’s up to the acquisition system to decide what
constitutes a “period”. A period could be based on time training, points earned,
physiological criteria, etc….

Some Important Things to Remember:

1) Commands ARE case sensitive strings.
2) A sent command must end in a “=” sign, have a value, and terminate with CHR(127)
No spaces between the command value and the equal sign or CHR(127).
Example: “SOMECOMMAND=” & someValue & CHR(127). In some cases, a
command that needs to be sent may not actually have a meaningful value parameter.
Set the value to “0” (not null) in these instances.
3) Must use the “AS” command to identify the biofeedback system in use.
4) Before calling for the display of a report screen it is important to do these 3 steps:
Stop sending feedback data, send the command “PAUSE=True”, and send the
“REPORTSCREENTYPE=theType” command. After that, it is safe to send the
“SHOWREPORT=True” command.
5) When done displaying the report screen and the command “SHOWREPORT=False”
has been sent, send the command “PAUSE=False” before continuing to send
feedback data again.
6) Commands that effect an interface are ignored during the display of a report screen
(the feedback interface isn’t loaded, and thus can’t react to the commands).
7) When loading a feedback interface while the user is training, stop sending feedback
data and send the “PAUSE=True” command before loading the different interface.
Then send the “PAUSE=False” command before continuing to send feedback data.
SENT COMMANDS
AS=string
This is used to identify the biofeedback system being used. Must be sent when
the connection to the CIS title is first made. Must be equal to the identification string
given to you by BVR.

EXIT=0
Tells the title to close.

PAUSE=boolean
Tells the title to temporally stop/start keeping track of how much time is spent
training. This info is used by some of the report screens. Total time training, and time
spent training during each period is kept track of.

1=single, 2=single, 3=single, etc. (minValue = -1 , maxValue = 1)

These commands must be sent via UDP. No other commands are sent via UDP.
Every interface has a number of “feedback streams”. Each stream controls
various things that happen in the scene. A simple conceptual example would be the
standard 3 boxes paradigm in which a person tries to keep two of the boxes small, while
keeping one as large as possible. Each box is controlled by its own particular “feedback
stream”. So stream1 may be might be theta suppression, stream two SMR augmentation,
and stream3 could represent a high beta inhibit. It should be noted that the CIS does not
actually know what physiological parameter the feedback stream represents (dumb client
model).
The value sent must be between the range of –1 and +1. Values less than 0 will
indicate negative reinforcement is appropriate. Values greater than (or equal to) 0 will
indicate positive reinforcement is appropriate. These values can easily be determined by
taking into account whether the physiological parameter is to be augmented or inhibited.

Example:
'determine the reinforcement value
If FSreinforcementType(stream) = "INHIBIT" Then
FSreinforcement(stream) = FSthreshold(stream) / FSamplitude(stream)
If FSreinforcement(stream) >= 1 Then 'Succeeding
FSreinforcement(stream) = (FSreinforcement(stream) - 1) * 1
If FSreinforcement(stream) > 1 Then FSreinforcement(stream) = 1
Else 'Failing
FSreinforcement(stream) = (1 - FSreinforcement(stream)) * -1
If FSreinforcement(stream) < -1 Then FSreinforcement(stream) = -1
End If
ElseIf FSreinforcementType(stream) = "AUGMENT" Then
FSreinforcement(stream) = FSamplitude(stream) / FSthreshold(stream)
If FSreinforcement(stream) >= 1 Then 'Succeeding
FSreinforcement(stream) = (FSreinforcement(stream) - 1) * 1
If FSreinforcement(stream) > 1 Then FSreinforcement(stream) = 1
Else 'Failing
FSreinforcement(stream) = (1 - FSreinforcement(stream)) * -1
If FSreinforcement(stream) < -1 Then FSreinforcement(stream) = -1
End If
End If
REPORTSCREENTYPE=typeOfReport (string)
typeOfReport= bargraph-points, bargraph-points and achievements, bargraph-
points and time, bargraph-points achievements and time, bargraph-achievements
and time, picture
Defines the type of report screen to display. Send this command before sending
the “SHOWREPORT=True” command. It should be noted that some report screens are
not appropriate to use under certain circumstances. If the biofeedback software is
determining periods by a set amount of time, it’s kind of silly to use a report showing the
amount of time elapsed each period – it’s always the same and would just add useless
info the report screen. If the biofeedback software is advancing periods based on a set
number of points it isn’t informative to display a report screen after period showing them
they got 100 points every period. Chose a report screen type that is the most informative
without displaying irrelevant information. The report type called “picture” display the
points, achievements, and period info, but will not generate bar graphs.

REPORTSCREENLOCATION=location of a graphic file (string)

Normally, the report screen will use either a gray background or a background
defined by the CIS title. When reportscreenType=picture, the background used will be a
the picture defined by this command. This allows an acquisition system to make it’s own
report screens for display in the CIS title. GIF, JPEG, and PNG formats are supported.

SHOWREPORT=boolean
Tells the CIS to display, or stop displaying, a report screen for the completed
periods of training.

INTERFACELIST=0
Requests a list of available feedback interfaces. Each name in the list is separated
by a CHR(13) character (enter key).

INTERFACEDESCRIPTION=0
Request a refresh of the loaded feedback interface’s description. The description
is automatically sent whenever an interface is loaded, but some variables may change
during training.

GETPREVIEW=string
Returns a simple description of what an interface does. The name of the interface
needs to be a valid name returned by the “INTERFACELIST=0” command. The
interface doesn’t have to be loaded to get the short preview description.

LOAD=string
Load the feedback interface named “string”. Must be a valid interface name.

COMMAND=string
The feedback interfaces can accept various different commands. These
commands may be different from one interface to the next. Sending an invalid interface
command will not result in an error (nothing will happen). Interface commands are not
case-sensitive.
Interface commands should be able to be typed in a text field and sent by the user
by pressing a button or hitting enter.
GCOMMANDS=0
This command will request a list of the default commands for the currently loaded
interface. Each feedback interface can have its own set of commands that are
automatically executed by the CIS every time the interface is loaded, including when an
interface is immediately loaded after the display of a report screen.

DCOMMANDS=string
For sending an updated list of default commands (see GCOMMANDS) for the
currently loaded feedback interface. The CIS automatically saves this list of commands
to an .ini file specific to the feedback interface. Each command must be separated by
CHR(13) & CHR(10). This particular character combination tells a textBox object (in
Visual C++ or Visual Basic) to advance a line without showing a strange character. This
makes it possible to take the string and send it directly to a textBox and have it displayed
properly.

POINTSSUCCESSTIME=single
The amount of time that must elapse, while meeting all success criteria, in order
for a point to be awarded.

POINTSFAILURETIME=single
The amount of time that can elapse, while not meeting all success criteria, before
the accumulated success time for a point (see above) is reset back to 0.

POINTRANDOMREWARD%=single (minValue = 0 , maxValue = 100)

The chance to get a random reward when a point was earned.

ACHIEVEMENTSSUCCESSTIME=single
The amount of time that must elapse, while meeting all success criteria, in order
for an achievement to be awarded.

ACHIEVEMENTSFAILURETIME=single
The amount of time that can elapse, while not meeting all success criteria, before
the accumulated success time for an achievement (see above) is reset back to 0.

ACHIEVEMENTRANDOMREWARD%=single (minValue = 0 , maxValue = 100)

The chance to get a random reward when an achievement was earned.

LONGTERMPOINTS=single
The number of points to elapse for each long term reward event.

The commands in this section can also be sent by the user via the Interface Command
feature accessed by the CIS icon. The ability to do so is an undocumented feature (other
than in this documentation). The commands that are accepted in the command field are
PST=, PFT=, PRR%=, AST=, AFT=, ARR%=, LTP= along with the appropriate value.
People who wish to use customized success criteria every time a particular feedback
interface is used, can put these interface commands in the “commands-
interfaceName.cfg” file.
POINTSINDICATOR=boolean
ACHEIVEMENTSINDICATOR=boolean
PERIODINDICATOR=boolean
FRAMERATEINDICATOR=boolean
Tells the title whether or not to display the various HUD indicators. Turning off
the FrameRate indicator is not recommended because it lets the clinician know if their
hardware is not able to render the 3D scene in a timely manner.

CDI=boolean
Determines whether or not the feedback interface modulates the playback volume
of CD audio based on feedback criteria, or if the CD should simply play the music
without it being tied to feedback criteria. Interfaces define the dynamic characteristics of
the CD volume modulation. Default is for the interface to control CD volume.

CDPLAY=0, CDSTOP=0, CDEJECT=0

CDNEXTRACK=0, CDPREVIOUSTRACK=0
Playback will automatically begin if a CD is already in the CD player when the
CIS starts. However, the volume will immediately be set to zero if the feedback interface
is set to control the CD playback volume because the user will not have started training
the instant the interface is loaded and displayed.

CDRT=boolean
Repeat/loop the track currently playing.

CDVOLUME=integer
The maximum volume for CD playback. Note that this is the maximum volume,
so it is the loudest that playback will be if the CD volume is controlled by the feedback
interface. This makes it possible to easily control the CD volume in relation to the other
sounds in the feedback interface. If CD volume is not set to be controlled by the
feedback interface (CDI=False) then this value will set the actual volume.

CPU=integer (minValue = 25 , maxValue = 100)

Used to set the amount of CPU load for the 3D engine used by the CIS. A value
of “100” does not mean that 100% of the CPU resources will go towards operation of the
CIS title. It is a number representing the maximum allowable load. The acquisition
system should monitor its own performance and adjust the amount of CPU load allocated
to the CIS title if/when needed.

FRAMERATE=0
Requests the 3D engine’s current display framerate. This can be used in
conjunction with the CPU command to further optimize system performance.

DATARPS=0
Number of times per second the CIS should send incoming data into the scene
graph. This is NOT the amount of times per second the scene graph refreshes to the
screen (framerate). This facilitates asynchronous communication to a CIS title via the
UDP connection.
SNAPSHOT=string
Tells the CIS title to take a screen shot of what’s in the feedback interface
window. Specify a name to save the picture as. The picture will be saved in the folder
that the CIS title was installed in. Picture format is JPEG. Do not add the extension
name (.jpg) to the file save name.

RECEIVED COMMANDS

EXIT=0
The title was closed

CISstate=string (“connected” or “disconnected”)

Sent when first connected or closed.

P=integer
The current number of points. This is sent every time a point is earned.

A=integer
The current number of achievements (a type of “higher order” points). This is
sent every time an achievement is earned.

PR=integer
The current training period. Sent at the beginning of every training period.

INTERFACE=string
The name of the currently loaded feedback interface. This is automatically sent
every time an interface is loaded, including when an interface is automatically loaded
after displaying a report screen.

IDESCRIPTION=string
A full description of how the currently loaded interface functions (no need for the
user to locate a manual). This is automatically sent whenever an interface is loaded,
including when an interface is automatically loaded after displaying a report screen.

PREVIEW=string
A short description of how an interface works. This command is received after
the GETPREVIEW command was sent. GETPREVIEW / PREVIEW combination is
useful for a dialog box listing the available feedback interfaces. Suggested use - A user
can get a short description of an interface they click on without having to actually load it
to get the full description (IDESCRIPTION).

INTERFACELIST=string
A list of available feedback interfaces. This list is returned when the
INTERFACELIST=0 command is sent. The name of each interface is separated by
CHR(13).
#S=integer
The number of feedback streams the currently loaded interface supports.
Automatically sent whenever a feedback interface is loaded. It is very important for the
number of feedback streams supported by the currently loaded interface to match the
number of feedback streams currently being sent by the biofeedback software.

DCOMMANDS=string
This string is returned after the GCOMMANDS command was sent. Each
command is separated by CHR(13) & CHR(10). This particular character combination
tells a textBox object (in Visual C++ or Visual Basic) to advance a line without showing
a strange character. This makes it possible to take the string received and send it directly
to a textBox and have it displayed properly. The list of commands can then be edited in
the textBox by the user and should be automatically sent back to the CIS so that it can be
updated (via the DCOMMANDS sent command) when the user is done editing/looking at
the list.

POINTSSUCCESSTIME=single
The amount of time that must elapse, while meeting all success criteria, in order
for a point to be awarded.

POINTSFAILURETIME=single
The amount of time that can elapse, while not meeting all success criteria, before
the accumulated success time for a point (see above) is reset back to 0.

POINTRANDOMREWARD%=single (minValue = 0 , maxValue = 100)

The chance to get a random reward when a point was earned.

ACHIEVEMENTSSUCCESSTIME=single
The amount of time that must elapse, while meeting all success criteria, in order
for an achievement to be awarded.

ACHIEVEMENTSFAILURETIME=single
The amount of time that can elapse, while not meeting all success criteria, before
the accumulated success time for an achievement (see above) is reset back to 0.

ACHIEVEMENTRANDOMREWARD%=single (minValue = 0 , maxValue = 100)

The chance to get a random reward when an achievement was earned.

LONGTERMPOINTS=single
The number of points to elapse for each long term reward event.

DTRAININGCRITERIA=string
A comma-delimitated list of values specifying the default training criteria for an
interface. The values are in this order: points success time, points failure time, points
random reward%, achievements success time, achievements failure time, achievements
random reward%, long term reward for points

REPORTSHOWING=boolean
Sent by the CIS when a report screen is first displayed, and when it’s unloaded.
POINTSINDICATOR=boolean
ACHEIVEMENTSINDICATOR=boolean
PERIODINDICATOR=boolean
FRAMERATEINDICATOR=boolean
Whenever the state of the HUD indicators is changed, the state is then transmitted
by the CIS. The user can change the state of the HUD indicators via the CIS icon in the
system tray, and it’s a good idea to make it possible for the user to be able to change it
from the biofeedback software as well.

CDPLAY=boolean, CDSTOP=boolean, CDEJECT=boolean

CDNEXTRACK=boolean, CDPREVIOUSTRACK=boolean
Whenever the state of the CD player is changed the CIS will update the CD menu
of the CIS icon. Some items should be enabled at times when others should be disabled.
Example: the Stop item on the CD menu gets grayed out when the CD player has
stopped. This info is also transmitted to the acquisition system so that a matching menu
can easily be made without worrying about any type of multi-media programming.

CDI=boolean, CDRT=boolean
Whether or not the “CD controlled by the Interface” or “Repeat Current Track”
menu items of the CD playback menu are checkmarked.

CDTRACK=integer
The current track number of the CD that is playing.

CDVOLUME=integer (minValue = 0 , maxValue = 100)

Whenever the CD volume is changed, either by the CD volume slider in the CIS
or by sending the CDVOLUME command, it will echo the changed back to the
acquisition system. This makes it possible to keep both volume sliders in synch. Take
care not to cause a cascading loop from sending and receiving values via the
CDVOLUME commands.

FRAMERATE=single
This is returned whenever the FRAMERATE=0 command was sent.