ScanImage-WaveSurfer Integration v2

This document describes how to set up intercommunication ("yoking") between ScanImage (SI) and WaveSurfer (WS), for versions of SI and WS that support version 2 of the SI-WS communication protocol. WS support for the version 2 protocol was added in WS 0.95. SI support for the version 2 protocol was added in SI 2017a. When using SI and WS together, both have to be using the same version of the SI-WS communication protocol.

For a description of how things worked under version 1 of the SI-WS communication protocol, see, for example, the relevant section of the WaveSurfer 0.945 manual.

The documentation below assumes you're using ScanImage 2017b and WaveSurfer 0.97, but other versions that both support version 2 of the SI-WS communication protocol should work similarly.

Some notes on terminology: In WaveSurfer, a "sweep" is a single acquisition for (typically) a fixed duration. A WaveSurfer sweep is analogous to a ScanImage acquisition. In WaveSurfer, a "run" is a series of sweeps, one after the other, with gaps in between. A WaveSurfer run is analogous to a ScanImage loop.

What yoking does

When ScanImage and WaveSurfer are yoked together, several aspects of their behavior are coordinated. In particular:

  1. When you start a run in WaveSurfer, it automatically starts a loop in ScanImage. If data files are being recorded, ScanImage is instructed to save its data files in the same folder as WaveSurfer, with a similar data file name.
  2. Similarly, when you stop a run in WaveSurfer using the stop button, it automatically stops the ongoing loop in ScanImage.
  3. If an error causes the WaveSurfer run to end prematurely, ScanImage is notified of this and will also stop the ongoing loop.
  4. At the start of the run, WaveSurfer communicates the data file name to ScanImage, and the first sweep index. ScanImage then uses the same directory, base file name, and sweep/acquisition index when saving its own data files.
  5. When the protocol file is saved in WS, a message is sent to SI to save its protocol file in the same folder. The SI configuration file will have a name that is "parallel" to the WS protocol file name. In particular, the SI configuration file will be in the same folder as the WS protocol file, and will have the same name except that the SI configuration file will have an extension of .cfg rather than .wsp.
  6. When a protocol file is loaded in WS, a message is sent to SI to load the parallel configuration file.
  7. When the user settings file is saved in WS, a message is sent to SI to save its user settings file. The SI user settings file will have a name that is "parallel" to the WS user settings file name. In particular, the SI user settings file will be in the same folder as the WS user settings file, and will have the same name except that the SI user settings file will have an extension of .usr rather than .wsu.
  8. When a user settings file is loaded in WS, a message is sent to SI to load the parallel SI user settings file.
  9. All of the above actions are reciprocal: If you initiate one of them in ScanImage, SI will instruct WS to initiate the parallel operation.

How to set up yoking

  1. Start Matlab and run ScanImage.
  2. Set up ScanImage for external triggering:
    1. Go to the "Settings" menu on ScanImage.
    2. Select the "Triggers" menu entry.
    3. Choose the desired Terminal and Edge type for "Acquisition Start". Physically connect the indicated terminal on the ScanImage DAQ board to whatever line signals sweep starts to WaveSurfer. If WaveSurfer is using its builtin trigger (the default), connect the ScanImage terminal to PFI8 on the WaveSurfer DAQ board.
    4. On the "Main Controls" window, select the "EXT" button to turn on external triggering.
  3. Start a new instance of Matlab and run WaveSurfer.
  4. Ensure that you are using WaveSurfer in sweep-based acquisition mode, and that the duration of the WaveSurfer sweeps is at least one second longer than the SI acquisitions. This gives SI time to ready itself at the end of each acquisition. Otherwise, SI may not be ready when the next trigger from WaveSurfer (or wherever) occurs.
  5. Go to the "Settings" menu in ScanImage and click on the entry "Yoke WaveSurfer". A check mark should become visible next to the menu entry.
  6. WaveSurfer should automatically detect that yoking has been turned on. In the WaveSurfer "Protocol" menu, a check mark should be visible next to the "Yoked to ScanImage" menu entry.
  7. ScanImage and WaveSurfer are now yoked. Pressing the play or record buttons in WaveSurfer should now start a loop in ScanImage, and pressing the loop button in ScanImage should start a run in WaveSurfer.

How to turn off yoking

  1. Go to the "Settings" menu in ScanImage and click on the entry "Yoke WaveSurfer". The check mark next to the menu entry should go away.
  2. WaveSurfer should automatically detect that yoking has been turned off. In the WaveSurfer "Protocol" menu, there should be no check mark next to the "Yoked to ScanImage" menu entry.
  3. ScanImage and WaveSurfer will now operate independently.

Yoking when ScanImage and WaveSurfer are running on different computers

This is not officially supported, but if you must: WaveSurfer and ScanImage communicate via text files written to the current temporary directory, as returned by Matlab's tempdir() function. If ScanImage and WaveSurfer are on different computers but share a network folder, it is possible for them to interact if you tell them both to use the network folder for communication.

In ScanImage, if your shared network folder is Z:/my-network-folder, you can do this by entering the following command on the Matlab command line: 

    hSI.hWSConnector.communicationDir = 'Z:/my-network-folder' ;
where hSI is a handle to the ScanImage object.

In WaveSurfer, you can do this by changing the file +ws/commandFilePaths.m in the WaveSurfer folder, which normally looks like this: 

    CommunicationFolderName_ = tempdir() ;
Again, if your your shared network folder was Z:/my-network-folder, you would change line 3 to read: 
    CommunicationFolderName_ = 'Z:/my-network-folder'  ;

updated February 8, 2018