View source for Technical Reference:App Connector

==NOTE==
The '''AppConnector''' interface has been '''superseded''' by a variety of BCI2000 scripting and remote control options. It is being kept for backward compatibility.

===Instead of AppConnector ConnectorOutput, use WATCHes as follows:===
As a functional equivalent to the <tt>ConnectorOutput</tt> filter, execute the following [[User_Reference:Operator_Module_Scripting|scripting code]] at startup, e.g., from a batch file:
 ADD WATCH State1 State2 State3 ... StateN AT localhost:12345
As a result, the values of the state variables listed will be sent to the named UDP port whenever one of them changes. Multiple ADD WATCH commands may be used to send change notifications for different states (or expressions) to different UDP ports:
 ADD WATCH TargetCode AT localhost:2006
 ADD WATCH ResultCode AT localhost:2007

===Instead of AppConnector ConnectorInput, use a TCP connection as follows:===
As a functional equivalent to the <tt>ConnectorInput</tt> filter, you may establish a TCP connection to <tt>localhost:3999</tt> and issue a SET STATE command, e.g.
 SET STATE TargetCode 3
in order to set <tt>TargetCode</tt> to 3.

===To efficiently transport signal data from BCI2000 into other applications:===
Send a shared GenericSignal object through a TCP connection as demonstrated in
[[Programming Reference:SignalSharingDemo Signal Processing]].

===For more information about controlling BCI2000 from other applications, see===

