Overview

Reads data from a HID keyboard device.

dotsReadableHIDKeyboard extends the dotsReadableHID superclass to manage HID keyboard devices. Many integrated and USB keybords are HID keyboards.

By default, dotsReadableHIDKeyboard defines "pressed" events for each keyboard key. Use getNextEvent() to make sure that no key presses are missed, and that each press is observed only once.

Inheritance diagram for dotsReadableHIDKeyboard:

[legend]

Properties and Events
Property	keyMatching
	Example usage: kb = dotsReadableHIDKeyboard(); [isPressed, waitTime, data, kbout] = dotsReadableHIDKeyboard.waitForKeyPress(kb, 'KeyboardF', 5, true) More...

Property	VendorIDs
	matching preferences read from machine defaults ... More...

Properties and Events inherited from dotsReadableHID
Property	deviceInfo
	struct of info about the HID device

Property	deviceMatching
	struct of HID parameters for identifying suitable HID devices. More...

Property	devicePreference
	struct of HID parameters for choosing among suitable devices. More...

Property	queueDepth = 1024
	size of the mexHID() internal data queue More...

Property	queueIsOpen = false
	whether or not the internal data queue opened successfully

Property	isExclusive = false
	whether or not to get exclusive access to device data

Property	allowMultipleConnections = false
	whether or not to allow multiple objects to access the same device

Properties and Events inherited from dotsReadable
Property	isAvailable = false
	whether or not the object is ready to read() from

Property	components
	struct array with details about each component

Property	state
	matrix of ID, latest value, and latest time indexed by ID

Property	history
	matrix of component ID, value, and time from previous read()

Property	isAutoRead = true
	whether or not to to invoke read() during getValue(), etc.

Property	eventDefinitions
	struct array defining events of interest, indexed by ID

Property	initialEventQueueSize = 100
	initial size of queue for events of interest

Property	clockFunction
	any function that returns the current time as a number

Property	filename
	name of the data file for devices that store their own data

Property	filepath
	where the file is

Property	recordDuringCalibration = true
	controls whether or not to stop recording during calibration

Property	useGUI = false
	Flag to use GUI for feedback, etc.

Property	useExistingCalibration = false
	Flag to skip calibration routine.

Property	calibrationUI
	Possibly use a keyboard or other UI to help with calibration.

Property	deactivateEventsAtStartTrial =false
	Flag to deactivate all events at the beginning of each trial.

Methods
self	dotsReadableHIDKeyboard (devicePreference)
	Get rid of annoying rollover event. More...

Methods inherited from dotsReadableHID
self	dotsReadableHID ()
	Constructor takes no arguments.

	flushData (self, varargin)
	Clear data from this object and the mexHID() internal queue. More...

components	setComponentCalibration (self, namesOrIDs, rawRange, deadRange, calibratedRange, granularity)
	Adjust scaling of raw values from HID components. More...

event	defineEvent (self, name, varargin)
	Define a calibrated event for given component. More...

Methods inherited from dotsReadable
self	dotsReadable ()
	Constructor takes no arguments.

	initialize (self)
	Locate, acquire, configure, etc. device and component resources.

	calibrate (self, varargin)
	Calibrate the device More...

	record (self, onFlag, filename)
	Open/close data file associated with the device Arguments: onFlag ... More...

	reset (self, varargin)
	reset device More...

	close (self)
	Release any resources acquired by initialize().

	delete (self)
	Automatically close when Matlab is done with this object.

	read (self)
	Add incoming data to history and detect events of interest. More...

	flushData (self, waitForNoEvents)
	Delete historical data and reset the current state. More...

	logData (self)
	Record current and historical data in topsDataLog. More...

stateAtTime	getState (self, time)
	Get the state of device components as of the given time. More...

value data	getValue (self, ID)
	Get the latest value for the given component. More...

event	defineEvent (self, name, varargin)
	Define the event of interest for one of the input components. More...

	defineEventsFromComponents (self, names, varargin)
	defineEventsFromComponents More...

	defineEventsFromStruct (self, eventStruct, setName, keepExisting, inactivate)
	defineEventsFromStruct More...

	showActiveEvents (self)
	Mostly for debugging.

	activateEventSet (self, name)
	Swap in a set of events.

	activateEvents (self)
	Activate all events. More...

	deactivateEvents (self)
	Deactivate all events. More...

