function daq = DaqDeviceIndex(DeviceName, IShouldWarn)
% daq = DaqDeviceIndex([DeviceName][, ShowInterfaceNumberWarning=1])
% Returns a list of all your USB -1024LS, -1208FS, -1408FS, or -1608FS daqs.
%
% CAUTION: This routine works well on GNU/Linux and MS-Windows, but is very
% unreliable on Apple OSX, especially with multiple DAQ devices connected.
% You may be better off guessing a proper daq index.
%
% TECHNICAL NOTE: When we call PsychHID('Devices'), each USB-1208FS/1408FS
% box presents itself as four HID "devices" sharing the same serial number. They
% are interfaces 0,1,2,3. They usually appear in reverse order in the
% device list. Nearly all the commands use only interface 0, so
% we will select that one to represent the whole. All our Daq routines
% expect to receive just the interface 0 device as a passed designator. The
% few routines that need to access the other interfaces do so
% automatically.
%
% ADDENDUM: The above statement is correct for the 1208FS and the 1408FS,
% not for the 1608FS. Number of Devices found by PsychHID for a
% 1608FS and Leopard varies from five to seven with little rhyme or reason. It
% appears that the correct number of interfaces is seven. As with the 1208FS,
% most communication is through interface 0. However, when acquiring data
% (e.g., using DaqAInScan), output is via interfaces 1 through 6. Because
% PsychHID's enumeration of the interfaces is flaky, you may need to run this
% function more than once (with calls to DaqReset and probably "clear PsychHID"
% in between successive calls) in order to get device enumeration completed
% correctly. In DaqTest, user will be warned if they try to test a 1608 and
% this function doesn't return the right number of interfaces, so I added the
% second optional argument as a flag to suppress the warning that would be
% generated here. -- mpr
%
% See also Daq, DaqFunctions, DaqPins, DaqTest, PsychHIDTest,
% DaqFind, DaqDIn, DaqDOut, DaqAIn, DaqAOut, DaqAInScan,DaqAOutScan.
% 4/15/05 dgp Wrote it.
% 8/26/05 dgp Added support for new "USB" name, as suggested by Steve Van Hooser <vanhooser@neuro.duke.edu>.
% 8/26/05 dgp Incorporated bug fixes (for compatibility with Mac OS X Tiger)
% suggested by Jochen Laubrock <laubrock@rz.uni-potsdam.de>
% and Maria Mckinley <parody@u.washington.edu>.
% The reported number of outputs of the USB-1208FS has changed in Tiger.
% http://groups.yahoo.com/group/psychtoolbox/message/3610
% http://groups.yahoo.com/group/psychtoolbox/message/3614
%
% 11-12/xx/07 mpr Added possibility of specified input (with defaults) and
% changed number of expected device outputs; tested with
% USB-1608FS and Leopard. Known device names: PMD-1208FS,
% USB-1208FS, USB-1408FS, USB-1608FS.
% 1/7/08 mpr Rewrote sections to take advantage of input, added checks to deal
% with problems I encountered with 1608 and PsychHID's device
% enumeration.
% 1/14/08 mpr added second argument
% 5/22/08 mk Add (untested!) support for detection of USB-1024LS box.
% 5/08/13 mk Fix enumeration of multiple connected devices (untested).
% Use numeric USB productID instead of USB product name string
% for matching of devices, as the latter isn't supported on
% Windows, at least not reliably, whereas productID's are. Also
% reject non-MCC devices based on the well-defined MCC
% vendorID.
% Use combined locationID and serialNumber as unique ID for
% each instance of multiple identical DAQ devices to
% disambiguate if user connects multiple devices of same model.
% Bits of cleanup and refactoring.
% 5/20/13 mk Verify correct enumeration of devices with a USB-1408FS device
% on 10.5 Leopard, 10.7 Lion, Linux, and Windows-7. Remove 1408FS
% "untested" warnings. It is tested now.
%
% 10/4/13 mk More futile attempts to fix OSX: Use a heuristic of always
% choosing the maximum device index of eligible entries as
% returned daq index, assuming that one is interface#0. This
% heuristic only used if only 1 DAQ device is detected and only
% on OSX, as the regular matching code works well on Linux and
% Windows.
%
% 12/06/15 mk Try to use interfaceID on OSX to find interface #0 directly without
% all the awful hacks. PsychHID learned to extract interfaceID with
% this release. Well, we don't know if it works with DAQ boxes, we
% just hope it will work.
%
% 07/31/16 mk Remove experimental note about 1024LS. It's tested and known to work.
if nargin < 2 || isempty(IShouldWarn)
IShouldWarn=1;
end
if ~nargin || isempty(DeviceName)
% DeviceName can be anything -- doesn't matter for further processing.
DeviceName = '';
AcceptAlternateNames = 1;
else
if ~ischar(DeviceName)
error('DaqDeviceIndex expects a character string as input.');
end
AcceptAlternateNames = 0;
% Validate given DeviceName against list of supported devices:
switch DeviceName
case {'PMD-1208FS','USB-1208FS','PMD-1408FS','USB-1408FS'}
case {'PMD-1608FS','USB-1608FS'}
case {'PMD-1024LS','USB-1024LS'}
otherwise
error('I did not recognize your specified device name.');
end % switch DeviceName
end % if ~nargin || isempty(DeviceName)
NumInterfaces = [];
% Retrieve preprocessed list of PsychHID('Devices'), with some filtering
% applied to supported DAQ devices:
devices = PsychHIDDAQS;
daq=[];
for k=1:length(devices)
% Skip all devices with a vendorId other than 2523 aka 0x09db, ie. all
% devices that are not from Measurement Computing:
if devices(k).vendorID ~= 2523
continue;
end
% It is a MCC device.
if AcceptAlternateNames
if isempty(NumInterfaces)
NumInterfaces = 1;
MatchedDeviceName = devices(k).product;
MatchedSerialNumbers = devices(k).serialNumber;
else
% Device already known - stored in our list?
matchedIt = 0;
for l=1:size(MatchedDeviceName,1)
if ~isempty(strfind(MatchedDeviceName(l,:),devices(k).product)) && ...
~isempty(strfind(MatchedSerialNumbers(l,:),devices(k).serialNumber))
% Yes: Increment its interface count:
NumInterfaces(l) = NumInterfaces(l) + 1;
matchedIt = 1;
end
end % for l=1:size(MatchedDeviceName,1)
% Found at least 1 match in list of already known devices?
if ~matchedIt
% Nope: Add this devices name/id and serialNumber to array,
% init to at least one interface we found by definition of
% reaching this point:
MatchedDeviceName = char(MatchedDeviceName,devices(k).product);
MatchedSerialNumbers = char(MatchedSerialNumbers,devices(k).serialNumber);
NumInterfaces(end+1) = 1;
end
end % if isempty(NumInterfaces); else
% We want interface #0:
if devices(k).interfaceID == 0
daq(end+1) = k;
end
else % if ~AcceptAlternateNames
if streq(devices(k).product,DeviceName)
if isempty(NumInterfaces)
NumInterfaces = 1;
MatchedSerialNumbers = devices(k).serialNumber;
else
% Device already known - stored in our list?
matchedIt = 0;
for l=1:size(MatchedSerialNumbers,1)
if ~isempty(strfind(MatchedSerialNumbers(l,:), devices(k).serialNumber))
% Yes: Increment its interface count:
NumInterfaces(l) = NumInterfaces(l) + 1;
matchedIt = 1;
end
end
% Found at least 1 match in list of already known devices?
if ~matchedIt
% Nope: Add this devices serialNumber to array, init to at
% least one interface we found by definition of reaching
% this point:
MatchedSerialNumbers = char(MatchedSerialNumbers,devices(k).serialNumber);
NumInterfaces(end+1) = 1;
end
end % if isempty(NumInterfaces); else branch.
% We want interface #0:
if devices(k).interfaceID == 0
daq(end+1) = k; %#ok<*AGROW>
end
end % if streq(devices(k).product,DeviceName)
end % if AcceptAlternateNames; else
end % for k=1:length(devices)
if IShouldWarn
for k=1:length(daq)
if ~isempty(strfind(devices(daq(k)).product,'1608'))
if NumInterfaces(k) < 7
ConfirmInfo(sprintf(['Only found %d interfaces for DeviceIndex %d. Execute ' ...
'"help DaqReset" for suggestions.'], ...
NumInterfaces(k),daq(k)));
end
end
end
end
return;