VDJPedia



 ControllerDefinitionHID

Controller Definition HID in Version 7


The Controller Definition File for a HID controller is a XML file installed in the folder MyDocuments/VirtualDJ/Devices/ on PC or /users/YOURNAME/Documents/VirtualDJ/Devices/ on Mac, with these properties:

the root element of the xml must be <device>, with these properties:
- name: unique string that identifies the controller, as will be used in the mapper
- author: (optional) name of the author of this xml file
- type: must be "HID"
- decks: can be "1" if the controller represents one deck, or "2" for dual-deck, "4" for 4 deck, etc.
- vid: VendorID of the device
- pid: ProductID of the device
- reportsize: size of the report pages in bytes (default 32)
- outreportsize: (optional) if different, size of the output pages in bytes

The <device> element have child elements <page>, with these properties:
- type: can be "in", "out", "packets", "init", "wait" or "exit"
- pagesize: (optional) if different, report page size in bytes

example:
<?xml version="1.0" encoding="UTF-8"?>
<device name="MYCONTROLLER" author="Me" type="HID" decks="1" vid="0x1234" pid="0x0100" reportsize="32">
<page type="in">
...
</page>
<page type="out">
...
</page>
</device>



HID devices tool
http://www.virtualdj.com/download/hidtrace.exe


Each button, slider, knob, LED, LCD, etc, will be defined by a child item of the <page> element.
All elements (except <constant>) can implement these properties:
- name: the name of this element, as will be used in the mapper
- deck: (optional) the deck on which this element apply, if the device controls two decks

All elements also have properties that defines their position and length inside the page report.
The position can be defined by one of these properties:
- bit: gives the position in number of bits since the beginning of the page (1 bit = 0 or 1)
- byte: gives the position in number of bytes since the beginning of the page (1 byte = 8 bits)
- word: gives the position in number of words since the beginning of the page (1 word = 2 bytes = 16 bits)
- dword: gives the position in number of dwords since the beginning of the page (1 dword = 2 words = 4 bytes = 32 bits)

If the number of bits taken by the element in the report is different than the size implied by the method used to give the position, you can specify the size by one of these properties:
- nbbits: (optional) specifically gives the number of bits
- size: (optional) can be "bit", "byte", "word", "dword"

If the size is greater or equal to "word", you can specify this property:
- endian: (optional) can be "little" or "big" (default is "big")


Pages IN

Pages "IN" are HID report pages sent by the device on the HID port.

If your device sends more than one report page, you must differentiate the pages using a <constant> element.
When VirtualDJ receives the HID report, it will use the first <page> element where all <constant> elements match the content of the report.

Constants
The <constant> element can have one of these properties:
- text: specifies the content of the constant with a text string.
- buffer: specifies the content of the constant with an hexadecimal buffer (like "010203040A0B0C")
- value: specifies the content of the constant with a value

Buttons
A button is defined by a <button> element, with the following properties:
- value: (optional) specify the value the element should match
- inverted: (optional) set to "true" if the bit is 0 when pressed and "value" when released

example:
<button bit="42" name="PLAY" />


If the button does not change the report value on pushed/released, but on on/off, you can use a <toggle> element with the following properties:
- value: (optional) specify the value the element should match
- inverted: (optional) set to "true" if the bit is 0 when activated and "value" when deactivated

Sliders
A slider is defined by a <slider> element, with the following properties:
- min: defines the value for 0% (default: 0)
- max: defines the value for 100% (default: maximum allowed by nbbits)
- signed: (optional) if "true", the value is a signed value
- inverted: (optional) set to "true" if the slider is bottom-up
- vibration: (optional) defines a delta value under which changes are not reported
- zerorange: (optional) if value is closer than zerorange from 50%, it will be set to 50%

example:
<slider word="2" endian="little" max="1000" name="VOLUME" />


Jog Wheels
A jog wheel is defined by a <jog> element, with the following properties:
- full: gives the number of steps to perform a full rotation
- min: (optional) defines the minimum value
- max: (optional) defines the maximum value, just before it wraps back to the minimum value
- inverted: (optional) set to "true" if the jogwheel is inverted
- vibration: (optional) defines a delta value under which changes are not reported