activeFlags	getActiveFlags (self)
	Get all active flags.

	setActiveFlags (self, activeFlags)
	Set all active flags from array.

	setEventsActiveFlag (self, activateList, deactivateList)
	Set/unset activeFlag. More...

name data	getNextEvent (self, isPeek, acceptedEvents)
	Get the next event that was detected in read(). More...

lastName lastID names IDs	getHappeningEvent (self, time)
	Get events that are happening at the current time. More...

name waitTime data	waitForEvents (self, eventNames, maxWait)
	Wait for event(s)

nEvents	getNumberOfEvents (self)
	Get the number of events in eventQueue. More...

IDs	getComponentIDs (self)
	Get an array of unique integer component IDs. More...

ID	getComponentID (self, nameOrID)
	Get ID of component by name or ID

name	getComponentName (self, nameOrID)
	Get name of component by name or ID

indices	getComponentIndicesByID (self, IDs)
	Get array of indices for the given component IDs

indices	getComponentIndicesByName (self, names)
	Get array of indices for the given component names

time	getDeviceTime (self)
	Get the current time from clockFunction.

	setDeviceTime (self, val)
	Set the device time

	startTrial (self, varargin)
	startTrial() More...

	finishTrial (self, varargin)
	finishTrial() More...

	plotData (self)
	Open a figure with continuously read device data. More...

	startTrialDevice (self, varargin)
	Overloaded methods.

Protected Methods
components	openComponents (self)
	Locate and enqueue all the keys of the keyboard.

	closeComponents (self)
	Unenqueue all the keys of the keyboard.

Protected Methods inherited from dotsReadableHID
isOpen	openDevice (self)
	Find the best available HID device with mexHID().

	closeDevice (self)
	Release mexHID() resources for this device.

isOpen	openHIDQueue (self, cookies)
	Open a queue to record value changes for device elements. More...

newData	readNewData (self)
	Pass any data from the mexHID() internal queue to this object(). More...

Protected Methods inherited from dotsReadable
isOpen	openDevice (self)
	Locate and acquire input device resources (for subclasses). More...

	closeDevice (self)
	Release input device resources (for subclasses). More...

	resetDevice (self, varargin)
	Reset the device.

status	calibrateDevice (self, varargin)
	Calibrate the device (for subclasses). More...

isRecording	startRecording (self)
	Turn on data recording from the device (for subclasses).

isRecording	stopRecording (self)
	Turn off data recording from the device (for subclasses).

components	openComponents (self)
	Locate and acquire device components (for subclasses). More...

	closeComponents (self)
	Release device components (for subclasses). More...

newData	readNewData (self)
	Read and format incoming data (for subclasses). More...

isEvent	detectEvents (self, data)
	Use new data to look up events of interest (used internally). More...

newSize	resizeEventQueue (self, minSize, doClear)
	Resize and optionally clear the event queue (used internally). More...

nEvents	enqueueEvents (self, eventValues)
	Add events of interest to the event queue (used internally). More...

eventValue nEvents	dequeueEvent (self, isPeek)
	Remove the next queued event of interest (used internally). More...

Static Methods
static kbs	openManyKeyboards ()
	Open all of the available HID keyboards. More...

static	closeManyKeyboards (kbs)
	Close several HID keyboards. More...

static isPressed data kb	isKeyPressed (kbs, keyName)
	Is the given key pressed, on one or many keyboards? More...

static didHappen waitTime data kb name	waitForKeyPress (kbs, keyName, maxWait, flush, waitForRelease)
	Wait for given key to be pressed, on one or many keyboards. More...

Static Methods inherited from dotsReadableHID
static	mexHIDQueueCallback (self, newData)
	Pass data from the mexHID() internal queue to Matlab. For newData, Rows are inputs Columns are.

static time	currentHIDTime ()
	Get the current time from the system USB/HID implementation.

Static Methods inherited from dotsReadable
static isHappening data readable	isEventHappening (readables, eventName)
	Is the named event happening now? More...

static didHappen waitTime data readable name	waitForEvent (readables, eventName, maxWait)
	Wait for the named event to happen. More...

static data	loadDataFile (filename, varargin)
	Load data from file. More...

Additional Inherited Members
Protected Properties inherited from dotsReadableHID
Property	deviceID
	device identifier from mexHID('openMatchingDevice') More...

Property	queueCallback = @dotsReadableHID.mexHIDQueueCallback
	Callback which mexHID() uses to pass HID data to Matlab. More...

