Difference between revisions of "MatNIC Matlab Toolkit"

From Neuroelectric's Wiki
Jump to: navigation, search
(Created page with "== Controlling NIC with Matlab: the MatNIC toolkit == <!-- talk about the features of NIC being controlling (Enobio and StarStim) using a command-based protocol--> <!-- talk ...")
 
(Controlling NIC with Matlab: the MatNIC toolkit)
Line 5: Line 5:
  
 
NIC can be remotely commanded from a third-party software through a set of commands that can be sent using a TCP/IP connection. NIC listens to the '''TCP/IP port 1235''' for incoming connections. The clients that connect to that port can command the following actions:
 
NIC can be remotely commanded from a third-party software through a set of commands that can be sent using a TCP/IP connection. NIC listens to the '''TCP/IP port 1235''' for incoming connections. The clients that connect to that port can command the following actions:
  /-------------------------------------------------------------------------------------\
+
  /--------------------------------------------------\
  | Action               | Device            | Command code                            |
+
  | Action                       | Device            |
  |-------------------------------------------------------------------------------------|
+
  |--------------------------------------------------|
  | Start EEG streaming | Enobio & StarStim | [0xF0]                                  |
+
  | Start EEG streaming         | Enobio & StarStim |
  | Stop EEG streaming   | Enobio & StarStim | [0xF1]                                  |
+
  | Stop EEG streaming           | Enobio & StarStim |
  | Start Stimulation   | StarStim          | [0xFB]                                  |
+
  | Start Stimulation           | StarStim          |
  | Abort Stimulation   | StarStim          | [0xFA]                                  |
+
  | Abort Stimulation           | StarStim          |
  | Online Freq Change  | StarStim          | [0xF4][newFrequency]['\0','\n' or '\r'] |
+
| Online tACS Frequency Change | StarStim          |
  | Load template       | StarStim          | [0xF5][templateName]['\0','\n' or '\r'] |
+
  | Online tACS Amplitude change | StarStim          |
  \-------------------------------------------------------------------------------------/
+
  | Online tDCS Amplitude change | StarStim          |
** NOTE: Command parameters [templateName],[newFreqency] are ASCII Strings
+
  | Load template               | StarStim          |
 +
  | Request status              | Enobio & StarStim |
 +
  \--------------------------------------------------/
  
 
NIC responds to those commands with a set of status commands to indicate whether the commands are successfully processed, the stimulation is ready to be started and so on. The following table shows all the possible status value that NIC might send.
 
NIC responds to those commands with a set of status commands to indicate whether the commands are successfully processed, the stimulation is ready to be started and so on. The following table shows all the possible status value that NIC might send.
  
  /---------------------------------------------------------------------\
+
  /--------------------------------------------------------\
  | Status               | Device            | Status code              |
+
  | Status                             | Device            |
  |---------------------------------------------------------------------|
+
  |--------------------------------------------------------|
  | EEG streaming is ON | Enobio & StarStim | 0xF2                    |
+
| Remote control allowed            | Enobio & StarStim |
  | EEG streaming is OFF | Enobio & StarStim | 0xF3                    |  
+
| Remote control rejected            | Enobio & StarStim |
  | Template not loaded | StarStim          | 0xF9                    |
+
| Device is idle                    | Enobio & StarStim |
  | Stimulation is ready | StarStim          | 0xFC                    |
+
  | EEG streaming is ON               | Enobio & StarStim |
  | to be started       |                   |                          |
+
  | EEG streaming is OFF               | Enobio & StarStim |  
  | Stimulation is ON   | StarStim          | 0xFD                    |
+
  | Template not loaded               | StarStim          |
  | Stimulation is OFF   | StarStim          | 0xFE                    |
+
  | Template loaded                    | StarStim          |
  \---------------------------------------------------------------------/
+
  | Stimulation is ready to be started | StarStim          |
 +
  | Stimulation is ON                 | StarStim          |
 +
  | Stimulation is OFF                 | StarStim          |
 +
  \--------------------------------------------------------/
  
 
