Added RCS 'select all' and 'select none' commands. Updated README

Author: cboulay

README.md

@@ -5,31 +5,37 @@
 
 The LabRecorder is the default recording program that comes with LSL. It allows to record all streams on the lab network (or a subset) into a single file, with time synchronization between streams.
 
+[Download it from the Releases page](https://github.com/labstreaminglayer/App-LabRecorder/releases).
+
 # File Format
 
-The file format used by the LabRecorder is XDF. This is a new open general-purpose format that was designed concurrently with LSL and supports all features of LSL streams. The project page is [here](https://github.com/sccn/xdf). There are importers for MATLAB (included with the distribution), EEGLAB, BCILAB, Python, and MoBILAB (available separately on the Downloads page).
+The file format used by the LabRecorder is XDF. This is an open general-purpose format that was designed concurrently with LSL and supports all features of LSL streams. The project page is [here](https://github.com/sccn/xdf). There are importers for MATLAB, EEGLAB, BCILAB, Python, and MoBILAB.
 
 # Getting LabRecorder
 
 Navigate to the [`releases` page](https://github.com/labstreaminglayer/App-LabRecorder/releases) and download the latest release for your platform.
 
 # Usage
 
-The LabRecorder displays a list of currently present device streams under "Record from Streams". If you have turned on a device after you have already started the recorder, click the "Refresh" button to update the list (this takes ca. 2 seconds). For testing there are several simple dummy devices in the [examples folder](https://github.com/labstreaminglayer/App-Examples) (for example SendData<!--, SendStringMarkers, and SendDataSimple-->); you can start any of these programs (and follow the on-screen instructions, if any) to bring a stream online. After you have done so, clicking refresh in the recorder should display the streams in green. If you cannot see streams that are provided on another computer, read the section Network Troubleshooting on the NetworkConnectivity page. You can select which streams you want to record from and which not by checking the check boxes next to them. By default any present stream will be initially checked, as in the follwing picture.
+The LabRecorder displays a list of currently present device streams under "Record from Streams". If you have turned on a device after you have already started the recorder, click the "Update" button to update the list (this takes ca. 2 seconds).
+> For testing you can use a "dummy" device from the `lslexamples` found in the [liblsl release assets](https://github.com/sccn/liblsl/releases) (for example SendData<!--, SendStringMarkers, and SendDataSimple-->).
+
+If you cannot see streams that are provided on another computer, read the section Network Troubleshooting on the NetworkConnectivity page. You can select which streams you want to record from and which not by checking the check boxes next to them.
 > ![labrecorder-default.png](doc/labrecorder-default.png)
 
-The entry in "Storage Location" shows you the file name (or file name template) where your recording will be stored. You can change this by clicking the browse button. If this string contains any occurrence of the placeholder `%n`, it will be replaced by the value in the "Experiment Number" field. The value in that field is "smart": when you start the recorder or load a configuration file, this field will be set automatically to the lowest number for which no directory exists yet on disk. If the string contains any occurrence of `%b`, it will be substituted by the the selected string under "Current experiment block". This list of pre-defined block names is feature for advanced uses that can be customized by editing the `default_config.cfg` configuration file (or creating a new one). If the respective directory does not yet exist, it will be created automatically (except if you do not have the permissions to create it). If the file that you are trying to record to already exists, the existing file will be renamed (the string `_oldX` will be appended where X is the lowest number that is not yet occupied by another existing file). This way, it is impossible to accidentally overwrite data.
+The entry in "Saving to..." shows you the file name (or file name template) where your recording will be stored. You can change this by modifying the Study Root folder (e.g., by clicking the browse button) and the `File Name / Template` field. If the respective directory does not yet exist, it will be created automatically (except if you do not have the permissions to create it). The file name string may contain placeholders that will be replaced by the values in the fields below. Checking the BIDS box will automatically change the filename template to be BIDS compliant. If the file that you are trying to record to already exists, the existing file will be renamed (the string `_oldX` will be appended where X is the lowest number that is not yet occupied by another existing file). This way, it is impossible to accidentally overwrite data.
+
+The Block/Task field can be overwriten or selected among a list of items found in the configuration file.
 
 <!--If the checkbox "Enable scripted actions" is checked, then scripted actions that are defined in your current config file will be automatically invoked when you click Start, Stop, or select a block. This check box is by normally unchecked unless you have custom-tailored a configuration to your experiment or experimentation environment.-->
 
-Click "Start" to start a recording. If everything goes well, the status bar will now display the time since you started the recording, and more importantly, the current file size (the number before the kb) will grow slowly. This is a way to check whether you are still in fact recording data. The recording program cannot be closed while you are recording (as a safety measure). This looks like in the following picture.
-> ![labrecorder-running.png](doc/labrecorder-running.png)
+Click "Start" to start a recording. If everything goes well, the status bar will now display the time since you started the recording, and more importantly, the current file size (the number before the kb) will grow slowly. This is a way to check whether you are still in fact recording data. The recording program cannot be closed while you are recording (as a safety measure).
 
-When you are done recording, click the "Stop" button. You can now close the program. You can now import and inspect your recording, see for example ImportingRecordingsInMatlab.
+When you are done recording, click the "Stop" button. You can now close the program. See [the xdf repository](https://github.com/sccn/xdf) for tools and information on how to use the XDF files.
 
-# Preparing a Full Study
+## Preparing a Full Study
 
-When preparing a new study, it is a good idea to make a custom configuration file which at least sets up a custom storage location for the study. See the documentation in the file `default_config.cfg` for how to do this -- it is very easy! <!--The file `sample_config.cfg` contains a somewhat more advanced setup for reference. By default, the file `default_config.cfg` is loaded at startup.--> You can override this by making a shortcut for the LabRecorder program (e.g. on the desktop) and appending in its properties the command-line arguments `-c name_of_you_config.cfg`. You can also create a batch script. You can also load the config while the program is already running, but this can easily be forgotten during an experiment, so we recommend to follow the shortcut route.
+When preparing a new study, it is a good idea to make a custom configuration file which at least sets up a custom storage location for the study. See the documentation in the file `LabRecorder.cfg` for how to do this -- it is very easy! <!--The file `sample_config.cfg` contains a somewhat more advanced setup for reference. By default, the file `default_config.cfg` is loaded at startup.--> You can override this by making a shortcut for the LabRecorder program (e.g. on the desktop) and appending in its properties the command-line arguments `-c name_of_you_config.cfg`. You can also create a batch script. You can also load the config while the program is already running, but this can easily be forgotten during an experiment, so we recommend to follow the shortcut route.
 
 In addition to the storage location, if your experiment has multiple blocks (e.g., SubjectTraining, PreBaseline, MainBlock, PostBaseline or the like) you can make the recording process even more straightforward for the experimenters by setting up a default list of block names. Again, take a look at the existing config files.
 
@@ -40,7 +46,50 @@ Since it is too easy to forget to turn on or check all necessary recording devic
 <!--The following picture shows the the recorder fully configured for a particular study. The BioSemi device is displayed in red because it is not yet turned on. The file naming scheme is customized, and there are four blocks pre-configured with associated scripted actions.
 > ![labrecorder-study.png](labrecorder-study.png)-->
 
-# Misc Features
+## Remote Control
+
+If you check the box to EnableRCS then LabRecorder exposes some rudimentary controls via TCP socket.
+
+Currently supported commands include:
+* `select all`
+* `select none`
+* `start`
+* `stop`
+* `filename ...`
+
+`filename` is followed by a series of space-delimited options enclosed in curly braces. e.g. {root:C:\root_data_dir}
+* `root` - Sets the root data directory.
+* `template` - sets the File Name / Template. Will unselect BIDS option. May contain wildcards.
+* `task` - will replace %b in template
+* `run` - will replace %n in template (not working?)
+* `participant` - will replace %p in template
+* `session` - will replace %s in template
+* `acquisition` - will replace %a in template
+* `modality` - will replace %m in template. suggested values: eeg, ieeg, meg, beh
+
+
+For example, in Python:
+
+```python
+import socket
+s = socket.create_connection(("localhost", 22345))
+s.sendall(b"select all\n")
+s.sendall(b"filename {root:C:\\Data\\} {template:exp%n\\%p_block_%b.xdf} {run:2} {participant:P003} {task:MemoryGuided}\n")
+s.sendall(b"start\n")
+```
+
+```Matlab
+lr = tcpip('localhost', 22345); 
+fopen(lr)
+fprintf(lr, 'select all');
+fprintf(lr, ['filename {root:C:\Data\} '...
+            '{task:MemoryGuided} ' ...
+            '{template:s_%p_%n.xdf ' ...
+            '{modality:ieeg}']); 
+fprintf(lr, 'start');
+```
+
+## Misc Features
 
 The LabRecorder has some useful features that can add robustness if things go wrong during the experiment:
 
@@ -52,4 +101,6 @@ You should check the health of your device to be sure, however, for example usin
 
 If a device is displayed in red when you start recording (and it is checked), it will be added to the ongoing recording by the time when it comes online. This can be useful when a device can only be turned on while the recording is already in progress. Again, it is advisable to check that the device is in fact discoverable and added. The LabRecorder brings up a console window in the background which shows a list of all streams that are added to the recording -- this is a good place to check whether a late stream did get picked up successfully during a live recording.
 
-# [Build instructions](BUILD.md)
+# Build Instructions
+
+Please follow the general [LSL App build instructions](https://labstreaminglayer.readthedocs.io/dev/app_build.html).

doc/labrecorder-default.png

@@ -544,6 +544,8 @@ void MainWindow::enableRcs(bool bEnable) {
 		connect(rcs.get(), &RemoteControlSocket::start, this, &MainWindow::rcsStartRecording);
 		connect(rcs.get(), &RemoteControlSocket::stop, this, &MainWindow::stopRecording);
 		connect(rcs.get(), &RemoteControlSocket::filename, this, &MainWindow::rcsUpdateFilename);
+		connect(rcs.get(), &RemoteControlSocket::select_all, this, &MainWindow::selectAllStreams);
+		connect(rcs.get(), &RemoteControlSocket::select_none, this, &MainWindow::selectNoStreams);
 	}
 	bool oldState = ui->rcsCheckBox->blockSignals(true);
 	ui->rcsCheckBox->setChecked(bEnable);

src/mainwindow.cpp

@@ -26,6 +26,12 @@ void RemoteControlSocket::handleLine(QString s, QTcpSocket *sock) {
 		emit stop();
 	else if (s.contains("filename")) {
 		emit filename(s);
+	} else if (s.contains("select")) {
+		if (s.contains("all")) {
+			emit select_all();
+		} else if (s.contains("none")) {
+			emit select_none();
+		}
 	}
 	sock->write("OK");
 	// TODO: select /deselect streams

src/tcpinterface.cpp

@@ -18,6 +18,8 @@ class RemoteControlSocket : public QObject {
 	void start();
 	void stop();
 	void filename(QString s);
+	void select_all();
+	void select_none();
 
 public slots:
 	void addClient();