Help.txt

========
SYNOPSIS
========

The @SpikeGL API class is a MATLAB object with methods to access the SpikeGLX program via TCP/IP. On top of that, our message exchange protocol implements acknowledgement, validation and error reporting. SpikeGLX and MATLAB can run on the same machine (via loopback socket address 127.0.0.1) or across a network.

The API provides extensive control over a running SpikeGLX process: starting and stopping a run, setting parameters, fetching live data, calling the Par2 and SHA1 tools, and so on. Everything you need to integate SpikeGLX into your workflow.

Users (clients) of this class merely need to construct an instance of a @SpikeGL object and all network communication with the SpikeGLX server process is handled automatically.

The network socket handle is used with the 'CalinsNetMex' mexFunction, which is a helper mexFunction that does all the actual socket communications for this class.

Instances of @SpikeGL are weakly stateful: merely keeping a handle to a network socket. It is ok for MATLAB to create and destroy several of these objects. Each network connection cleans up after itself on the server side after 10 seconds of inactivity. By the way, if your script has paused longer than 10 seconds, and you reuse a handle that has timed out, the handle will automatically reestablish a connection and the script will likely continue without problems, but a warning will appear in the Command Window reflecting the timeout. Such warnings have a warningid, so you can suppress them by typing >> warning( 'off', 'CalinsNetMex:connectionClosed' ).

========
EXAMPLES
========

my_s = SpikeGL; // connect to SpikeGLX running on local machine

prms = GetParams( my_s ); // optionally retrieve run params as struct

SetParams( my_s, struct('niMNChans1','0:5','niDualDevMode','false',...) ); // make changes

StartRun( my_s ); // start data acquisition run using last-set params

StopRun( my_s );  // stop run and clean up

========
(js, ip)
========

The two integer values (js, ip) select a data stream.
js: stream type: {0=nidq, 1=obx, 2=imec-probe}.
ip: substream:   {0=nidq (if js=0), 0+=which OneBox or imec probe}.
Examples (js, ip):
(0, 0) = nidq.	// for nidq, ip is arbitrary but zero by convention
(1, 4) = obx4.
(2, 7) = imec7.
Note: ip has range [0..np-1], where, np is queried using GetStreamNP().

=======================
GetParams and SetParams
=======================

Manual Pre-validation
=====================

You'll find that several of the API functions to get or set run parameters complain if you haven't validated any parameters yet. To validate parameters, visit the Configure dialog in SpikeGLX and make choices for your experiment, then click either 'Run' or 'Verify|Save'. Either of these buttons apply a battery of self-consistency checks to your choices. The most recent set of Configuration settings that have passed all the sanity checks are saved in:

- 'SpikeGLX/_Configs/daq.ini'
- 'SpikeGLX/_Calibration/imec_probe_settings.ini'
- 'SpikeGLX/_Calibration/imec_onebox_settings.ini'.

The above ini files are used to initialize the Configure dialog each time you open it. Open the ini files in a text editor. You'll see several subgroups of settings. This is the best way to see the exact spelling, case, and value type of the items you can read and write via the API. Examples of accessing the subgroups:

- Group [DAQSettings]:                GetParams()
- Group [DAQ_Imec_All]:               GetParamsImecCommon()
- Group [SerialNumberToProbe]/SNjjj:  GetParamsImecProbe()
- Group [SerialNumberToOneBox]/SNjjj: GetParamsOneBox()

Generally, follow this workflow:

(1) Start SpikeGLX and make sure its Command Server is listening (you'll see a message to that effect in the Console/Log window).

(2) Open the Configure dialog to elect which hardware streams you want to run.

(3) Click 'Detect' and then 'Verify|Save'.

Now you are ready to run from MATLAB.

(4) Typically you will need to adjust just a few settings from within your script.