dotsReadableHID Class Reference

Overview

Superclass for objects that read data from Human Interface Devices.

dotsReadableHID extends the dotsReadable superclass with support for Human Interface Devices (HID). It uses the mexHID() mex function, which is part of Snow Dots, to locate and communicate with HID devices.

dotsReadableHID itself is not a usable class. It supports dotsReadableHID* subclasses such as dotsReadableHIDKeyboard.

mexHID() uses an internal queue to record all the value changes of elements (buttons, axes, etc.) for each dotsReadableHID object. The dotsReadableHID readData() method passes any queued data into Matlab via each object's appendData() method.

Inheritance diagram for dotsReadableHID:

Properties and Events
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.

Protected Properties
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.

Methods
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
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	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...

Methods

flushData()

flushData	(	self	,
		varargin
	)

Clear data from this object and the mexHID() internal queue.

Extends the dotsReadable flushData() method to do also flush the mexHID() internal data queue.

setComponentCalibration()

components setComponentCalibration	(	self	,
		namesOrIDs	,
		rawRange	,
		deadRange	,
		calibratedRange	,
		granularity
	)

Adjust scaling of raw values from HID components.

Parameters

IDs	array of component integer IDs
rawRange	[min, max] raw values to work between
deadRange	[min, max] raw values to treat as "middle"
calibratedRange	[min, max] calibrated values to report
granularity	the smallest unit of reported values

setComponentCalibration() allows the raw integer values read from device components to be mapped onto arbitrary, calibrated values. Thus, components may use meaningful units. Components can also ignore unused values at the extremens of their ranges, and coalesce noisy values near the middles of their ranges.

IDs must contain one or more of the unique IDs in components. Each specified component will receive the same calibration.

rawRange specifies the range of integer values to consider when reading from components. For example, a component may have a theoretical range of 0-255, rawRange might specify a smaller acheivable range, perhaps 10-245. Values outside of rawRange are clipped.

deadRange specifies a range of values near the "middle" of rawRange. All values within deadRange are coalesced and reported as the "middle" value. For example, a joystick might need to treat several appriximately centered values as properly centered.

calibratedRange specifies the range of values to be reported. The min and max of rawRange are mapped to the min and max of calibratedRange, respectively. Intermediate raw values are mapped to intermediate calibrated values linearly.

granularity specifies the smallest step between calibrated values. Reported values will be integer multiples of granularity.

If any of rawRange, deadRange, calibratedRange, or granularity is empty or omitted, the present value is used.

defineEvent()

event defineEvent	(	self	,
		name	,
		varargin
	)

Define a calibrated event for given component.

Parameters

componentNameOrID

the HID usage name or ID

Finds the component that matches the given nameOrID, and defines an event for that component. Any existing event for that component will be replaced. The "pressed" event is defined as the component reaching its maximum value. The event name will have the form "pressed @a keyName", including the space. Arguments: name ... (required) string name of the event Required property/value pairs: 'component' ... string name (standard form; e.g., the "b" key must be named as "KeyboardB" ...

See mexHIDUsage or mexHIDUsage.gui) or component ID Optional property/value pairs: 'calibratedValues' Moved 6/5/2018 from dotsReadableHIDKeyboard

openHIDQueue()

isOpen openHIDQueue ( self  , cookies    )

protected

Open a queue to record value changes for device elements.

Adds the device elements identified by queueCookies to a queue to have their value changes recorded. Other device elements will be left out of the queue, so their values will be ignored.

Returns true if mexHID successfully created the queue and added queueCookies elements were added to it. The queue will start recording value changes immediately.

readNewData()

newData readNewData ( self  )

protected

Pass any data from the mexHID() internal queue to this object().

Moves data from the mexHID() internal queue into Matlab via the queueCallback function and queueCallbackData property.

Properties and Events

deviceMatching

Property deviceMatching

struct of HID parameters for identifying suitable HID devices.

Each subclass must supply parameters and values that mexHID() can use to locate suitable HID devices.

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

devicePreference

Property devicePreference

struct of HID parameters for choosing among suitable devices.

Each subclass may supply parameters and values that mexHID() can use to choose among a suitable HID devices.

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

queueDepth

Property queueDepth = 1024

size of the mexHID() internal data queue

queueDepth is number of HID element value changes to keep in the mexHID() internal data queue, before discarding old values. This is distinct from initialEventQueueSize, which is used by all dotsReadable objects.

The best queueDepth depends on how fast a HID device accumulates data and how often the data are read() into Matlab.

deviceID

Property deviceID

protected

device identifier from mexHID('openMatchingDevice')

openDevice() should fill in deviceID.

queueCallback

Property queueCallback = @dotsReadableHID.mexHIDQueueCallback

protected

Callback which mexHID() uses to pass HID data to Matlab.

mexHID('check') invokes queueCallback function_handle to pass formatted data into Matlab.

queueCallback should be a function handle. The corresponding function must expect a dotsReadableHID object ("self") as the first argument. It must expect an nx3 matrix of component data as the second argument. It must assign new data to queueCallbackData.

---

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

• dotsReadableHID.m