function err=DaqALoadQueue(daq,channel,range)
% err=DaqALoadQueue(DeviceIndex,channel,range)
% USB-1208FS: Load the channel/gain queue. The USB-1208FS can scan an
% arbitrary sequence of analog input channels, each with an arbitrary gain
% setting. DaqALoadQueue allows you to specify that sequence.
% "DeviceIndex" is a small integer, the array index specifying which HID
% device in the array returned by PsychHID('Devices') is interface 0
% of the desired USB-1208FS box.
% "channel" is a vector of length 1 to 8; each value (0 to 15) selects any of
% various single-ended or differential measurements.
% "channel" Measurement
% 0 0-1 (differential)
% 1 2-3 (differential)
% 2 4-5 (differential)
% 3 6-7 (differential)
% 4 1-0 (differential)
% 5 3-2 (differential)
% 6 5-4 (differential)
% 7 7-6 (differential)
% 8 0 (single-ended)
% 9 1 (single-ended)
% 10 2 (single-ended)
% 11 3 (single-ended)
% 12 4 (single-ended)
% 13 5 (single-ended)
% 14 6 (single-ended)
% 15 7 (single-ended)
% "range" is a vector of the same length, with values of 0 to 7, specifying
% the desired gain (and voltage range) for the corresponding channel...
% unless we're talking channels greater than 7. Single-ended inputs always
% have a range of +/- 10 V, so if you try to set the range to anything other
% than zero for a single-ended measurement, your setting will be ignored.
% For differential measurements (channels 0:7), the mapping between the
% values passed to this function and the gain (and actual range) are:
% 0 for 1x (+/-20 V), 1 for 2x (+/-10 V),
% 2 for 4x (+/-5 V), 3 for 5x (+/-4 V),
% 4 for 8x (+/-2.5 V), 5 for 10x (+/-2 V),
% 6 for 16x (+/-1.25 V), 7 for 20x (+/-1 V).
%
% USB-1608FS:
% "DeviceIndex" has the same meaning here as for the USB-1208FS.
% "channel" is a bit different...
% Only single ended inputs are defined for the 1608FS, so channels range
% only from 0 through 7. Also, when the gain queue is loaded, it is
% supposed to be loaded for all 8 channels -- AInScan does not allow you to
% use the gain queue as a way to determine which channels to check; you can
% *NOT* scan an arbitrary sequence of channels in a 1608 box like you can
% with a 1208 (and I believe 1408) box. There also appears to be no way to
% poll any of the device to find out the current state of the gain queue.
% All of this means choices have to be made. To keep this function as
% similar as possible for operations of both types of device, user is still
% allowed to pass an arbitrary set of channel/gain pairs (as long as there
% no repeats), and the function will do its best not to touch the gains of
% other channels. To be safe, you should always specify the gains for all
% 8 channels, but I figure you will only read from the channels whose gains
% you explicitly set... Even though that behavior does not happen
% automatically through calls to this function as it may with the 1208FS.
% However, since we cannot poll the device to find out the current gain
% queue settings, we're going to try to use a Preferences file. I suspect
% this will generally work, but if multiple accounts use the device or if
% the device is sometimes attached to a different machine, then this
% function may cause some gains to get changed even if not specified by the
% user. Did I mention that you should always specify the gains for all 8
% channels? Anyhoo...
% "range" has the same conceptual meaning for the 1608 as it does for the
% 1208, but the numbers are different:
%
% 0 for 1x (+/- 10 V), 1 for 2x (+/- 5 V),
% 2 for 4x (+/- 2.5 V), 3 for 5x (+/- 2 V),
% 4 for 8x (+/- 1.25 V), 5 for 10x (+/- 1 V),
% 6 for 16x (+/- 0.625 V), 7 for 32x (+/- 0.3125 V).
%
% See also Daq, DaqFunctions, DaqPins, DaqTest, PsychHidTest, DaqAIn,
% DaqAInScan, DaqAInScanBegin.
%
% 4/15/05 dgp Wrote it.
% 1/8/08 mpr created behavior appropriate for 1608
% 6/23/15 mk Make compatible with Octave, fix 1608-FS pref file caching.
devices = PsychHIDDAQS;
if strcmp(devices(daq).product(5:6),'16')
Is1608 = 1;
MaxChannelID = 7;
else
Is1608 = 0;
MaxChannelID = 15;
end
if length(channel)~=length(range)
error('Length of "channel" and "range" vectors must be equal.');
end
if length(channel)~=numel(channel) || length(range)~=numel(range)
error('"channel" and "range" must be vectors.');
end
if any(~ismember(channel,0:MaxChannelID)) || any(~ismember(range,0:7))
error(sprintf('Each "channel" value must be in 0:%d and each range value must be in 0:7.',MaxChannelID));
end
if Is1608
if length(channel) ~= length(unique(channel))
error('You cannot specify the same input channel multiple times!');
end
DaqPrefsDir = DaqtoolboxConfigDir;
PrefsExist = exist([DaqPrefsDir filesep 'DaqPrefs.mat'],'file');
if PrefsExist
DaqVars=load([DaqPrefsDir filesep 'DaqPrefs']);
if isfield(DaqVars,'OldGains')
OldGains = DaqVars.OldGains;
else
PrefsExist=0;
end
end % if PrefsExist
LeftOut = setdiff(0:7,channel);
range(channel+1) = range;
if PrefsExist
range(LeftOut+1) = OldGains(LeftOut+1);
else
range(LeftOut+1) = zeros(1,length(LeftOut));
end
report=uint8([19 range(:)']);
err=PsychHID('SetReport',daq,2,19,report); % ALoadQueue
if err.n
fprintf('DaqALoadQueue error 0x%s. %s: %s\n',hexstr(err.n),err.name,err.description);
else
DaqVars.OldGains = range;
save([DaqPrefsDir filesep 'DaqPrefs.mat'],'-v7','-struct','DaqVars');
end
else % if Is1608
% ignore range inputs for single-ended channels
range(find(channel > 7)) = zeros(size(find(channel > 7)));
report=zeros(1,2+2*length(channel));
report(1)=19;
report(2)=length(channel);
for i=1:length(channel)
report(2*i+1)=channel(i);
report(2*i+2)=range(i);
end
err=PsychHID('SetReport',daq,2,19,uint8(report)); % ALoadQueue
if err.n
fprintf('DaqALoadQueue error 0x%s. %s: %s\n',hexstr(err.n),err.name,err.description);
end
end % if Is1608; else
return;