[[User Reference:Operator Module Scripting#Commands operating on States]]

[[User Reference:Operator Module Scripting#Commands operating on Events]]

[[User Reference:Operator Module Scripting#Commands operating on Watches]]

[[Programming Reference:BCI2000Remote Class]]

[[User Reference:Module Command Line Options#Operator Module]]

[[Programming Reference:SignalSharingDemo Signal Processing]]

=Obsolete AppConnector documentation=
==Introduction==
The BCI2000 external application interface provides a bi-directional link to exchange 
information with external processes running on the same machine, or on a different machine
over a local network.
Via the external application interface, read/write access to BCI2000 [[BCI2000 Glossary#State Vector|state vector]] information and to the [[BCI2000 Glossary#Control Signal|control signal]] is possible. An external application may 
read the <tt>ResultCode</tt> state to access the classification result, set the 
<tt>TargetCode</tt> state to control the user's task, or get access to the 
control signal that is calculated by SignalProcessing so as to control an 
external output device (such as a robotic arm or a web browser). Multiple 
instances of BCI2000 running on separate machines may share sequencing and 
control signal information, allowing for interactive applications such as games.

===Scope===
The scope of this interface is to provide access to internal BCI2000 information 
for cases in which the generation of a full-fledged BCI2000 module is 
impractical. Such a case might be the control of external applications that 
practically do not allow full incorporation into the BCI2000 framework (such as 
the Dasher system for efficient low-bandwidth spelling). 

This interface is '''not''' intended to replace the existing BCI2000 framework for BCI2000 
communication. The advantages of writing modules that are fully integrated into 
the BCI2000 framework are that their configuration is achieved through the same 
interface as other BCI2000 configuration, that this configuration is stored in 
the data file along with all other system parameters, and that the state of the 
module at any given time is encoded in event markers that are also stored in the 
data file. In contrast, control of an external device using the External 
Application Interface implies that the configuration of the external device has 
to be done outside of BCI2000, that this corresponding configuration is not 
stored along with the data file, and that the internal state of the output 
device is not automatically saved together with the brain signals 
(although it is possible to introduce your own state variables
for this purpose using the operator module's [[User_Reference:Operator_Module_Scripting#INSERT_STATE_.3Cname.3E_.3Cbit_width.3E_.3Cinitial_value.3E|INSERT STATE]] scripting command).
Having no configuration and state information present in the data file will make it more 
difficult to reconstruct what exactly was going on during an experimental 
session. It is thus important to keep this in mind when using this 
possibility.

===Design===
The design of the external application interface aims at simplicity, and at minimal 
interference with the timing of the signal flow through the BCI2000 system. With 
this in mind, a connection-less, UDP based transmission protocol was chosen 
rather than one based on TCP. This comes at the cost of a possible loss, or 
reordering of protocol messages. To keep the probability for such losses as low 
as possible, and their consequences as local as possible, messages have been 
designed to be short, self-contained, and redundantly encoded in a human 
readable fashion.

The connectionless nature of UDP implies that there is no ''server'' or ''client'' in the asymmetric sense that applies for TCP connections. Rather, processes write to local or remote UDP ports, and read from local UDP ports, whenever applicable.
Thus, for bi-directional communication between machine A running BCI2000 and machine B running the external application, there will be two UDP ports involved:
* a port on machine B into which BCI2000 writes out its messages to the external application, and
* a port on machine A into which the external application writes its messages to BCI2000.
In most cases, both BCI2000 and the external application will run on the same machine, i.e., A and B will refer to the same machine, and both ports will be local. Still, they are distinct ports.

For communication involving a large number of network nodes, or unreliable connections, we suggest 
using local UDP communication, in conjunction with locally executed TCP/IP server processes that forward messages to a TCP connection between the two remote machines.

==Description==
For each block of data processed by the BCI2000 system, two types of information are sent out
and may be received from the external application interface:
*the BCI2000 internal state as defined by the values of all [[BCI2000 Glossary#State|BCI2000 states]], and 
*the BCI2000 [[BCI2000 Glossary#Control Signal|control signal]].
 
Sending data occurs immediately after the task filter of the application module processes the data; 
receiving occurs immediately before the task filter.
This ensures that changes resulting from user choices are sent out immediately, and that 
received information will immediately be available to the task filter.
IP addresses and ports used are user-configurable. Sending and receiving may not use the same address and port.

==Protocol==
Messages consist of a name and a value, separated by white space
and terminated with a single newline (<code>'\n'==0x0a</code>) character.
Names may identify
*BCI2000 states by name -- then followed by an integer value in decimal ASCII representation;
*Signal elements in the form <tt>Signal(<channel>,<element>)</tt> -- then followed by a float value in decimal ASCII representation. Channel and element indices are given in zero-based form.

==Examples==
<pre>
Running 0\n
ResultCode 2\n
Signal(1,0) 1e-8\n
</pre>
Note that the first example will switch BCI2000 into a suspended state.
While the system is in that state, no communication is possible over the application protocol.

The meaning of control signal indices depends on the application module used. For the [[BCI2000 Glossary#Control Signal|control signal]] in a typical [[User Reference:CursorTask#Control_Signal|cursor task]], there are up to three channels holding a single element each, with channel indices 0, 1, and 2 corresponding to movement in X, Y, and Z direction, such that
 Signal(1,0) 1e-2\n
would indicate a value of 1e-2 for the control signal representing movement in Y direction.

==Parameterization from within BCI2000==
BCI2000 reads data from a local IP socket specified by the 
<tt>ConnectorInputAddress</tt> parameter, and writes data out into the socket specified by the 
<tt>ConnectorOutputAddress</tt> parameter.
Sockets are specified by an address/port combination.
Addresses may be host names, or numerical IP addresses. Address and port are separated by
a colon as in
<pre>
localhost:5000
134.2.103.151:20321
</pre>
For incoming values, messages are filtered by name using a list of allowed names 
present in the <tt>ConnectorInputFilter</tt> parameter. 
To allow signal messages, allowed signal elements must be specified including their
indices.
To allow all names, enter an asterisk (*) as the only list entry.

==Examples==
===BCI2000 example code===
* A simple few-line program that uses AppConnector information from BCI2000 to control the state of the parallel port is found at [https://{{SERVERNAME}}/tracproj/browser/trunk/src/contrib/AppConnectorApplications/ParallelSwitch/ParallelSwitch.cpp BCI2000/src/contrib/AppConnectorApplications/ParallelSwitch/].
* A GUI application that allows to interactively play with BCI2000 states is found at [https://{{SERVERNAME}}/tracproj/browser/trunk/src/contrib/AppConnectorApplications/AppConnectorExample BCI2000/src/contrib/AppConnectorApplications/AppConnectorExample].
* A MATLAB example is available at [https://{{SERVERNAME}}/tracproj/browser/trunk/src/contrib/AppConnectorApplications/readudp.m BCI2000/src/contrib/AppConnectorApplications/readudp.m].
* A minimal C++ program forwarding BCI2000 AppConnector messages to stdout (using the BCI2000 <code>sockstream</code> class) reads
<pre>
#include <iostream>
#include "SockStream.h"

using namespace std;

int main( int argc, char** argv )
{
  const char* address = "localhost:5000";
  if( argc > 1 )
    address = argv[ 1 ];

  receiving_udpsocket socket( address );
  sockstream connection( socket );
  string line;
  // Print each line of BCI2000 input to stdout.
  while( getline( connection, line ) )
    cout << line << endl;

  return 0;
}
</pre>
* ''Note:'' The above example program use BCI2000 socket stream utility classes contained in <tt>src/shared/utils/SockStream.cpp</tt>. You will need to add this file to your project to build the example program.

===An external application reading information from BCI2000, running locally===
* Set the <tt>ConnectorOutputAddress</tt> parameter to a local address above 1024, such as <code>localhost:5000</code>.
* In the external application, create a UDP socket and bind it to BCI2000's output port, i.e. <code>localhost:5000</code>. 
* Read from that socket as you would from a TCP socket.
===An external application reading information from BCI2000, running on a remote machine===
* Set the <tt>ConnectorOutputAddress</tt> parameter to a remote address with a port above 1024, such as <code>134.2.102.151:20321</code>.
* In the external program, create a UDP socket, and bind it to the remote machine's external address, i.e. <code>134.2.102.151:20321</code> rather than <code>localhost:20321</code>.
* Read from that socket as you would from a TCP socket.
===An external application sending information to BCI2000, running locally===
* Set the <tt>ConnectorInputAddress</tt> parameter to a local address with a port above 1024, such as <code>localhost:5001</code>.
* Set the <tt>ConnectorInputFilter</tt> to <code>*</code> (a single asterisk).
* In the external application, create a UDP socket and bind it to BCI2000's input port, i.e. <code>localhost:5001</code>.
* Write to that socket whenever appropriate, without waiting for a connection to be established.
===An external application sending information to BCI2000, running on a remote machine===
* Set the <tt>ConnectorInputAddress</tt> parameter to the local machine's external address, and a port above 1024, such as <code>bci2000machine.yourdomain.org:20320</code>.
* In the external program, create a UDP socket and bind it to the BCI2000 machine's external address, i.e. <code>bci2000machine.yourdomain.org:20320</code>.
* Write to that socket whenever appropriate, without waiting for a connection to be established.

==See also==
[[Technical Reference:System Design]], [[Technical Reference:State Definition]]

[[Category:External Interfaces]][[Category:User Application]]