Merge pull request #2 from Remi-Gau/remi-change_keyboard_defaults

change to keyboards function and defaults

Author: Remi-Gau

.travis.yml

@@ -0,0 +1,25 @@
+# Travis CI (https://travis-ci.org/)
+
+language: c
+dist: bionic
+cache:
+  apt: true # only works with Pro version
+
+env:
+  global:
+    - OCTFLAGS="--no-gui --no-window-system --silent"
+
+before_install:
+  - travis_retry sudo apt-get -y -qq update
+  - travis_retry sudo apt-get -y install octave
+  - travis_retry sudo apt-get -y install liboctave-dev
+
+install:
+  - octave $OCTFLAGS --eval "addpath (pwd); savepath ();"
+
+before_script:
+  # Change current directory
+  - cd tests
+
+script:
+  - octave $OCTFLAGS --eval "results = runtests; assert(all(~[results.Failed]))"

README.md

@@ -70,6 +70,30 @@ You can then use the [matlab package manager](https://github.com/mobeets/mpm), t
   end
 ```
 
+## Setting up keyboards
+
+To select a specific keyboard to be used by the experimenter or the participant, you need to know
+the value assigned by PTB to each keyboard device.
+
+To know this copy-paste this on the command window:
+
+``` matlab
+[keyboardNumbers, keyboardNames] = GetKeyboardIndices;
+
+disp(keyboardNumbers);
+disp(keyboardNames);
+```
+
+You can then assign a specific device number to the main keyboard or the response box in the `cfg` structure
+
+-   `cfg.keyboard.responseBox` would be the device number of the device used by the participant to give his/her
+response: like the button box in the scanner or a separate keyboard for a behavioral experiment
+-   `cfg.keyboard.keyboard` would be the device number of the keyboard on which the experimenter will type or
+press the keys necessary to start or abort the experiment.
+
+`cfg.keyboard.responseBox` and `cfg.keyboard.keyboard` can be different or the same.
+
+Using empty vectors (ie `[]`) or a negative value for those means that you will let PTB find and use the default device.
 
 ## Structure and function details
 
@@ -106,23 +130,27 @@ It is wrapper function to use `KbQueue` which is definitely what you should used
 
 You can easily collect responses while running some other code at the same time.
 
-It will only take responses from the `response box` which can simply be the "main keyboard" or
-another keyboard connected to the computer or the response box that the participant is using.
+It will only take responses from one device which can simply be the "main keyboard" 
+(the default device that PTB will find) or another keyboard connected to the computer 
+or the response box that the participant is using.
 
 You can use it in a way so that it only takes responses from certain keys and ignore others (like
 the triggers from an MRI scanner).
 
 If you want to know more on how to use it check its help section and the `CPP_getResponseDemo.m`.
 
-To select a specific keyboard to be used by the experimenter or the participant, you need to know
-the value assigned by PTB to each keyboard device.
+In brief, there are several actions you can execute with this function.
 
-To know this copy-paste this on the command window:
+-   init: initialize the buffer for key presses on a given device (you can also specify the keys of interest that should be listened to).
+-   start: start listening to the key presses (carefully insert into your script - where do you want to start buffering the responses).
+-   check: till that point, it will check the buffer for all key presses. 
+    -   It only reports presses on the keys of interest mentioned at initialization.
+    -   It **can** also check for presses on the escape key and abort if the escape key is part of the keys of interest.
+-   flush: Empties the buffer of key presses in case you want to discard any previous key presses.
+-   stop: Stops buffering key presses. You can still restart by calling "start" again.
+-   release: Closes the buffer for good.
 
-    [keyboardNumbers, keyboardNames] = GetKeyboardIndices;
 
-    keyboardNumbers
-    keyboardNames
 
 ### deg2Pix
 

checkAbort.m

@@ -1,16 +1,35 @@
-function checkAbort(cfg)
+function checkAbort(cfg, deviceNumber)
 % Check for experiment abortion from operator
+% When no deviceNumber is set then it will check the default device
+% When an abort key s detected this will set a global variable and throw a
+% specific error that can then be catched.
+%
+% Maint script
+% try
+%     % Your awesome experiment
+% catch ME % when something goes wrong
+%     switch ME.identifier
+%         case 'checkAbort:abortRequested'
+%             % stuff to do when an abort is requested (save data...)
+%         otherwise
+%             % stuff to do otherwise
+%             rethrow(ME) % display the error
+%     end
+% end
 
-[keyIsDown, ~, keyCode] = KbCheck(cfg.keyboard);
+if nargin < 1 || isempty(cfg)
+    error('I need at least one input.')
+end
 
-if keyIsDown && keyCode(KbName(cfg.escapeKey))
-    
-    global stopEverything
-    stopEverything = true;
-    
-    cleanUp();
+if nargin < 2 || isempty(deviceNumber)
+    deviceNumber = -1;
+end
+
+[keyIsDown, ~, keyCode] = KbCheck(deviceNumber);
+
+if keyIsDown && keyCode(KbName(cfg.keyboard.escapeKey))
 
-    error('Escape key press detected: aborting experiment.')
+    errorAbort();
 
 end
 

demos/CPP_checkAbortDemo.m

@@ -1,12 +1,31 @@
-cd ..
+% add parent directory to the path (to make sure we can access the CPP_PTB
+% functions)
+addpath(fullfile(pwd, '..')) 
 
-cfg.keyboard = [];
-cfg.escapeKey = 'ESCAPE';
+% set up
+cfg.keyboard.escapeKey = 'ESCAPE';
+
+% beginning of demo
 KbName('UnifyKeyNames');
 
-% stay in the loop until the escape key is pressed
-while GetSecs < Inf
+
+try
+
+    % stay in the loop until the escape key is pressed
+    while GetSecs < Inf
+
+        checkAbort(cfg)
+
+    end
+
+catch ME
 
-    checkAbort(cfg)
+    switch ME.identifier
+        case 'checkAbort:abortRequested'
+            warning('You pressed the escape key: will try to fail gracefully.')
+            fprintf('\nWe did catch your abort signal.\n')
+        otherwise
+            rethrow(ME) % display other errors
+    end
 
 end

demos/CPP_getResponseDemo.m

@@ -1,100 +1,100 @@
 %% Demo showing how to use the getResponse function
 
 % This small script shows how to use the getReponse function
-%  (a wrapper around the KbQueue function from PTB)
 
-% start with a clean slate
-cd ..
-clear; clc;
+% add parent directory to matlab path (so we can access the CPP_PTB functions)
+addpath(fullfile(pwd, '..')) 
+
+
+%% start with a clean slate
+clear; 
+clc;
+
 if IsOctave
     more off % for a better display experience
 end
 
-%% set parameters
+% use the default set up (use main keyboard and use the ESCAPE key to abort)
+cfg = setDefaultsPTB;
 
-% cfg.responseBox would be the device number of the device used by the participant to give his/her
-% response: like the button box in the scanner or a separate keyboard for a behavioral experiment
-%
-% cfg.keyboard would be the device number of the keyboard on which the experimenter will type or
-% press the keys necessary to start or abort the experiment.
+% show the default option
+disp(cfg.keyboard)
 
-%  cfg.responseBox and cfg.keyboard can be different or the same.
+%% set parameters
 
-% If you want to know the device number of all the keyboards and responses
-% boxes connected to the computer you can use the following code.
-% [cfg.keyboardNumbers, cfg.keyboardNames] = GetKeyboardIndices
+% Change the values set by defaults (for more info about the keyboard see the doc) 
+% cfg.keyboard.keyboard = ??
+% cfg.keyboard.responseBox = ??
+% cfg.keyboard.escapeKey = ??
 
-% Using empty vectors should work for linux when to select the "main"
-%  keyboard. You might have to try some other values for Windows. To
-%  assigne a specific keyboard input the kb assigned value (see README)
-cfg.keyboard = [];
-cfg.responseBox = [];
+% Decide which device you want to collect responses from
+deviceNumber = []; % default device (PTB will find it for you)
+% deviceNumber = cfg.keyboard.keyboard; % the one you may have chosen as the main keyboard
+% deviceNumber = cfg.keyboard.responseBox; % the one you may have chosen as the response box
 
-cfg.escapeKey = 'ESCAPE';
+% if you want getResponse to ignore the key release
+getOnlyPress = 1;
 
 % We set which keys are "valid", any keys other than those will be ignored
-expParameters.responseKey = {};
+cfg.keyboard.responseKey = {'a', 'b'};
 
+% This would make sure that you listen to presses of the escape key
+cfg.keyboard.responseKey{end+1} = cfg.keyboard.escapeKey; 
 
-%% init
 
-% Keyboard
-%  Make sure keyboard mapping is the same on all supported operating systems
-%  Apple MacOS/X, MS-Windows and GNU/Linux:
-KbName('UnifyKeyNames');
-
-
-% we ask PTB to tell us which keyboard devices are connected to the computer
-[cfg.keyboardNumbers, cfg.keyboardNames] = GetKeyboardIndices;
-
-cfg.keyboardNumbers
-cfg.keyboardNames
+%% Final checks 
 
+% Make sure keyboard mapping is the same on all supported operating systems
+KbName('UnifyKeyNames');
 
 % Test that the keyboards are correctly configured
 testKeyboards(cfg);
 
-% Give the time to the test key to be released and not listened
+% Give the time to the test key to be released and not listened to
 WaitSecs(1);
 
-
 fprintf('\nDuring the next 5 seconds we will collect responses on the following keys: \n\n');
-if isempty(expParameters.responseKey)
+if isempty(cfg.keyboard.responseKey)
     fprintf('\nALL KEYS\n\n');
 else
-    for iKey=1:numel(expParameters.responseKey)
-        fprintf('\n%s', expParameters.responseKey{iKey});
+    for iKey=1:numel(cfg.keyboard.responseKey)
+        fprintf('\n%s', cfg.keyboard.responseKey{iKey});
     end
     fprintf('\n\n');
 end
 
 
 %% Run demo
 
+try 
+    
 % Create the keyboard queue to collect responses.
-getResponse('init', cfg, expParameters, 1);
+getResponse('init', deviceNumber, cfg);
 
 % Start collecting responses for 5 seconds
 %  Each new key press is added to the queue of events recorded by KbQueue
 startSecs = GetSecs();
-getResponse('start', cfg, expParameters, 1);
+getResponse('start', deviceNumber);
 
 % Here we wait for 5 seconds but are still collecting responses.
 %  So you could still be doing something else (presenting audio and visual stim) and
 %  still collect responses.
 WaitSecs(5);
 
 % Check what keys were pressed (all of them)
-responseEvents = getResponse('check', cfg, expParameters, 0);
-
-% The following line would only return key presses and not releases
-% responseEvents = getResponse('check', cfg, expParameters, 1);
+% If the escapeKey was pressed at any time, it will only abort when you
+% getResponse('check')
+responseEvents = getResponse('check', deviceNumber, cfg, getOnlyPress);
 
 % This can be used to flush the queue: empty all events that are still present in the queue
-getResponse('flush', cfg, expParameters, 1);
+getResponse('flush', deviceNumber);
+
+% If you wan to stop listening to key presses. You could start listening again
+% later by calling: getResponse('start', deviceNumber)
+getResponse('stop', deviceNumber);
 
-% If you wan to stop listening to key presses.
-getResponse('stop', cfg, expParameters, 1);
+% If you wan to destroyt the queue: you would have to initialize it again
+getResponse('release', deviceNumber);
 
 
 %% Now we look what keys were pressed and when
@@ -106,9 +106,29 @@
         eventType = 'released';
     end
 
-    fprintf('\n%s was %s at time %.3f seconds\n', ...
-        responseEvents(iEvent).key_name, ...
+    fprintf('\n %s was %s at time %.3f seconds\n', ...
+        responseEvents(iEvent).keyName, ...
         eventType, ...
         responseEvents(iEvent).onset - startSecs);
 
 end
+
+
+catch ME
+    
+    getResponse('release', deviceNumber)
+    
+    switch ME.identifier
+        
+        case 'getResponse:abortRequested'
+            warning('You pressed the escape key: will try to fail gracefully.')
+            
+            fprintf('\nWe did catch your abort signal.\n')
+
+        otherwise
+            rethrow(ME) % display other errors
+            
+    end
+end
+
+

demos/CPP_pressSpace4meDemo.m

@@ -0,0 +1,9 @@
+% add parent directory to the path (to make sure we can access the CPP_PTB
+% functions)
+addpath(fullfile(pwd, '..')) 
+
+% beginning of demo
+KbName('UnifyKeyNames');
+
+% press the key "space" to "start" the experiment
+pressSpace4me

demos/CPP_wait4TriggerDemo.m

@@ -1,11 +1,17 @@
-cd ..
-
-cfg.device = 'Scanner';
-
+% set up
+cfg.testingDevice = 'scanner';
 cfg.numTriggers = 4; 
+cfg.triggerKey = 't';
+
+% this field is not required but can be mentioned
+cfg.MRI.repetitionTime = 3; 
 
-cfg.triggerKey = 'space';
+% add parent directory to the path (to make sure we can access the CPP_PTB
+% functions)
+addpath(fullfile(pwd, '..')) 
 
+% beginning of demo
 KbName('UnifyKeyNames');
 
+% press the key "t" to simulate triggers
 wait4Trigger(cfg)

errorAbort.m

@@ -0,0 +1,6 @@
+function errorAbort
+    errorStruct.message = 'Escape key press detected: aborting experiment.';
+    errorStruct.identifier = 'checkAbort:abortRequested';
+    
+    error(errorStruct)
+end