1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
function varargout = PsychHID(varargin) %#ok<STOUT>
%
% returnValues=PsychHID(subcommand, arg1 [,arg2] ...)
%
% PsychHID is a MEX file that communicates with any USB device that is
% HID-compliant. The Universal Serial Bus (USB) is quite popular, and there
% are many USB devices that conform to the Human Interface Device (HID)
% class. Typical HID devices are keyboards, mice and joysticks. That is
% what the HID class was designed for, but manufacturers of more exotic
% input and output devices, including audio breakout boxes and data
% acquisition devices, have also opted to be HID-compliant.
%
% PsychHID also supports certain low-level operations on USB devices which are not
% HID-compliant. Currently synchronous USB control transfers, interrupt transfers,
% and bulk transfers are supported. PsychHID uses libusb-1.0 for these operations.
% Abilities and limitations of low-level access, and various required setup steps
% to enable low-level access to specific USB devices, vary by operating system,
% available operating system or 3rd party (device manufacturer) device drivers,
% and the specific type and capabilities of USB devices. In general, things should
% work nicely on Linux if a suitable udev.rules file is installed for your device.
% Things should work on macOS if neither macOS itself nor 3rd parties (e.g., the
% device manufacturer of your USB device) have a kernel driver attached to your
% device for exclusive use. In case of attached kernel drivers, only various painful
% measures and hacks will make it maybe possible to access the device. See the
% libusb FAQ here:
%
% https://github.com/libusb/libusb/wiki/FAQ#how-can-i-run-libusb-applications-under-mac-os-x-if-there-is-already-a-kernel-extension-installed-for-the-device-and-claim-exclusive-access
%
% On MS-Windows, abilities depend on specific type of device. Some will work plug
% and play out of the box without limitations, others will have limitations and/or
% require installation of dedicated kernel drivers. E.g., USB-HID devices which are
% accessed by the libusb HID backend can not support USB control transfers as of
% libusb version 1.0.26. See these FAQ's for setup info:
%
% https://github.com/libusb/libusb/wiki/FAQ#How_to_use_libusb_under_Windows
%
%
% NOT RESPONDING? If PsychHID is not responding, try quitting and
% restarting MATLAB. We find that this reliably restores normal
% communication.
%
%
% Additional software requirements:
%
% PsychHID uses the free/open-source libusb-1.0 library (http://libusb.info)
% as a backend for low-level device control. libusb is licensed under
% LGPLv2+ license. PsychHID also uses the BSD licensed HIDAPI library
% (http://www.signal11.us/oss/hidapi/) as backend for USB-HID access.
%
% On Linux and Windows, not all PsychHID subfunctions are implemented, as
% certain functionality can be handled in a better or different way on
% those systems. USB-HID low-level access, and USB low-level access is
% implemented though.
%
% Linux: libusb-1 is part of a standard operating system installation, so
% nothing to do for you.
%
% macOS: You must manually install the libusb-1.0.dylib library on your
% system to use PsychHID for low-level USB access and communication, e.g.,
% for synchronous USB control transfers, bulk- and interrupt transfers.
%
% One good source of libusb-1.0.dylib is the HomeBrew package manager from
% https://brew.sh After setting up HomeBrew you can install libusb-1 via:
%
% brew install libusb
%
% MS-Windows: PsychHID will use a working version of libusb-1.0.dll which is
% contained in the Psychtoolbox/PsychContributed/x64 folder. This library is
% only infrequently updated by us. More recent versions of the library may be
% downloaded from the official project website:
% https://libusb.info -> Download link, or Git repository releases section...
% https://github.com/libusb/libusb/releases
%
%
% HELP: Like Screen, PsychHID has built-in help. For a list of PsychHID
% subcommands enter "PsychHID" at the MATLAB command line:
%
% >> PsychHID
% Usage:
% numberOfDevices=PsychHID('NumDevices')
% numberOfElements=PsychHID('NumElements',deviceNumber)
% numberOfCollections=PsychHID('NumCollections',deviceNumber)
% devices=PsychHID('Devices')
% elements=PsychHID('Elements',deviceNumber)
% collections=PsychHID('Collections',deviceNumber)
% elementState=PsychHID('RawState',deviceNumber,elementNumber)
% elementState=PsychHID('CalibratedState',deviceNumber,elementNumber)
% [keyIsDown,secs,keyCode]=PsychHID('KbCheck',[deviceNumber])
% [report,err]=PsychHID('GetReport',deviceNumber,reportType,reportID,reportBytes)
% err=PsychHID('SetReport',deviceNumber,reportType,reportID,report)
% usbHandle = PsychHID('OpenUSBDevice', vendorID, deviceID [, configurationId=0])
% PsychHID('CloseUSBDevice' [, usbHandle])
% PsychHID('USBClaimInterface', usbHandle, interfaceId)
% [recData, count] = PsychHID('USBControlTransfer', usbHandle, bmRequestType, bRequest, wValue, wIndex, wLength [, outData][, timeOutMSecs=10000])
% [countOrRecData] = PsychHID('USBBulkTransfer', usbHandle, endPoint, length [, outData][, timeOutMSecs=10000])
% [countOrRecData] = PsychHID('USBInterruptTransfer', usbHandle, endPoint, length [, outData][, timeOutMSecs=10000])
%
% For help on a specific PsychHID subcommand, call PsychHID with the
% subcommand suffixed with a question mark, for example:
%
% >> PsychHID NumDevices?
% Usage:
% numberOfDevices=PsychHID('NumDevices')
% Return the the number of USB HID devices connected to your computer.
%
% History:
%
% In the OS9 and Win Psychtoolbox, most functions that accepted user input
% were implemented as device-specific mex files. In Psychtoolbox-3 they are
% M files that all call PsychHID, just one MEX for the many kinds of input
% device. For example, Gamepad (formerly named "Joystick") and KbCheck are
% M functions that call PsychHID. For user programs, it is easier to call
% these special-purpose functions (with self-documenting names), which call
% PsychHID, than to call PsychHID directly. PsychHID is more general, but
% also more complicated. However, if you acquire a novel input/output
% device that is HID-compliant, you can access it through PsychHID.
% PsychHID can distinguish between multiple devices of the same type by
% their serialNumber or locationID.
%
% More technical background infos:
%
% PsychHID on macOS links against Apples HID Utilities library. For information on
% how to program HID devices on OS X in C or Objective C see the HID
% utilities project, its companion project, HID Explorer and related:
% http://developer.apple.com/samplecode/HID_Utilities_Source/HID_Utilities_Source.html
% http://developer.apple.com/samplecode/HID_Explorer/HID_Explorer.html
% http://developer.apple.com/samplecode/Hardware/idxHumanInterfaceDeviceForceFeedback-date.html
% _________________________________________________________________________
%
% See also: DaqTest, KbCheck, Gamepad, PsychHardware.
AssertMex('PsychHID.m');
|