example:
<jog byte="19" size="word" full="300" name="JOGWHEEL" deck="1" />


Encoders
An encoder is defined by a <encoder> element, with the following properties:
- min: (optional) defines the minimum value
- max: (optional) defines the maximum value, just before it wraps back to the minimum value
- inverted: (optional) set to "true" if the encoder is inverted
- vibration: (optional) defines a delta value under which changes are not reported

Actions
You can put an <action> elements with the usual position, size and name properties.
The mapper for this name will be called every times the report page containing this <action> is received.


Pages OUT

Pages "OUT" are HID report pages that the application can send to the device on the HID port.

If the report page needs to have some specific headers to identify the page, you can use <constant> elements, as described in the Pages IN section.
(for Hercules DJConsole RMX, Hercules DJControl MP3 where ReportID equals 1, please use <constant byte="-1" value="0x01"/>)

LEDs
a LED is defined by a <led> element, with the following properties:
- value: (optional) the value to set this element to when the LED is on
- default: (optional) gives the name of the corresponding <button> element. If the mapper doesn't specifically provide an action for this LED, the action of the button will automatically be used to get the state of the LED.

example:
<led bit="0x42" name="LED_PLAY" default="PLAY" deck="1" />


Digits
Digits on a LCD are defined by a <digit> element, with the following properties:
- enablebit: (optional) specify the position in bits from the beginning of the page of a bit to set to 0 when there is no digits to display and 1 when there is.
- enablebit2: (optional) specify the position in bits from the beginning of the page of another bit to set to 0 when there is no digits to display and 1 when there is (can be used to activate LCD sign related to these digits).
- dotbit: (optional) specify the position in bits from the beginning of the page of a bit to set to 1 if the value to display is not an integer. The value will be multiplied by 10 before being sent to the digit.
- dotbit2: (optional) specify the position in bits from the beginning of the page of a bit to set to 1 if the value to display is not an integer. The value will be multiplied by 100 before being sent to the digit.
- plusbit: (optional) specify the position in bits from the beginning of the page of a bit to set to 1 if the value to display is positive.
- minusbit: (optional) specify the position in bits from the beginning of the page of a bit to set to 1 if the value to display is negative.
- min: (optional) set a minimum for the value.
- max: (optional) set a maximum for the value.

Text displays
Text displays are defined by a <text> element, with the following properties:
- nbchars: the number of characters
- enablebit: (optional) specify the position in bits from the beginning of the page of a bit to set to 0 when the text is empty and to 1 when it's not.
- encoding: (optional) the encoding to use (can be "utf8", "utf16", "iso-8859-1", "ascii", etc)
- scroll: set to "false" to prevent the display from scrolling too long strings (default is "yes")

Progress bars and VUE meters
Progress bars are defined by a <bar> element, with the following properties:
- min: (optional) value to write for 0%
- max: (optional) value to write for 100%
- enablebit: (optional) specify the position in bits from the beginning of the page of a bit to set to 0 when the bar is empty and to 1 when it's not.
- enablebit2: (optional) specify the position in bits from the beginning of the page of another bit to set to 0 when the bar is empty and to 1 when it's not.
- minusbit: (optional) specify the position in bits from the beginning of the page of a bit to set to 1 when the value is negative and 0 when it's positive.

Alternatively, progress bars can be defined as a buffer of binary bits.
For this, use a <bar> element with the following properties:
- type: if set to "bitfill" the buffer will progressively fill with 1s. If set to "bitmove", the buffer will have only one 1 moving through the buffer.
- inverted: (optional) invert the direction of the buffer.


Other Pages

Pages defined with the type "init" will be sent to the HID port when the device is initialized.
The pages will be sent in the order they appear in the XML.
You can use <constant> elements to fill the page, as defined in Pages IN.

If a page has the type "wait", the device will not start until this page has been received, after all the "init" pages have been sent.

Pages defined with the type "exit" will be sent when the device is exited.


Go Back to Controller Definition Wiki page

Wiki HOME