Property	queueCallbackData
	matrix of recent data passed in from mexHID()

Protected Properties inherited from dotsReadable
Property	eventQueue
	array of queued events (row indices into history)

Property	queueNext
	queue index of the next event to be dequeued

Property	queueLast =0
	queue index of the last event enqueued

Property	isRecording =false
	keep track of whether device is currenly writing to a data file

Property	didCalibrate = true
	Keep track of whether calibration occurs.

Property	defaultEventPrefix = 'event'
	Default prefix for event names: <prefix>_<componentName>

Property	eventSets
	Strutures with different named event definitions, in case we want to quickly swap between them.

Constructor

◆ dotsReadableHIDKeyboard()

self dotsReadableHIDKeyboard ( devicePreference )

Get rid of annoying rollover event.

Constructor may take device matching preferences.

Parameters

devicePreference struct of HID matching parameters

devicePreference is an optional struct of HID parameters for choosing among suitable devices, assigned to the devicePreference property. jig added useSecondary flag to be able to get a second keyboar

Methods

◆ openManyKeyboards()

static kbs openManyKeyboards ( )

static

Open all of the available HID keyboards.

Scans for connected HID keyboards and constructs a dotsReadableHIDKeyboard object for each. Returns the objectss as an array of dotsReadableHIDKeyboard.

◆ closeManyKeyboards()

static closeManyKeyboards ( kbs )

static

Close several HID keyboards.

Parameters

kbs	array of dotsReadableHIDKeyboard objects

Invokes close() on each of the given dotsReadableHIDKeyboard objects. Objects should be re-initialized or discarded.

◆ isKeyPressed()

static isPressed data kb isKeyPressed	(	kbs	,
		keyName
	)

static

Is the given key pressed, on one or many keyboards?

Parameters

kbs	array of dotsReadableHIDKeyboard objects
keyName	the HID usage name of a keyboard key

Creates a "pressed" event for the given keyName, on each of the given kbs. Checks whether the pressed event is happening on any of the given kbs.

Returns true if any of given kbs has keyName currently pressed. Returns as a second output the data associated with the key press. The data has the form [ID, value, time]. Returns as a third output the keyboard object on which the key is pressed. If keyboard has the key pressed, returns only the first one.

◆ waitForKeyPress()

static didHappen waitTime data kb name waitForKeyPress	(	kbs	,
		keyName	,
		maxWait	,
		flush	,
		waitForRelease
	)

static

Wait for given key to be pressed, on one or many keyboards.

Arguments: kbs ... dotsReadableHIDKeyboard object (or cell array of them) keyName ... the HID usage name (component) of a keyboard key (or blank for any key to wait for any key) maxWait ... maximum time to wait for key press (sec) flush ... whether or not to flush queue before starting waitForRelease ... whether to wait for release after press

Creates a "pressed" event for the given keyName, on each of the given kbs. Waits for one of of the given kbs to report that the given keyName was pressed. maxWait specifies how long to wait before giving up. Uses currentTime() of the first object to keep track of time. Invokes read() and checks each object for events at least once, even if maxWait is zero or negative.

Returns true if any of given kbs reports that keyName was pressed, before maxWait. Returns as a second output the amout of time waited. Returns as a third output the data associated with the key press. The data has the form [ID, value, time]. Returns as a fourth output the object which reported the key press. If more than one keyboard can report that the key was pressed, only the first one is returned.

Properties and Events

◆ keyMatching

Property keyMatching

Example usage: kb = dotsReadableHIDKeyboard(); [isPressed, waitTime, data, kbout] = dotsReadableHIDKeyboard.waitForKeyPress(kb, 'KeyboardF', 5, true)

struct of HID parameters to identify the key elements of the keyboard.

See mexHIDUsage() or mexHIDUsage.gui() for lists of valid HID parameters.

◆ VendorIDs

Property VendorIDs

matching preferences read from machine defaults ...

including secondary values if/when second keyboard is added

The documentation for this class was generated from the following file:

dotsReadableHIDKeyboard.m

Overview

Properties and Events

Methods

Protected Methods

Static Methods

Additional Inherited Members

Constructor

◆ dotsReadableHIDKeyboard()

Methods

◆ openManyKeyboards()

◆ closeManyKeyboards()

◆ isKeyPressed()

◆ waitForKeyPress()

Properties and Events

◆ keyMatching

◆ VendorIDs