Human Interface Device

Reads data from a USB/HID device.

Pins

io	letter	name	unit	description
out			value or logic	Maximum of 6 per object

Parameters

name	option	description
pins	off or control	Pins may be connected to any control in the list.
controls		Assign controls to pins.
sign		A control axis may be flipped, or a button set to bipoloar or digital.

Notes

To use a HID device with ABox2 it must be connected to the computer and operating correctly before ABox2 is started. After launching ABox2, create a HID object and place it in the workspace. Right click on the newly created HID object to summon its control panel. Pins A HID object may have up to 6 output pins. The 'Pins' list shows the device, control name, pin letter, and OK if the control was found on the computer. If the control can not be found, '!!!' is displayed to indicate that the pin will not produce any data. If there are several devices or controls with the same name they will be numbered consecutively. For example, if there are three joysticks they will be numbered #1, #2 and #3. Controls The control list displays all of the devices and controls available on the local computer. After selecting a pin, a control may be assigned simply by clicking on it. Any object may select any combination of controls from any available device. Sign Sometimes it is convenient to change the sign of the control's data. Reversing the direction of a Y axis for example. This is accomplished by pressing one of the buttons in the sign group. Changing the sign will affect all objects connected to the same control. Thus if the Y axis is reversed on one object, it will be reversed for all other objects as well. Types of Data Control buttons produce typical ABox logic values. If the button is pressed it will produce -1, otherwise it will produce +1 or 0 depending on the sign setting. -1 and +1 are the default. All other controls produce ABox normalized values ranging from -1 to +1 for most controls and 0 to +1 the others. The resolution and range is limited by device. For example, a joystick Y axis might have 10 bits of resolution resulting in 1024 unique values spread between -1 and +1. A Hat Switch, however, typically has 4 bits resulting in 16 possible values spaced between 0 and +1, of which only 9 are actually reported. Some experimentation may be required to determine the range of data a particular control produces. At the simplest this can be done by connecting a Readout and watching what it does while manipulating the control. Transients Output data is not filtered or smoothed by the HID object. If the control is connected to an audio path, an amplitude pin for example, small transients may be heard. Use a low pass filter somewhere between the HID object and the audio path to prevent this. For logic outputs, an ADSR can also be used. XYZ Axes and Joysticks ABox adopts the USB HID standard of a right handed coordinate system. This defines directions in three dimensional space as well as positive and negative rotations. The diagram below shows the X, Y and Z axes with rings pointing towards positive rotation around each axis. A joystick device is oriented with the handle pointing up along the Z axis. Moving the handle from left to right is a positive rotation around the Y axis. Moving the handle backwards to forwards is a negative rotation around the X axis. Twisting the handle clockwise is a negative rotation around the Z axis. While X and Y appear to be swapped on the control panel, they are labeled correctly in terms of rotation around the stated axis. Latency and Performance Issues While playing, ABox checks the status of the HID controls once every sample frame, at most every 23 milliseconds. Thus minimum latency between physical control motion and data appearing in the circuit is 23ms. If there are multiple control events waiting, they will be placed at equal intervals along the sample frame. Delay phenomena may arise if there is a long latency object in the circuit, particularly WaveOut using the default device. To reduce this, switch the WaveOut to a DirectSound device. This both smooths out the control events and reduces the latency. When there are many HID objects in a circuit, only one of them will be reading data from the devices. The rest of the objects simply point at the same data. If it is necessary to reduce the CPU clock cycles used by HID, turn off any controls that are not being used. Unknown USB Devices Not all HID devices fully implement the USB/HID recommended practices. While ABox attempts to recognize partially compliant devices, it will ignore those that do not report their data formats. HID Edit is a technical tool designed to deduce the data formats of HID devices. While it requires knowledge of bits and number formats, using HID Edit makes it possible to define parameters for just about any HID device. It can then store formatting information in the Windows registry for use by ABox. The HID Edit software, help and example registry strings can be found at http://www.andyware.com/hidedit/index.html