'''MatNIC''' (see our [http://www.neuroelectrics.com/support/download '''Downloads section'''] for more info on MatNIC) wraps all these commands and status code in a set of Matlab functions that allow remotely controlling NIC. The MatNIC zip file ([http://www.neuroelectrics.com/contact '''contact us'''] for more info) contains:
 
'''MatNIC''' (see our [http://www.neuroelectrics.com/support/download '''Downloads section'''] for more info on MatNIC) wraps all these commands and status code in a set of Matlab functions that allow remotely controlling NIC. The MatNIC zip file ([http://www.neuroelectrics.com/contact '''contact us'''] for more info) contains:
Line 41: Line 46:
 
  function [ret] = RemoteStimulationClient (templateName, host, port)
 
  function [ret] = RemoteStimulationClient (templateName, host, port)
 
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
  %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% RemoteStimulationClient
+
% RemoteStimulationClient
%
+
%
% This function implements a client to connect to the NIC Remote
+
% This function implements a client to connect to the NIC Remote
% Stimulation Server. The server is running on the machine where the NIC
+
% Stimulation Server. The server is running on the machine where the NIC
% application runs on the port 1235.
+
% application runs on the port 1235.
%
+
%
% The NIC Remote Server waits for the client to send the name of the  
+
% The NIC Remote Server waits for the client to send the name of the  
% template that the client wants to use. If the NIC user accepts the
+
% template that the client wants to use. If the NIC user accepts the
% remote control session, the template is loaded and the client is
+
% remote control session, the template is loaded and the client is
% informed when the system is ready to start the stimulation.
+
% informed when the system is ready to start the stimulation.
%
+
%
% The client then might send the code to start the stimulation or the one
+
% The client then might send the code to start the stimulation or the one
% to abort it. The abort command might be sent in any moment of the
+
% to abort it. The abort command might be sent in any moment of the
% stimulation session. If the stimulation session is aborted locally from
+
% stimulation session. If the stimulation session is aborted locally from
% the NIC GUI the connection is automatically closed so the client needs
+
% the NIC GUI the connection is automatically closed so the client needs
% to connect, send the template and wait again for the permission. When
+
% to connect, send the template and wait again for the permission. When
% the stimulation script execution is finished the system prepares itself
+
% the stimulation script execution is finished the system prepares itself
% to start again a new stimulation so the code informing about that is
+
% to start again a new stimulation so the code informing about that is
% received.
+
% received.
%
+
%
% The client might also send commands to start and stop receiving the EEG
+
% The client might also send commands to start and stop receiving the EEG
% streaming. The data is received through a separate server on the port
+
% streaming. The data is received through a separate server on the port
% 1234. The 8/20 channel samples are sent in 4 bytes in two's complement.
+
% 1234. The 8/20/32 channel samples are sent in 4 bytes in two's complement.
% The MSB byte is sent first.
+
% The MSB byte is sent first.
%
+
%
% The following are the functions to connect, send the commands to the
+
% The following are the functions to connect, send the commands to the
% server and read the status the server sends:
+
% server and read the status the server sends:
% - NICRemoteStimulationServerConnect
+
% - NICRemoteStimulationServerConnect
% - NICRemoteStimulationServerReadStatus
+
% - NICRemoteStimulationServerQueryStatus
% - NICRemoteStimulationServerLoadTemplate
+
% - NICRemoteStimulationServerLoadTemplate
% - NICRemoteStimulationServerOnlineFreqChange
+
% - NICRemoteStimulationServerStartStimulation
% - NICRemoteStimulationServerStartStimulation
+
% - NICRemoteStimulationServerAbortStimulation
% - NICRemoteStimulationServerAbortStimulation
+
% - NICRemoteStimulationServerStartEEG
% - NICRemoteStimulationServerStartEEG
+
% - NICRemoteStimulationServerStopEEG
% - NICRemoteStimulationServerStopEEG
+
% - NICRemoteStimulationServerOnlineAtacsChange
%
+
% - NICRemoteStimulationServerOnlineAtdcsChange
% The following are the status that the server might send to the client
+
% - NICRemoteStimulationServerOnlineFtacsChange
% and can be read with the NICRemoteStimulationServerReadStatus function:
+
%
%
+
%
% STATUS              |  TYPE        |      CODE
+
% Input:
% -------------------------------------------------------
+
% templateName: Name of the template to be loaded on NIC.
% EEG streaming is ON  |  Byte        |      0xF2
+
% host: Name or IP of the host where NIC is running.
% -------------------------------------------------------
+
%
% EEG streaming is OFF |  Byte        |      0xF3
+
% Output:
% -------------------------------------------------------
+
% ret: Zero or positive number if the function completes successfully. A
% Template not loaded  |  Byte        |      0xF8
+
% negative number otherwise:
% -------------------------------------------------------
+
% -1: The connection to the host and port number did not succeed.
% Template loaded      |  Byte        |      0xF9
+
% -2: Error writing template name.
% -------------------------------------------------------
+
% -3: Error reading from server.
% Stimulation is ready |  Byte        |      0xFC
+
% -4: Template not loaded.
%  to be started        |              |
+
% -5: Error writing command to the server.
% -------------------------------------------------------
+
%
% Stimulation is ON    |  Byte        |      0xFD
+
% Author: Javier Acedo (javier.acedo@starlab.es)
% -------------------------------------------------------
+
% Company: Neuroelectrics
% Stimulation is OFF  |  Byte        |      0xFE
+
% Created: 16 Jan 2013
% -------------------------------------------------------
+
% Known issues: None
%
+
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% Input:
 
% templateName: Name of the template to be loaded on NIC.
 
% host: Name or IP of the host where NIC is running.
 
% port: Port number where the NIC server runs.
 
%
 
% Output:
 
% ret: Zero or positive number if the function completes successfully. A
 
% negative number otherwise:
 
% -1: The connection to the host and port number did not succeed.
 
% -2: Error writing template name.
 
% -3: Error reading from server.
 
% -4: Template not loaded.
 
% -5: Error writing command to the server.
 
%
 
% Author: Javier Acedo (javier.acedo@starlab.es)
 
% Company: Neuroelectrics
 
% Created: 16 Jan 2013
 
% Known issues: None
 
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 

Revision as of 16:56, 18 December 2013

Controlling NIC with Matlab: the MatNIC toolkit

NIC can be remotely commanded from a third-party software through a set of commands that can be sent using a TCP/IP connection. NIC listens to the TCP/IP port 1235 for incoming connections. The clients that connect to that port can command the following actions:

/--------------------------------------------------\
| Action                       | Device            |
|--------------------------------------------------|
| Start EEG streaming          | Enobio & StarStim |
| Stop EEG streaming           | Enobio & StarStim |
| Start Stimulation            | StarStim          |
| Abort Stimulation            | StarStim          |
| Online tACS Frequency Change | StarStim          |
| Online tACS Amplitude change | StarStim          |
| Online tDCS Amplitude change | StarStim          |
| Load template                | StarStim          |
| Request status               | Enobio & StarStim |
\--------------------------------------------------/

NIC responds to those commands with a set of status commands to indicate whether the commands are successfully processed, the stimulation is ready to be started and so on. The following table shows all the possible status value that NIC might send.

/--------------------------------------------------------\
| Status                             | Device            |
|--------------------------------------------------------|
| Remote control allowed             | Enobio & StarStim |
| Remote control rejected            | Enobio & StarStim |
| Device is idle                     | Enobio & StarStim |
| EEG streaming is ON                | Enobio & StarStim |
| EEG streaming is OFF               | Enobio & StarStim | 
| Template not loaded                | StarStim          |
| Template loaded                    | StarStim          |
| Stimulation is ready to be started | StarStim          |
| Stimulation is ON                  | StarStim          |
| Stimulation is OFF                 | StarStim          |
\--------------------------------------------------------/

MatNIC (see our Downloads section for more info on MatNIC) wraps all these commands and status code in a set of Matlab functions that allow remotely controlling NIC. The MatNIC zip file (contact us for more info) contains:

- The MatNIC manual (also available in our Downloads Area), an explanation on how to use the Matlab functions to remotely control NIC and
- RemoteStimulatioClient, a folder with all the Matlab functions for remotely controlling NIC, and an example on how to use them.

To run the example please make the following call:

>> ret = RemoteStimulationClient (templateName, '127.0.0.1', 1235)

where templaName is set with a name of an already defined stimulation template NIC, then the host where NIC is running (in the example above we use the localhost IP, so NIC is running in the same computer) and finally the port 1235 which is where the NIC server runs. Here is the header of the example client code:

function [ret] = RemoteStimulationClient (templateName, host, port)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

% RemoteStimulationClient % % This function implements a client to connect to the NIC Remote % Stimulation Server. The server is running on the machine where the NIC % application runs on the port 1235. % % The NIC Remote Server waits for the client to send the name of the % template that the client wants to use. If the NIC user accepts the % remote control session, the template is loaded and the client is % informed when the system is ready to start the stimulation. % % The client then might send the code to start the stimulation or the one % to abort it. The abort command might be sent in any moment of the % stimulation session. If the stimulation session is aborted locally from % the NIC GUI the connection is automatically closed so the client needs % to connect, send the template and wait again for the permission. When % the stimulation script execution is finished the system prepares itself % to start again a new stimulation so the code informing about that is % received. % % The client might also send commands to start and stop receiving the EEG % streaming. The data is received through a separate server on the port % 1234. The 8/20/32 channel samples are sent in 4 bytes in two's complement. % The MSB byte is sent first. % % The following are the functions to connect, send the commands to the % server and read the status the server sends: % - NICRemoteStimulationServerConnect % - NICRemoteStimulationServerQueryStatus % - NICRemoteStimulationServerLoadTemplate % - NICRemoteStimulationServerStartStimulation % - NICRemoteStimulationServerAbortStimulation % - NICRemoteStimulationServerStartEEG % - NICRemoteStimulationServerStopEEG % - NICRemoteStimulationServerOnlineAtacsChange % - NICRemoteStimulationServerOnlineAtdcsChange % - NICRemoteStimulationServerOnlineFtacsChange % % % Input: % templateName: Name of the template to be loaded on NIC. % host: Name or IP of the host where NIC is running. % % Output: % ret: Zero or positive number if the function completes successfully. A % negative number otherwise: % -1: The connection to the host and port number did not succeed. % -2: Error writing template name. % -3: Error reading from server. % -4: Template not loaded. % -5: Error writing command to the server. % % Author: Javier Acedo (javier.acedo@starlab.es) % Company: Neuroelectrics % Created: 16 Jan 2013 % Known issues: None %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%