OTHER PAGES IN THIS SECTION:
ScannerSync command reference
Contents
Contents
-
ScannerSync command reference
- Initialising and terminating the communication with the board
- Generally useful
-
Synchronisation with board
- Function CheckPulseSynchrony()
- Function StartExperiment(TR As Double) As Integer
- Function SynchroniseExperiment(booActuallyWaitForPulse As Boolean, dblDelay As Double)
- Function SynchroniseExperimentToPulseNumber (booActuallyWaitForPulse As Boolean, intPulseNumber As Integer, dblDelay As Double) As Integer
- Function CheckPulseSynchronyForTime(dblTimeToWait As Double) As Integer
- Multi-tasking routines
- Scanner Spy
- Getting information about what's happening
- Options
- Routines available that you shouldn't normally need
-
ScannerSync command reference
Initialising and terminating the communication with the board
Function Initialize(strConfig As String) as Integer
Gets the system ready.
Parameters:
strConfig You no longer need this configuration file - just specify ""
Returns:
0 if no error
Keithly error code otherwise
Possible errors and causes:
Board in use. If you haven't called the Terminate command at the end of running a program, you'll get an error when you start the program again. If this happens, just close the program entirely (e.g., quit the VB editor if you're using it) and start it again. This will release the drivers.
DASSHL32.DLL not found. You're using a computer without the Keithly drivers installed.
Example [[BR]] If (objSS.Initialize("")<>0) Then End
Sub Terminate
Calling this routine is no longer necessary - the board communication is terminated when the ScannerSync object is destroyed.
Generally useful
Sub SetPretendMode(booEmulateScannerPulse As Boolean)
Call this routine INSTEAD of calling Initialize command. The routines will give a warning, and wait for a keyboard press to start the experiment. They'll then pretend they are hearing pulses from the scanner at a rate a little below the TR, and ask for keyboard responses instead of using the response box.
Example [[BR]] Change... [[BR]] If (objSS.Initialize("")<>0) Then End [[BR]] to... [[BR]] objSS.SetPretendMode True
Sub SetPretendModeExtended(booEmulateScannerPulse As Boolean, booEmulateResponses As Boolean)
Similar to SetPretendMode, but allows you to separately choose whether the routines emulate pulses from the scanner and whether they emulate the response box.
If you have either as false (e.g., not pretend mode) you'll need to keep the objSS.Initialize command.
Example objSS.Initialize("") ' You still need the initialise if you want to use the button box. objSS.SetPretendModeExtended(true,false) 'Pretend only pulses, not responses Do Debug.Print objSS.GetResponse DoEvents Loop
Function GetVersion() As String
This routine Returns: the version of the ScannerSync installed, currently 1.0.2
Example MsgBox "Current ScannerSync version is " & ObjSS.GetVersion
Synchronisation with board
Function CheckPulseSynchrony()
Waits for a pulse. It then measures its time precisely. From the previously supplied rough estimate of the TR, the routine works out the number of the pulse that has just arrived. It then uses the exact time to work out the true TR.
This routine can be called at any point in your code, with any degree of regularity/irregularity. You choose when! The only constraint is that it should be at least 30 secs - 1 minute or so as discussed in the introduction.
Function StartExperiment(TR As Double) As Integer
This starts the clock. You should do this once per block (run of acquisitions). If no pulse is received within the timeout period (default 20s; set using SetTimeout command) then an error is returned.
For accuracy, this command should be executed at a high thread priority (see example).
Parameters:
TR The time between pulses that you've asked for in milliseconds.
Returns:
0 if there has been no error
non zero otherwise
Example [[BR]] objSS.StartExperiment 3000 [[BR]]
Function SynchroniseExperiment(booActuallyWaitForPulse As Boolean, dblDelay As Double)
Sychronises the execution of your program (trial presentation) with the scanner. You can choose whether you actually wish to wait for a pulse or not.
Parameters:
dblDelay Time in ms after the pulse that you wish the routine to return.
plain:booActuallyWaitForPulse If True, then actually wait for a scanner pulse to come in. If False, then allow use of calculated scanner pulse time. The advantage of the latter is that if a pulse has just happened (say 0.5 s ago) and you want a delay of 2s, then the routine will return in 1.5s. If you insist on waiting for a pulse, then at TR=3 it will be 2.5s before this comes in, and then you'll have to wait for 2s giving a total delay of 4.5s.
Returns:
0 if there has been no error
non zero otherwise.
Function SynchroniseExperimentToPulseNumber (booActuallyWaitForPulse As Boolean, intPulseNumber As Integer, dblDelay As Double) As Integer
As synchroniseExperiment, but waits for a particular pulse number. If the pulse has already occurred then:
if booActuallyWaitForPulse=True the routine will return straight away (without delay);
if booActuallyWaitForPulse=False then the routine will return straight away if the desired time has passed, or at the appropriate time if it has not.
Function CheckPulseSynchronyForTime(dblTimeToWait As Double) As Integer
Waits for dblTimeToWait and records any scanner pulse(s). It will not return before this time has expired even if a pulse is found earlier. It will return at this time, even if a pulse has not been found.
If you wish to design an experiment, but can only spend short periods listening for a pulse, then just work out how many pulses you'll catch on average by looking at the proportion of the TR that you're listening. So, for example, if you listen using this routine for 600ms using
objSS.CheckPulseSynchronyForTime 600
then with a TR of 3000ms you'll catch a pulse on average 600/3000=0.2=20% of looks.
Multi-tasking routines
'Expert only!
Multi-tasking versions of all of the routines are implemented. These are identical to StartExperiment, SynchroniseExperiment etc., but can safely be interrupted. A quality control system ensures that only truely reliable measurements of scanner pulse are accounted for. The commands are the same as their non-interruptable counterparts described above, but have an additional sngRequiredConfidence parameter. This parameter describes the accuracy, in ms, that a measurement must have to be taken as a reliable timing measurement. If the routines are interrupted, and cannot guarantee their timing to this accuracy, then an error value (-1) is returned, and the measurement does not contribute to estimates of the TR etc.
Function WaitForPulse_Interruptable(ByRef dblPulseTime s Double, sngRequiredConfidence As Single) As Integer
Function StartExperiment_Interruptable(dblTR As Double, sngRequiredConfidence As Single) As Integer
Function CheckPulseSynchrony_Interruptable(sngRequiredConfidence As Single) As Integer
Scanner Spy
'This program runs in the background with a very low thread priority, listening to scanner pulses when it can and recording information about them. It uses the multi-tasking routines mentioned above, and can safely be interrupted, with poor timing measurements being discarded.
Getting information about what's happening
Function GetMeasuredTR() As Double
Get the TR as estimated from all of the actual pulses measured in the experiment.
Function GetLastPulseTime(booLastActualMeasurement As Boolean) As Double
If booLastActualMeasurement=True then the routine Returns: the time in ms of the last pulse to be actually measured. However, this routine does not actually wait for a pulse whatever the flag settings. If it is False, then the routine Returns: the calculated last pulse time.
Function GetLastPulseNum(booLastActualMeasurement As Boolean) As Double
If booLastActualMeasurement=True then the routine Returns: the number of the last pulse to be actually measured. However, this routine does not actually wait for a pulse whatever the flag settings. If it is False, then the routine Returns: the calculated last pulse number.
Function GetResponse() As Integer
Find out what keys are pressed on the button box plugged into the Keithly Board. The value will be 2, 4, 8, or 16 depending on which button is pressed. If more than one button is pressed, then these values add together.
To find out if a particular key is pressed, use the keyword AND as in the example.
From what I understand, there are two button boxes that plug into the Keithly Board - a left handed and a right handed one. I don't know which way the buttons are wired up. You need to find someone who knows this or work it out. Please then email the vbsupport list with the answer!
Example [[BR]] If (Not(objSS.GetResponse() And 4)) Then Debug.Print "Button 2 was pressed"
Function GetResponseExtended(intNumButtons as Integer) As Integer
As GetResponse except supports more than 4 buttons. Specify the number of buttons in the parameter intNumButtons and the return value will be masked appropriately.
Example If (Not(objSS.GetResponseExtended(7) And 64)) Then Debug.Print "Button 6 was pressed"
Options
Function SetTimeout(dblTimeOutPeriod As Double)
Sets the time after which the routines will give up looking for a pulse - usually 20 seconds. dblTimeOutPeriod is in milliseconds.
Function ShowErrnums(booShowErrors As Boolean)
If you set this to true, then an error message will be display if there are unusual, large changes in the TR estimate. This might be useful while debugging but don't use it when you are scanning -just better to let the experiment take its course.
Function SetMSPerSample(dblMSPerSample As Double)
There is a bug in Matlab which means that while waiting in the StartExperiment routine a large amount of memory is consumed. After around 20 secs, this memory leak leads to the board drivers refusing to function. As a workaround, you may reduce the sample rate which slows the memory leak so that the routine doesn't crash out. We would recommend something like
Example objSS.SetMSPerSample 2
Thanks to Tom Morey for helping with this one.
Routines available that you shouldn't normally need
Function WaitForPulse(ByRef dblPulseTime As Double) As Integer
Used internally by SynchroniseExperiment - use this instead.
Function GetTimeOfPulsePriorTo(dblMyTime As Double) As Double
Gives you the calculated time of the pulse prior to the specified time.
Function ReadPIOValue() As Integer
Reads from Keithly board- used internally.